docs: add Traefik deployment example (#27)

README.md

@@ -5,8 +5,7 @@
 
 - [Introduction](#introduction)
 - [Configuration](#configuration)
-- [Installation](#installation)
-  - [With Traefik](#with-traefik)
+- [Deployment](#deployment)
 - [HTTP API](#http-api)
   - [`GET /v1/forward-auth`](#get-v1forward-auth)
   - [`GET /v1/health`](#get-v1health)
@@ -26,6 +25,9 @@ based on:
 - Requested domain
 - Requested method
 
+It works as a forward-authentication service that can be used with reverse
+proxies such as Traefik, NGINX, and Caddy.
+
 ## Configuration
 
 Geoblock uses a single configuration file (`config.yaml` by default) to set
@@ -83,34 +85,9 @@ access_control:
       policy: allow
 ```
 
-## Installation
-
-### With Traefik
+## Deployment
 
-```yaml
-# compose.yaml
----
-services:
-  traefik:
-    # Traefik configuration...
-
-  geoblock:
-    image: ghcr.io/danroc/geoblock:latest
-    container_name: geoblock
-    networks:
-      - proxy
-    volumes:
-      - ./config.yaml:/app/config.yaml
-    labels:
-      - traefik.enable=true
-      - traefik.http.middlewares.geoblock.forwardauth.address=http://geoblock:8080/v1/forward-auth
-      - traefik.http.middlewares.geoblock.forwardauth.trustForwardHeader=true
-    restart: unless-stopped
-
-networks:
-  proxy:
-    external: true
-```
+- [Example using Traefik](./examples/traefik/README.md)
 
 ## HTTP API
 

examples/traefik/README.md

@@ -0,0 +1,62 @@
+# Traefik Example
+
+## Deploying
+
+Run `docker compose up` to start the following services defined in the
+[`compose.yaml`](./compose.yaml) file:
+
+- `whoami-1`: Example service (allowed)
+- `whoami-2`: Example service (blocked)
+- `geoblock`: Geoblock service
+- `traefik`: Reverse proxy and load balancer
+
+This example will use the configuration defined in the
+[`config.yaml`](./config.yaml) file.
+
+## Testing
+
+In a different console, use `curl` to test the services:
+
+**✅ Allowed:**
+
+HTTP request and response:
+
+```bash
+$ curl -fH "Host: whoami-1.local" http://localhost:8080
+Hostname: 99704d18aa93
+IP: 127.0.0.1
+IP: 172.18.0.4
+RemoteAddr: 172.18.0.5:56060
+GET / HTTP/1.1
+Host: whoami-1.local
+User-Agent: curl/8.7.1
+Accept: */*
+Accept-Encoding: gzip
+X-Forwarded-For: 172.18.0.1
+X-Forwarded-Host: whoami-1.local
+X-Forwarded-Port: 80
+X-Forwarded-Proto: http
+X-Forwarded-Server: 750f0338632d
+X-Real-Ip: 172.18.0.1
+```
+
+Geoblock logs:
+
+```log
+geoblock-1  | time="2024-11-19T19:12:40Z" level=info msg="Request authorized" requested_domain=whoami-1.local requested_method=GET source_asn=0 source_country= source_ip=172.18.0.1 source_org=
+```
+
+**❌ Blocked:**
+
+HTTP request and response:
+
+```bash
+curl -fH "Host: whoami-2.local" http://localhost:8080
+curl: (22) The requested URL returned error: 403
+```
+
+Geoblock logs:
+
+```log
+geoblock-1  | time="2024-11-19T19:12:41Z" level=warning msg="Request denied" requested_domain=whoami-2.local requested_method=GET source_asn=0 source_country= source_ip=172.18.0.1 source_org=
+```

examples/traefik/compose.yaml

@@ -0,0 +1,33 @@
+---
+services:
+  whoami-1:
+    image: traefik/whoami:latest
+    labels:
+      - "traefik.http.routers.whoami-1.rule=Host(`whoami-1.local`)"
+
+  whoami-2:
+    image: traefik/whoami:latest
+    labels:
+      - "traefik.http.routers.whoami-2.rule=Host(`whoami-2.local`)"
+
+  geoblock:
+    image: ghcr.io/danroc/geoblock:latest
+    volumes:
+      - ./config.yaml:/app/config.yaml
+
+  traefik:
+    image: traefik:v3
+    ports:
+      - "8080:80"
+    depends_on:
+      - geoblock
+    labels:
+      - "traefik.http.middlewares.geoblock.forwardauth.address=http://geoblock:8080/v1/forward-auth"
+      - "traefik.http.middlewares.geoblock.forwardauth.trustForwardHeader=true"
+    command:
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.web.http.middlewares=geoblock@docker"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock

examples/traefik/config.yaml

@@ -0,0 +1,11 @@
+---
+access_control:
+  default_policy: deny
+  rules:
+    - domains:
+        - whoami-1.local
+      policy: allow
+
+    - domains:
+        - whoami-2.local
+      policy: deny