Add deploy notes and env explanation

Dockerfile

@@ -5,12 +5,15 @@ WORKDIR /app
 
 COPY update.py /app/update.py
 COPY entrypoint.sh /app/entrypoint.sh
+COPY healthcheck.sh /app/healthcheck.sh
 
 RUN pip install --no-cache-dir requests==2.32.3 \
-  && chmod +x /app/entrypoint.sh
+  && chmod +x /app/entrypoint.sh /app/healthcheck.sh
 
 ENV OUT_DIR=/data
 VOLUME ["/data"]
 
 ENTRYPOINT ["/app/entrypoint.sh"]
 
+HEALTHCHECK --interval=5m --timeout=10s --start-period=30s --retries=3 \
+  CMD /app/healthcheck.sh

README.md

@@ -1,15 +1,64 @@
 # education-flagger
 
-Dieses Repo nutzt MaxMind und damit indirekt die Datenbank von PeeringDB um HTTP Anfragen in kurzer Zeit mit Header zu versehen die Aufschluss darauf geben, ob sich der Client in einem Research and Education Netwerk (Eduroam) von DFN, GÉANT, SWITCH oder RENATER befindet. 
-Forschung und Bildung ist die wichtigste Investition in die Zukunft.
+Forschung und Bildung sind die wichtigste Investition in die Zukunft, und der Zugang zu ihren Netzwerken verdient besondere Unterstützung.
 
-**Middleware zum Anreichern von Header um Research Netzwerke zu erkennen**
+Dieses Repo stellt einen **minimalen Microservice** bereit, um **Hochschul- und Forschungsnetzwerke (NRENs)** anhand der **Autonomous System Number (ASN)** zu erkennen. Ziel ist es, **Zugriff oder bevorzugte Behandlung** für Nutzer aus Research- und Education-Netzen zu ermöglichen, ohne personenbezogene Daten zu verarbeiten.
 
-Die Middleware wird durch den Service genutzt und registriert. 
+Das System dient ausschließlich der **Netzwerk-Klassifikation** und **ersetzt keine Authentifizierung**.
+
+## Ziel
+
+- Erkennen, ob eine Anfrage aus einem **Hochschul- oder Forschungsnetz** stammt
+- Bereitstellung eines **Header-Hinweises** für nachgelagerte Services
+- Grundlage für Entscheidungen wie:
+  - kostenfreie Research-Features
+  - angepasste UI-Hinweise
+  - alternative Rate-Limits
+
+## Funktionsweise (Kurzfassung)
+
+```
+Client
+  -> Traefik
+    -> ForwardAuth
+      -> ASN Detection Service
+        -> Header wird ergänzt
+```
+
+1. Die Client-IP wird ermittelt
+2. Die zugehörige ASN wird lokal nachgeschlagen
+3. Die ASN wird mit einer NREN-ASN-Liste verglichen
+4. Das Ergebnis wird als HTTP-Header zurückgegeben
+
+## Datenquellen
+
+- **GeoLite2 ASN (MaxMind)**
+  - kostenlos
+  - lokal
+  - monatliche Aktualisierung
+
+- **NREN-ASN-Liste**
+  - abgeleitet aus PeeringDB
+  - Kategorie: `Research and Education`
+  - monatliche Aktualisierung
+
+## Bereitgestellte Header
+
+| Header | Beschreibung |
+|------|-------------|
+| `X-ASN` | ASN der Client-IP |
+| `X-ASN-ORG` | Organisation (optional) |
+| `X-NREN` | `1` wenn ASN zu einem Hochschul-/Forschungsnetz gehört, sonst `0` |
+
+## Integration
+
+Der Service wird als **Traefik ForwardAuth Middleware** eingebunden.  
+Die Header werden über `authResponseHeaders` an die eigentliche Anwendung weitergereicht.
+
+Der Service ist **nicht öffentlich exponiert** und kommuniziert ausschließlich über das interne Docker-Netzwerk.
 
 Die dafür vorgesehenen Labels sind:
 
-
       # Middleware Definition (ForwardAuth -> asn-header)
       - "traefik.http.middlewares.asn-enrich.forwardauth.address=http://asn-header:8080/auth"
       - "traefik.http.middlewares.asn-enrich.forwardauth.trustForwardHeader=true"
@@ -19,3 +68,35 @@ Die dafür vorgesehenen Labels sind:
       - "traefik.http.routers.web.middlewares=asn-enrich@docker"
 
 Bitte füge diese zu dem Service hinzu, bei welchem man die gewünschten Header möchte.
+
+## Run/Deploy (kurz)
+
+1. `example.env` kopieren und als `.env` befüllen (mindestens `MAXMIND_LICENSE_KEY`).
+2. Den Updater-Container starten und `OUT_DIR` als Volume mounten (z. B. `/data`).
+3. Den ASN-Detection-Service so starten, dass er **denselben** `OUT_DIR` liest.
+4. Traefik ForwardAuth aktivieren und `authResponseHeaders` durchreichen.
+5. Nach dem ersten Update sollten `GeoLite2-ASN.mmdb` und `nren_asns.txt` im `OUT_DIR` liegen.
+
+## example.env (kurz erklärt)
+
+- `MAXMIND_LICENSE_KEY`: notwendig für den GeoLite2 Download.
+- `PDB_API_KEY`: optional, reduziert PeeringDB Rate-Limits.
+- `OUT_DIR`: gemeinsamer Datenpfad zwischen Updater und Detection-Service.
+- `PDB_BASE`, `PDB_INFO_TYPE`, `PDB_LIMIT`: PeeringDB Filter.
+- `HTTP_TIMEOUT`: Timeout pro HTTP-Request.
+- `INTERVAL_SECONDS`: Update-Intervall (Standard 30 Tage).
+
+## Update-Strategie
+
+- monatliche Aktualisierung der ASN-Daten
+- keine externen Requests während der Anfrageverarbeitung
+
+## Einschränkungen
+
+- Die Erkennung ist **heuristisch**
+- Es gibt **keine Garantie**, dass jede Anfrage aus einem Hochschulnetz erkannt wird
+- Die Information darf **nicht als Authentifizierungsmerkmal** verwendet werden
+
+## Zusammenfassung
+
+Dieses Projekt ermöglicht eine **performante, datenschutzfreundliche Erkennung von Hochschulnetzen**, um **Research-Angebote kontextabhängig bereitzustellen**, ohne Nutzer zu identifizieren oder externe Dienste zur Laufzeit zu kontaktieren.

example.env

@@ -0,0 +1,19 @@
+# Required
+MAXMIND_LICENSE_KEY=
+
+# Optional (helps with rate limits)
+PDB_API_KEY=
+
+# Output data location shared with the detection service
+OUT_DIR=/data
+
+# PeeringDB settings
+PDB_BASE=https://www.peeringdb.com
+PDB_INFO_TYPE=Educational/Research
+PDB_LIMIT=250
+
+# HTTP settings
+HTTP_TIMEOUT=30
+
+# Update interval (seconds, default 30 days)
+INTERVAL_SECONDS=2592000

healthcheck.sh

@@ -0,0 +1,49 @@
+#!/bin/sh
+set -eu
+
+OUT_DIR="${OUT_DIR:-/data}"
+PDB_BASE="${PDB_BASE:-https://www.peeringdb.com}"
+INFO_TYPE="${PDB_INFO_TYPE:-Educational/Research}"
+
+if [ -z "${MAXMIND_LICENSE_KEY:-}" ]; then
+  echo "[health] MAXMIND_LICENSE_KEY missing" >&2
+  exit 1
+fi
+
+if [ ! -d "${OUT_DIR}" ]; then
+  echo "[health] OUT_DIR missing: ${OUT_DIR}" >&2
+  exit 1
+fi
+
+if [ ! -s "${OUT_DIR}/GeoLite2-ASN.mmdb" ]; then
+  echo "[health] GeoLite2-ASN.mmdb missing in ${OUT_DIR}" >&2
+  exit 1
+fi
+
+if [ ! -s "${OUT_DIR}/nren_asns.txt" ]; then
+  echo "[health] nren_asns.txt missing in ${OUT_DIR}" >&2
+  exit 1
+fi
+
+mm_url="https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-ASN&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz"
+mm_code="$(curl -fsS -o /dev/null -w "%{http_code}" "${mm_url}" || true)"
+if [ "${mm_code}" != "200" ]; then
+  echo "[health] MaxMind download not accessible (status ${mm_code})" >&2
+  exit 1
+fi
+
+pdb_code="000"
+pdb_url="${PDB_BASE}/api/net"
+pdb_args="--get --data-urlencode info_type=${INFO_TYPE} --data-urlencode limit=1 --data-urlencode skip=0 --data-urlencode fields=asn,status,info_type"
+if [ -n "${PDB_API_KEY:-}" ]; then
+  pdb_code="$(curl -fsS -o /dev/null -w "%{http_code}" -H "Accept: application/json" -H "Authorization: Api-Key ${PDB_API_KEY}" ${pdb_args} "${pdb_url}" || true)"
+else
+  pdb_code="$(curl -fsS -o /dev/null -w "%{http_code}" -H "Accept: application/json" ${pdb_args} "${pdb_url}" || true)"
+fi
+
+if [ "${pdb_code}" != "200" ] && [ "${pdb_code}" != "429" ]; then
+  echo "[health] PeeringDB not accessible (status ${pdb_code})" >&2
+  exit 1
+fi
+
+exit 0

update.py

@@ -5,7 +5,7 @@ OUT_DIR = os.getenv("OUT_DIR", "/data")
 LICENSE_KEY = os.getenv("MAXMIND_LICENSE_KEY", "").strip()
 PDB_API_KEY = os.getenv("PDB_API_KEY", "").strip()
 PDB_BASE = os.getenv("PDB_BASE", "https://www.peeringdb.com")
-INFO_TYPE = os.getenv("PDB_INFO_TYPE", "Research and Education")
+INFO_TYPE = os.getenv("PDB_INFO_TYPE", "Educational/Research")
 TIMEOUT = int(os.getenv("HTTP_TIMEOUT", "30"))
 LIMIT = int(os.getenv("PDB_LIMIT", "250"))
 
@@ -49,7 +49,7 @@ def pdb_headers():
     if not PDB_API_KEY:
         return {"Accept": "application/json"}
     # PeeringDB API Key (optional)
-    return {"Accept": "application/json", "Authorization": f"api-key {PDB_API_KEY}"}
+    return {"Accept": "application/json", "Authorization": f"Api-Key {PDB_API_KEY}"}
 
 def fetch_pdb_page(skip: int):
     url = f"{PDB_BASE}/api/net"
@@ -105,4 +105,3 @@ def main():
 
 if __name__ == "__main__":
     main()
-