200 /assets/app.js Cricklade, GB · traefik-01403 /wp-login.php Hanoi, VN · nginx-01200 / Toronto, CA · traefik-01404 /.env Ashburn, US · caddy-01200 /api/v1/status Oslo, NO · nginx-01502 /images/logo.png Charleroi, BE · traefik-01101 /ws/live Stockholm, SE · nginx-01404 /robots.txt São Paulo, BR · traefik-01200 /assets/app.js Cricklade, GB · traefik-01403 /wp-login.php Hanoi, VN · nginx-01200 / Toronto, CA · traefik-01404 /.env Ashburn, US · caddy-01200 /api/v1/status Oslo, NO · nginx-01502 /images/logo.png Charleroi, BE · traefik-01101 /ws/live Stockholm, SE · nginx-01404 /robots.txt São Paulo, BR · traefik-01

Sources

Point it at the log file your proxy already writes.

The format is detected per file. Rotated files are followed. Archives, plain or gzipped, can be backfilled through the same pipeline with one command.

nginx.confgeometrikks-jsonnginxcombined

log_format geometrikks_json escape=json
  '{'
    '"client_ip":"$remote_addr",'
    '"timestamp":"$time_iso8601",'
    '"method":"$request_method",'
    '"path":"$request_uri",'
    '"protocol":"$server_protocol",'
    '"status":"$status",'
    '"bytes":"$body_bytes_sent",'
    '"host":"$host",'
    '"referrer":"$http_referer",'
    '"user_agent":"$http_user_agent",'
    '"remote_user":"$remote_user",'
    '"request_time":"$request_time",'
    '"upstream_time":"$upstream_response_time",'
    '"request_raw":"$request"'
  '}';

access_log /config/log/nginx/access.log geometrikks_json;

In .env

ACCESS_LOG_DIR=/var/log/nginx
LOGPARSER_LOG_PATHS=/var/log/access/access.log

Worth knowing

nginx 1.11.8 or later, for escape=json.
The older positional format and nginx's built-in combined parse too, so archives import without a config change.
Behind a CDN, set real_ip so $remote_addr is the visitor and not the CDN.

nginx setup in the docs

traefik.ymltraefik-json

accessLog:
  filePath: "/var/log/traefik/access.log"
  format: json
  fields:
    headers:
      names:
        User-Agent: keep
        Referer: keep

In .env

ACCESS_LOG_DIR=/var/log/traefik
LOGPARSER_LOG_PATHS=/var/log/access/access.log

Worth knowing

A file path is required. Traefik logs to stdout by default, and GeoMetrikks cannot read that.
Rotate with logrotate, then docker kill --signal=USR1 traefik. GeoMetrikks follows the rotation.
Behind a CDN, set forwardedHeaders.trustedIPs on the entry point. Never forwardedHeaders.insecure.

Traefik setup in the docs

Caddyfilecaddy-json

(log_settings) {
  log {
    output file /var/log/caddy/access.log
    format json
    level INFO
  }
  log_append upstream_duration_ms {rp.upstream.duration_ms}
}

app.example.com {
  import log_settings
  reverse_proxy app:8000
}

In .env

ACCESS_LOG_DIR=/var/log/caddy
LOGPARSER_LOG_PATHS=/var/log/access/access.log

Worth knowing

Caddy logs to stderr by default. The log directive writes the file.
The log_append line fills the upstream response time column. Without it the column shows a dash.
Behind a CDN, set trusted_proxies in the global options so client_ip is the visitor.

Caddy setup in the docs

Screens

What it looks like once the log is flowing.

geometrikks.home.lan/map

Live map. Markers, clusters or a heatmap; flat or globe. Routes fly to your home beacon.

And the rest

The map is the front door. The tables are where you find out what happened.

Live tail

A WebSocket-backed tail on the access-logs page. New rows prepend and pause while you hover.

Access logs

Every request, server-paginated, with free-text search and filters for status, method, IP, host, country and source.

IP inspector

One panel per address: counts, bytes, hosts and paths hit, other locations it resolved to, and scanner tells like a hosting ASN or a wide path spread.

Geo logs

Traffic grouped by place: which locations send requests, how that changes over time, and which clients keep coming back.

Batch import

Rotated archives, plain or gzipped, through the same pipeline with one command. Checksum-deduped, so re-running is safe.

Debug logs

The raw source lines behind every request, with parse failures called out and linked to their request.

The IP inspector for a banned address: the ban badge with time left, a still-seen-after-ban warning, request counts, status mix over time and the latest requests

CrowdSec

Bans next to the traffic that earned them.

Connect the Local API and the Security page joins active decisions with your own logs: the country, city and request count for every banned IP, a Banned badge in the tables, and a map overlay for banned addresses still showing up in the selected range.

Ban and unban from the UI: With machine credentials, a shield button appears next to IPs on the map, in the tables and in the IP inspector, with a duration picker from an hour to forever. Every ban and unban is audit-logged with the acting user.
Live within seconds: The app follows the LAPI decision stream and pushes changes over a WebSocket, so badges react when CrowdSec bans or unbans an IP anywhere, not only from this UI.
Two lines to connect: # prints the API key docker exec crowdsec cscli bouncers add geometrikks CROWDSEC_LAPI_URL=http://crowdsec:8080 CROWDSEC_BOUNCER_API_KEY=<key>
CrowdSec decides; a bouncer in front of your stack still does the blocking. GeoMetrikks shows and manages decisions, it does not block traffic. CrowdSec setup in the docs

Agent mode

Several proxies, one map.

When traffic comes in through more than one proxy or host, run one full instance plus an agent next to each log file. The agent tails, parses, geolocates and writes locally. The full instance owns everything else: the UI, the API, migrations, the scheduler and CrowdSec.

Every writer publishes committed events over PostgreSQL LISTEN/NOTIFY, so the live map shows a request the moment any agent stores it. Each source gets its own home beacon, and every page filters by recording hostname.

An agent needs four things: the mode, database credentials for the shared instance, MaxMind credentials, and its log mount. No admin password, no UI, no migrations.

APP_MODE=agent
DB_HOST=timescale.example.internal
LOGPARSER_LOG_PATHS=/var/log/access/access.log
LOGPARSER_HOST_NAME=edge-01

Multi-source setup in the docs

nginxedge-01

APP_MODE=agenttail · parse · geoip · write

Traefikedge-02

APP_MODE=agenttail · parse · geoip · write

Caddyedge-03

APP_MODE=agenttail · parse · geoip · write

TimescaleDBone shared database · LISTEN/NOTIFY

GeoMetrikksUI · API · migrations · scheduler · CrowdSec

Install

Docker on amd64 or arm64. Two files, one command, and the app is on port 8000.

# Docker. Images 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

Docker. The compose file brings TimescaleDB along.
A free MaxMind account. GeoLite2 City and ASN download at startup under your key and refresh weekly. You never touch .mmdb files.
A free CARTO key. The basemap comes from CARTO, and their terms want a key per deployment. Optional today; keyless tiles may stop working at any time.
A log file. Not stdout. Traefik and Caddy need one directive to write one.
One admin password. Single-user session login. An authenticating proxy or a tailnet can take over, and the built-in login switches off.
No CrowdSec needed. Optional. Add a LAPI key later and the Security page lights up.
No telemetry. Outbound traffic is the GeoLite2 download and, unless disabled, one public-IP lookup for the map's home.

Quickstart GeoLite2 and the CARTO key Behind a CDN or tunnel

Your access logs, on a live map.

Point it at the log file your proxy already writes.

In .env

Worth knowing

In .env

Worth knowing

In .env

Worth knowing

What it looks like once the log is flowing.

The map is the front door. The tables are where you find out what happened.

Live tail

Access logs

IP inspector

Geo logs

Batch import

Debug logs

Bans next to the traffic that earned them.

Several proxies, one map.

What it runs on.