Deployment#

This guide covers two deployment paths: Docker Compose for local/testing, and either non-Docker (systemd) or custom containerized setups for production servers.

Dependencies#

PostgreSQL / TimescaleDB (event and log storage)
NSQ (async writes and spike absorption)
(Optional) Redis (some metrics/caching capabilities, depending on project configuration)

Option 1: Docker Compose#

bash

git clone https://github.com/aak1247/logtap.git
cd logtap/deploy
bash ../scripts/gen-auth-secret.sh   # generate AUTH_SECRET
docker compose up -d

The Compose file includes TimescaleDB, Redis, NSQ (lookupd/nsqd/admin), and the LogTap gateway. GeoIP is optional: set MAXMIND_LICENSE_KEY and the mmdb files are downloaded and cached into the /data/geoip/ volume. If the mmdb files exist and GEOIP_CITY_MMDB / GEOIP_ASN_MMDB are not explicitly set, the startup script automatically uses /data/geoip/GeoLite2-City.mmdb and /data/geoip/GeoLite2-ASN.mmdb.

Option 2: non-Docker (production servers)#

Build the gateway#

Requires Go 1.22+:

bash

go build -o gateway ./cmd/gateway

Upload the gateway binary to your server (e.g. /opt/logtap/gateway).

Minimal environment variables#

See .env.example in the repository for the full reference; the common ones:

Variable	Description
`HTTP_ADDR`	HTTP listen address, e.g. `:8080`
`NSQD_ADDRESS`	NSQ address, e.g. `127.0.0.1:4150`
`RUN_CONSUMERS`	Whether to run DB-writing consumers (`true` in production)
`POSTGRES_URL`	Required when `RUN_CONSUMERS=true`, e.g. `postgres://logtap:[email protected]:5432/logtap?sslmode=disable`
`AUTH_SECRET`	Enables console login and reporting auth (recommended)

On startup the gateway runs GORM AutoMigrate to create tables and indexes automatically.

systemd (optional templates)#

Templates live in deploy/systemd/:

logtap-gateway.service — gateway
nsqd.service — NSQ
logtap-alert-worker.service — optional: standalone alert delivery worker

Suggested approach: create /opt/logtap/, place the binary and .env in fixed locations, then systemctl enable --now logtap-gateway.

Alert delivery worker: if you don't enable RUN_ALERT_WORKER=true (the in-gateway worker), a standalone alert-worker process can consume alert_deliveries; see deploy/alert-worker.env.example for its environment variables.

Console (web)#

The console is a separate frontend (web/, Vite + React + Tailwind); the production build lands in web/dist/ and is served by Nginx or any static host:

bash

cd web
npm install
npm run build

For production, use Nginx/Traefik for HTTPS and reverse-proxy /api/ to the gateway.

Production advice#

Reverse proxy: Nginx/Traefik for HTTPS, /api/ proxied to the gateway
Persistence: plan the Postgres data disk, NSQ directories, and log retention up front
Resource isolation: run DB-writing consumers separately from the gateway (different processes/instances) so slow queries never affect reporting
Alert worker: under heavy traffic use the standalone alert-worker process to avoid competing with the gateway