Own repository (was images/geoauth in srv): README, build from the repository root...

diff --git a/Dockerfile b/Dockerfile
index 44f5d27..894d637 100644 (file)
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,12 +1,12 @@
 # syntax=docker/dockerfile:1
 #
-# geoauth: the country forward-auth for the public ingress. Built by the Tekton pipeline `geoauth` (k8s/clusters/dev/ci/pipeline-geoauth.yaml)
-# when a tag geoauth-vX.Y.Z is pushed to srv; the image is registry.home.muszr.me/geoauth:vX.Y.Z.
+# geoauth: the country forward-auth for the public ingress. Built by the Tekton pipeline `geoauth` when a tag vX.Y.Z is pushed
+# to this repository; the image is registry.home.muszr.me/geoauth:vX.Y.Z.
 #
 #   checks   go vet and go test (fails the build)
 #   geoauth  the runtime image: a static binary and the CA bundle in scratch, no shell, no package manager, uid/gid 65532
 #
-#   docker build --target geoauth -t geoauth images/geoauth        (any target works locally too)
+#   docker build --target geoauth -t geoauth .        (any target works locally too)
 
 ARG ALPINE=alpine:edge
 

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..68f1a89
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# geoauth
+
+A [Traefik](https://traefik.io) forward-auth service that admits HTTP clients by country.
+
+Traefik asks it about every request (a `forwardAuth` middleware), passing the client address in `X-Forwarded-For`. geoauth
+answers `200` (admit) or `403` ("this service is not available in your region").
+
+- **Data:** the Regional Internet Registries' public allocation files (ARIN, RIPE NCC, APNIC, LACNIC, AFRINIC). No
+  third-party database, no account, nothing is sent anywhere. Refreshed daily; the last good copy is kept when a refresh fails.
+- **Always admitted:** private, loopback and link-local addresses, and anything in `ALLOW_CIDRS`.
+- **Fails closed:** until the first successful load it answers `503` and admits no public address.
+- **Small:** one Go file, standard library only; the image is a static binary plus the CA bundle in `scratch`, running as
+  uid 65532.
+
+## Configuration
+
+Environment variables:
+
+| Variable      | Default                       | Meaning                                                     |
+| ------------- | ----------------------------- | ----------------------------------------------------------- |
+| `COUNTRIES`   | `US`                          | ISO 3166 codes to admit, comma-separated (e.g. `US,CA`)     |
+| `ALLOW_CIDRS` | (none)                        | extra ranges to admit regardless of country, comma-separated |
+| `SOURCES`     | the five RIR files            | allocation files to load, comma-separated URLs              |
+| `REFRESH`     | `24h`                         | how often to reload them                                    |
+| `LISTEN`      | `[::]:8080`                   | listen address                                              |
+
+Health: `/healthz` and `/readyz` (both `503` until the data is loaded). Prometheus metrics: `/metrics`.
+
+## Build
+
+```sh
+docker build --target checks .            # go vet and go test
+docker build --target geoauth -t geoauth .
+```
+
+## Traefik
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata: {name: country-gate}
+spec:
+  forwardAuth:
+    address: http://geoauth.<namespace>.svc:8080/
+```