DropHawk

Always-on, self-hosted ticket drop monitor. Polls primary and resale sources, pushes to your phone within 15 seconds when tickets go on sale.

Status: Phase 1 - infrastructure scaffolded, Ticketmaster adapter in progress.

Requirements

• Docker + Docker Compose v2 on the homelab host (recommend 16 GB RAM)
• Pi-hole or AdGuard: add drophawk.lan pointing to the host IP
• iOS: install the ntfy app and subscribe to drophawk-drops

Quickstart

# 1. Clone and configure
git clone <repo> drophawk
cd drophawk
cp .env.example .env
$EDITOR .env        # set every __CHANGE_ME__ - see comments in file

At minimum you must set:

• POSTGRES_PASSWORD, REDIS_PASSWORD, NATS_PASSWORD
• GRAFANA_ADMIN_PASSWORD
• TICKETMASTER_API_KEYS - free key at developer.ticketmaster.com
• NTFY_TOKEN - generated after first boot (step 4 below)

# 2. Start everything
make up

# 3. Run database migrations
make migrate

# 4. Create the ntfy publisher token (one-time)
docker compose exec ntfy ntfy user add --role=admin admin
docker compose exec ntfy ntfy token create admin
# Copy the token → paste as NTFY_TOKEN in .env → restart backend:
#   docker compose restart backend

# 5. Open the dashboard
# In your browser: http://drophawk.lan  (or http://<host-ip>)

# 6. Add a watchlist entry
# Navigate to Watchlist → Add Rule
# Artist: "Taylor Swift"   Priority: Critical
# Save. The next Ticketmaster poll will match events and alert you.

# 7. Verify all services are healthy
make health

Common operations

Task	Command
Start all services	make up
Stop all services	make down
View logs (all)	make logs
View logs (one service)	make logs-backend
Run migrations	make migrate
Open Postgres shell	make psql
Open Redis shell	make redis-cli
Watch NATS subjects	make nats-sub
Check all service health	make health
Manual backup now	make backup
Run full lint + test suite	make check
Local dev (no Docker for app)	make dev

Service URLs (all via Caddy on :80)

URL	Service
http://drophawk.lan/	Dashboard
http://drophawk.lan/api/health	Backend health
http://drophawk.lan/ntfy/	ntfy push server
http://drophawk.lan/grafana/	Grafana (metrics/logs)

Observability

• Grafana at /grafana/ (default login: admin / value of GRAFANA_ADMIN_PASSWORD)
  • Dashboard: DropHawk Overview - drops/24h, source health, detection latency p99
• Prometheus at http://<host>:9090 (internal only, not exposed by Caddy by default)
• Loki receives logs from all services - query in Grafana's Explore tab

Backups

Nightly pg_dump runs at 03:00. To run immediately:

make backup

Dumps land in backups/postgres/ and rotate (30-day daily, 12-week weekly, 12-month monthly).

To restore:

make down
docker volume rm drophawk_pg-data
make up   # starts postgres only initially
gunzip -c backups/postgres/drophawk-YYYYMMDD_HHMMSS.sql.gz \
  | docker compose exec -T postgres psql -U drophawk -d drophawk
make up   # bring up the rest
make health

Project documents

File	Role
CLAUDE.md	Agent bootstrap + hard rules
SPEC.md	Architecture and intent
CONTRACTS.md	Binding - pinned versions, SQL DDL, API contracts, algorithms

Legal

Personal-use monitoring + manual purchase only. Auto-purchase is disabled (US BOTS Act / UK equivalent). CAPTCHA solving is disabled. See CONTRACTS.md §16 for full guardrails.