Quickstart

You need Docker. The image is published to GHCR for amd64 and arm64.

mkdir geometrikks && cd geometrikks
curl -LO https://raw.githubusercontent.com/GilbN/geometrikks/main/docker-compose.yml
curl -Lo .env https://raw.githubusercontent.com/GilbN/geometrikks/main/.env.example
$EDITOR .env      # set APP_ADMIN_PASSWORD, MaxMind key, CARTO key, log path
docker compose up -d

Open http://localhost:8000 and log in with APP_ADMIN_USER / APP_ADMIN_PASSWORD. When MAXMINDDB_USER_ID and MAXMINDDB_LICENSE_KEY are set, the app downloads the GeoLite2 database at startup and refreshes it weekly (see MaxMind GeoLite2). Without credentials it starts in geo-degraded mode and a banner in the UI explains what to do; after adding credentials, restart the app container.

Point it at your logs

docker-compose.yml mounts ACCESS_LOG_DIR (default /var/log/nginx) read-only into the container at /var/log/access and reads LOGPARSER_LOG_PATHS from .env. Point ACCESS_LOG_DIR at wherever your reverse proxy writes its access logs. LOGPARSER_LOG_PATHS must name the file(s) as seen inside the container, under /var/log/access/.

Your proxy has to write a log GeoMetrikks can parse. Set that up first:

Nginx setup adds a JSON log_format to nginx.conf.
Nginx Proxy Manager setup adds a second log next to NPM’s own and imports the logs NPM already wrote.
Traefik setup and Caddy setup write the JSON access log to a file instead of stdout.
Pangolin uses Traefik’s log with a few more fields kept.
Loki setup reads the lines from Grafana Loki instead of a mounted file.

Traffic from more than one proxy or host goes through Multi-source setup. Once requests arrive, Settings > Status lists each log file and Loki selector, and Debug logs shows the raw lines with any parse failures.

Docker image tags

Images are published as ghcr.io/gilbn/geometrikks.

Tag	Example	Meaning
`latest`	`latest`	The newest stable release.
Exact stable version	`X.Y.Z`	A specific stable release; use this for reproducible deployments.
Major/minor stable version	`X.Y`	The newest stable patch release in a major/minor series.
Exact development version	`0.21.0-dev.1`	A specific prerelease build for testing upcoming changes.
`develop`	`develop`	The newest development release; a moving tag.

Use latest to follow stable releases, or pin an exact version:

image: ghcr.io/gilbn/geometrikks:0.21.0