Add containerized geoipupdate to Docker setup

- Add geoipupdate service to docker-compose.yml using ghcr.io/maxmind/geoipupdate
- Credentials supplied via .env file (MAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY)
- GeoIP databases stored in named volume 'geoip-data', mounted read-only by monitor
- Removed GeoIP mount from web service (not needed)
- GEOIPUPDATE_FREQUENCY=168 (weekly, matching MaxMind's Tuesday release schedule)
- Add .env.example for credential setup
- Update INSTALL.md: MaxMind credentials as prerequisite, Docker section uses
  containerized geoipupdate, systemd sections retain host geoipupdate + cron

Author: djkurlander

.env.example

@@ -0,0 +1,5 @@
+# MaxMind GeoIP credentials
+# Get a free account at https://www.maxmind.com/en/geolite2/signup
+# Then generate a license key in your account dashboard.
+MAXMIND_ACCOUNT_ID=your_account_id
+MAXMIND_LICENSE_KEY=your_license_key

INSTALL.md

@@ -32,42 +32,13 @@ ssh -p 2222 user@your-server
 
 You must open up your firewall (if present) to expose ports 22, 80 or 443, and potentially your real SSH port. This is specific to your network configuration, so the exact steps are not presented here.
 
-### GeoIP Databases
+### MaxMind Account (GeoIP)
 
 Knock-Knock uses MaxMind GeoLite2 databases for IP geolocation. You need a free MaxMind account.
 
-1. Install geoipupdate:
-
-**Debian/Ubuntu:**
-```bash
-apt install -y geoipupdate
-```
-
-**RHEL/CentOS/Fedora:**
-```bash
-dnf install -y geoipupdate
-```
-
-2. Create a free account at https://www.maxmind.com/en/geolite2/signup
-3. Generate a license key in your account dashboard. Either download the config file and save it as `/etc/GeoIP.conf`, or edit the existing `/etc/GeoIP.conf` (created by the install) and add your `AccountID` and `LicenseKey`.
-
-Then download the databases:
-```bash
-geoipupdate
-
-# Ensure databases are at /usr/share/GeoIP (some distros use /var/lib/GeoIP)
-[ ! -e /usr/share/GeoIP ] && ln -s /var/lib/GeoIP /usr/share/GeoIP
-
-# Verify
-ls /usr/share/GeoIP/GeoLite2-*.mmdb
-```
-
-Set up weekly auto-updates:
-```bash
-crontab -e
-# Add line:
-0 3 * * 3 /usr/bin/geoipupdate
-```
+1. Register at https://www.maxmind.com/en/geolite2/signup
+2. In your account dashboard, generate a license key
+3. Note your **Account ID** and **License Key** — you'll need them below
 
 ### SSH Host Key (Systemd Only)
 
@@ -91,40 +62,43 @@ Complete the [Prerequisites](#prerequisites) above first (skip the SSH Host Key
 curl -fsSL https://get.docker.com | sh
 ```
 
-### Using the Pre-built Image (Recommended)
-
-A multi-arch image (amd64 + arm64) is published to GitHub Container Registry. You only need the `docker-compose.yml` file:
+### Clone the Repository
 
 ```bash
 cd /root
 git clone https://github.com/djkurlander/knock-knock.git
 cd knock-knock
-
-# Pull and start (uses pre-built image from ghcr.io)
-docker compose up -d
 ```
 
-### Building Locally
-
-If you prefer to build from source:
+### Configure MaxMind Credentials
 
 ```bash
-cd /root
-git clone https://github.com/djkurlander/knock-knock.git
-cd knock-knock
+cp .env.example .env
+nano .env   # Fill in your Account ID and License Key
+```
+
+### Start
 
-# Build and start from Dockerfile
-docker compose up -d --build
+```bash
+# Pull and start (uses pre-built image from ghcr.io)
+docker compose up -d
 ```
 
+The `geoipupdate` container downloads the GeoIP databases on first start and refreshes them weekly. The monitor waits until the databases are ready before processing knocks — you'll see `⏳ Waiting for GeoIP databases...` in the logs until the download completes.
+
 ### Verify
 
 ```bash
-docker compose logs honeypot-monitor   # Should show "Monitor Active"
-docker compose logs web                # Should show uvicorn startup
+docker compose logs -f honeypot-monitor
+# Should show:
+#   ⏳ Waiting for GeoIP databases...  (briefly, during first-time download)
+#   ✅ GeoIP databases loaded
+#   🚀 Maximalist Monitor Active...
+
+docker compose logs web   # Should show uvicorn startup
 ```
 
-That's it. Three containers (Redis, honeypot+monitor, web) start automatically and restart on failure.
+That's it. Four containers (Redis, geoipupdate, honeypot+monitor, web) start automatically and restart on failure.
 
 **Useful commands:**
 ```bash
@@ -142,6 +116,35 @@ See [Optional Configuration](#optional-configuration) for various site-specific
 
 Complete the [Prerequisites](#prerequisites) above first.
 
+### GeoIP Databases
+
+```bash
+apt install -y geoipupdate
+```
+
+Configure your MaxMind credentials in `/etc/GeoIP.conf`:
+```
+AccountID your_account_id
+LicenseKey your_license_key
+DatabaseDirectory /usr/share/GeoIP
+```
+
+Download the databases and set up weekly auto-updates (MaxMind updates databases every Tuesday):
+```bash
+geoipupdate
+
+# Ensure databases are at /usr/share/GeoIP (some distros use /var/lib/GeoIP)
+[ ! -e /usr/share/GeoIP ] && ln -s /var/lib/GeoIP /usr/share/GeoIP
+
+# Verify
+ls /usr/share/GeoIP/GeoLite2-*.mmdb
+
+# Weekly auto-update
+crontab -e
+# Add line:
+0 3 * * 3 /usr/bin/geoipupdate
+```
+
 ### System Dependencies
 
 ```bash
@@ -199,6 +202,32 @@ See [Optional Configuration](#optional-configuration) for various site-specific
 
 Complete the [Prerequisites](#prerequisites) above first.
 
+### GeoIP Databases
+
+```bash
+dnf install -y geoipupdate
+```
+
+Configure your MaxMind credentials in `/etc/GeoIP.conf`:
+```
+AccountID your_account_id
+LicenseKey your_license_key
+DatabaseDirectory /usr/share/GeoIP
+```
+
+Download the databases and set up weekly auto-updates (MaxMind updates databases every Tuesday):
+```bash
+geoipupdate
+
+# Verify
+ls /usr/share/GeoIP/GeoLite2-*.mmdb
+
+# Weekly auto-update
+crontab -e
+# Add line:
+0 3 * * 3 /usr/bin/geoipupdate
+```
+
 ### System Dependencies
 
 ```bash
@@ -311,7 +340,16 @@ ss -tlnp | grep :22
 # Make sure real SSH is moved to another port first
 ```
 
-### GeoIP lookups failing
+### GeoIP lookups returning Unknown (Docker)
+```bash
+docker compose logs honeypot-monitor | grep -i geoip
+# Should show "✅ GeoIP databases loaded"
+# If stuck on "⏳ Waiting...", check geoipupdate logs:
+docker compose logs geoipupdate
+# Verify credentials in .env are correct
+```
+
+### GeoIP lookups failing (Systemd)
 ```bash
 ls -la /usr/share/GeoIP/GeoLite2-*.mmdb
 # If missing, ensure /etc/GeoIP.conf includes: DatabaseDirectory /usr/share/GeoIP
@@ -343,7 +381,7 @@ sqlite3 /root/knock-knock/data/knock_knock.db "SELECT * FROM knocks ORDER BY id
 # Reset all data (clear database and Redis)
 ./restart.sh --reset-all
 
-# Update GeoIP databases
+# Update GeoIP databases (systemd only — Docker handles this automatically)
 geoipupdate
 
 # Rotate SSL certs (if using Let's Encrypt)

docker-compose.yml

@@ -5,6 +5,17 @@ services:
       - redis-data:/data
     restart: unless-stopped
 
+  geoipupdate:
+    image: ghcr.io/maxmind/geoipupdate
+    environment:
+      - GEOIPUPDATE_ACCOUNT_ID=${MAXMIND_ACCOUNT_ID}
+      - GEOIPUPDATE_LICENSE_KEY=${MAXMIND_LICENSE_KEY}
+      - 'GEOIPUPDATE_EDITION_IDS=GeoLite2-ASN GeoLite2-City'
+      - GEOIPUPDATE_FREQUENCY=168
+    volumes:
+      - geoip-data:/usr/share/GeoIP
+    restart: unless-stopped
+
   honeypot-monitor:
     image: ghcr.io/djkurlander/knock-knock:latest
     build: .  # Used when running: docker compose up --build
@@ -15,9 +26,10 @@ services:
       - "22:22"
     volumes:
       - ./data:/app/data
-      - /usr/share/GeoIP:/usr/share/GeoIP:ro
+      - geoip-data:/usr/share/GeoIP:ro
     depends_on:
       - redis
+      - geoipupdate
     restart: unless-stopped
 
   web:
@@ -41,10 +53,10 @@ services:
       - "${WEB_LISTEN:-0.0.0.0}:80:80"
     volumes:
       - ./data:/app/data
-      - /usr/share/GeoIP:/usr/share/GeoIP:ro
     depends_on:
       - redis
     restart: unless-stopped
 
 volumes:
   redis-data:
+  geoip-data: