Quick Start#

Prerequisites#

Docker and Docker Compose
(Production) a server with at least 2 vCPU / 4 GB RAM

1. Clone and start#

bash

git clone https://github.com/aak1247/logtap.git
cd logtap/deploy

# Generate AUTH_SECRET (base64, >= 32 bytes decoded)
bash ../scripts/gen-auth-secret.sh

# Start — ships with Postgres/TimescaleDB, Redis, NSQ
docker compose up -d

Once started:

Gateway & console: http://localhost:8080
NSQ Admin: http://localhost:4171
Postgres: localhost:5432 (default database logtap)

The docker-compose.yml includes TimescaleDB, Redis, NSQ (lookupd/nsqd/admin), and the LogTap gateway — ready in about a minute. You can also try the online demo console first.

2. Access with auth enabled#

Once AUTH_SECRET is set:

The console requires login
Reporting must carry a project key: X-Project-Key: pk_... (create one on the project page), or the Sentry SDK's sentry_key

On PowerShell, use powershell -ExecutionPolicy Bypass -File scripts/gen-auth-secret.ps1, or task auth:secret from the Taskfile.

3. Send your first log#

Create a project in the console, then grab the project ID and the pk_-prefixed project key:

bash

curl -X POST http://localhost:8080/api/1/logs/ \
  -H "Content-Type: application/json" \
  -H "X-Project-Key: pk_xxx" \
  -d '{
    "level": "info",
    "message": "hello logtap",
    "user": { "id": "u1" },
    "fields": { "env": "dev" }
  }'

A 202 Accepted response means the event is queued. Back in the console you will see the log, and from there you can keep exploring:

Search: keyword search on the logs page
Tracking: POST events to /api/1/track/ and inspect DAU, funnels, and retention
Errors: point any Sentry SDK's DSN at LogTap — see Sentry compatibility

Optional: enable GeoIP#

Requires a MaxMind GeoLite2 download key: set MAXMIND_LICENSE_KEY in .env, and Compose downloads and caches the mmdb files into the /data/geoip/ volume for country/city/ASN breakdowns.

Next steps#

Deployment: non-Docker setups, systemd, and production advice
Ingest API: the full data model and batch reporting
SDKs: report from application code with an SDK