From 3706832a88dafb50180f8adcb325478dc30f4a3a Mon Sep 17 00:00:00 2001
From: Daniel Rocha <68558152+danroc@users.noreply.github.com>
Date: Fri, 1 Nov 2024 23:05:35 +0100
Subject: [PATCH] docs: update README

---
 README.md | 140 ++++++++++++++++++------------------------------------
 1 file changed, 47 insertions(+), 93 deletions(-)

diff --git a/README.md b/README.md
index 41d412d..1dd2270 100644
--- a/README.md
+++ b/README.md
@@ -1,105 +1,28 @@
 # Geoblock
 
 Geoblock is a lightweight authorization service designed to control access to
-services based on customizable rules.
-
-It enables blocking or allowing access based on various criteria, providing
-enhanced control over service access.
-
-## Rules
-
-Access can be controlled based on the following criteria:
+services based on the following criteria:
 
 - Client country
-- Client autonomous system number (ASN)
 - Client IP address
+- Client ASN (Autonomous System Number)
 - Requested domain
 
-Various criteria can be combined in a single rule, allowing for fine-grained
-access control.
+Various criteria can be combined in a single **rule**, allowing for
+fine-grained access control.
 
 Rules are tested in order, and the first rule that matches the request is
 applied. If no rule matches, the default policy is applied.
 
-### Examples
-
-Here are some examples of rules:
-
-1. Allow access from private networks:
-
-   ```yaml
-   - networks:
-       - 10.0.0.0/8
-       - 127.0.0.0/8
-       - 172.16.0.0/12
-       - 192.168.0.0/16
-     policy: allow
-   ```
-
-2. Block access from a specific country:
-
-   ```yaml
-   - countries:
-       - FR
-     policy: block
-   ```
-
-3. Allow access from a specific country to a list of domains:
-
-   ```yaml
-   - countries:
-       - FR
-     domains:
-       - example.com
-       - example.org
-     policy: allow
-   ```
-
-4. Block access from a specific ASN:
-
-   ```yaml
-   - asns:
-       - 1234
-     policy: block
-   ```
-
-## Deployment
-
-Here is an example of how to deploy Geoblock using Docker Compose with Traefik.
-
-```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
-```
-
-## Configuration file
+## Configuration
 
 Geoblock has a single configuration file that defines the access control rules
-to apply. Its default location is `config.yaml` in the same directory as the
-binary.
+to apply. Its default location is `./config.yaml`, relative to the `geoblock`
+binary file.
+
+Here is an example configuration file:
 
 ```yaml
-# config.yaml
 ---
 access_control:
   # Default policy to apply when no rules match, possible values are "allow"
@@ -110,13 +33,13 @@ access_control:
   # matches, the policy defined in the rule is applied. If no rule matches, the
   # default policy is applied.
   rules:
-    # Example: allow access to example.com and example.org
+    # Allow access to example.com and example.org
     - domains:
         - example.com
         - example.org
       policy: allow
 
-    # Example: allow access from private networks
+    # Allow access from private networks
     - networks:
         - 10.0.0.0/8
         - 127.0.0.0/8
@@ -124,18 +47,18 @@ access_control:
         - 192.168.0.0/16
       policy: allow
 
-    # Example: deny access for clients from ASNs 1234 and 5678
+    # Deny access for clients from ASNs 1234 and 5678
     - autonomous_systems:
         - 1234
         - 5678
       policy: deny
 
-    # Example: allow access from France
+    # Allow access from France
     - countries:
         - FR
       policy: allow
 
-    # Example: allow access from France and the US to example.com
+    # Allow access from France and the US to example.com
     - domains:
         - example.com
       countries:
@@ -144,12 +67,43 @@ access_control:
       policy: allow
 ```
 
+## Deployment
+
+### Traefik
+
+```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
+```
+
 ## Environment variables
 
 The following environment variables can be used to configure Geoblock:
 
-- `GEOBLOCK_CONFIG`: Path to the configuration file (default: `config.yaml`).
-- `GEOBLOCK_PORT`: Port to listen on (default: `8080`).
+| Variable          | Description                    | Default       |
+| :---------------- | :----------------------------- | :------------ |
+| `GEOBLOCK_CONFIG` | Path to the configuration file | `config.yaml` |
+| `GEOBLOCK_PORT`   | Port to listen on              | `8080`        |
 
 ## Manual testing