README.md · Drophawk

125 lines · markdown

# 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](https://apps.apple.com/us/app/ntfy/id1625396347) and subscribe to `drophawk-drops`
 
## Quickstart
 
```bash
# 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](https://developer.ticketmaster.com)
- `NTFY_TOKEN` - generated after first boot (step 4 below)
 
```bash
# 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
```
 
```bash
# 5. Open the dashboard
# In your browser: http://drophawk.lan  (or http://<host-ip>)
```
 
```bash
# 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.
```
 
```bash
# 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:
 
```bash
make backup
```
 
Dumps land in `backups/postgres/` and rotate (30-day daily, 12-week weekly, 12-month monthly).
 
To restore:
 
```bash
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`](./CLAUDE.md) | Agent bootstrap + hard rules |
| [`SPEC.md`](./SPEC.md) | Architecture and intent |
| [`CONTRACTS.md`](./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.

1	# DropHawk
2
3	Always-on, self-hosted ticket drop monitor. Polls primary and resale sources, pushes to your phone within 15 seconds when tickets go on sale.
4
5	> Status: Phase 1 - infrastructure scaffolded, Ticketmaster adapter in progress.
6
7	## Requirements
8
9	- Docker + Docker Compose v2 on the homelab host (recommend 16 GB RAM)
10	- Pi-hole or AdGuard: add `drophawk.lan` pointing to the host IP
11	- iOS: install the [ntfy app](https://apps.apple.com/us/app/ntfy/id1625396347) and subscribe to `drophawk-drops`
12
13	## Quickstart
14
15	```bash
16	# 1. Clone and configure
17	git clone <repo> drophawk
18	cd drophawk
19	cp .env.example .env
20	$EDITOR .env # set every __CHANGE_ME__ - see comments in file
21	```
22
23	At minimum you must set:
24	- `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `NATS_PASSWORD`
25	- `GRAFANA_ADMIN_PASSWORD`
26	- `TICKETMASTER_API_KEYS` - free key at [developer.ticketmaster.com](https://developer.ticketmaster.com)
27	- `NTFY_TOKEN` - generated after first boot (step 4 below)
28
29	```bash
30	# 2. Start everything
31	make up
32
33	# 3. Run database migrations
34	make migrate
35
36	# 4. Create the ntfy publisher token (one-time)
37	docker compose exec ntfy ntfy user add --role=admin admin
38	docker compose exec ntfy ntfy token create admin
39	# Copy the token → paste as NTFY_TOKEN in .env → restart backend:
40	# docker compose restart backend
41	```
42
43	```bash
44	# 5. Open the dashboard
45	# In your browser: http://drophawk.lan (or http://<host-ip>)
46	```
47
48	```bash
49	# 6. Add a watchlist entry
50	# Navigate to Watchlist → Add Rule
51	# Artist: "Taylor Swift" Priority: Critical
52	# Save. The next Ticketmaster poll will match events and alert you.
53	```
54
55	```bash
56	# 7. Verify all services are healthy
57	make health
58	```
59
60	## Common operations
61
62	\| Task \| Command \|
63	\|---\|---\|
64	\| Start all services \| `make up` \|
65	\| Stop all services \| `make down` \|
66	\| View logs (all) \| `make logs` \|
67	\| View logs (one service) \| `make logs-backend` \|
68	\| Run migrations \| `make migrate` \|
69	\| Open Postgres shell \| `make psql` \|
70	\| Open Redis shell \| `make redis-cli` \|
71	\| Watch NATS subjects \| `make nats-sub` \|
72	\| Check all service health \| `make health` \|
73	\| Manual backup now \| `make backup` \|
74	\| Run full lint + test suite \| `make check` \|
75	\| Local dev (no Docker for app) \| `make dev` \|
76
77	## Service URLs (all via Caddy on `:80`)
78
79	\| URL \| Service \|
80	\|---\|---\|
81	\| `http://drophawk.lan/` \| Dashboard \|
82	\| `http://drophawk.lan/api/health` \| Backend health \|
83	\| `http://drophawk.lan/ntfy/` \| ntfy push server \|
84	\| `http://drophawk.lan/grafana/` \| Grafana (metrics/logs) \|
85
86	## Observability
87
88	- Grafana at `/grafana/` (default login: `admin` / value of `GRAFANA_ADMIN_PASSWORD`)
89	- Dashboard: DropHawk Overview - drops/24h, source health, detection latency p99
90	- Prometheus at `http://<host>:9090` (internal only, not exposed by Caddy by default)
91	- Loki receives logs from all services - query in Grafana's Explore tab
92
93	## Backups
94
95	Nightly `pg_dump` runs at 03:00. To run immediately:
96
97	```bash
98	make backup
99	```
100
101	Dumps land in `backups/postgres/` and rotate (30-day daily, 12-week weekly, 12-month monthly).
102
103	To restore:
104
105	```bash
106	make down
107	docker volume rm drophawk_pg-data
108	make up # starts postgres only initially
109	gunzip -c backups/postgres/drophawk-YYYYMMDD_HHMMSS.sql.gz \
110	\| docker compose exec -T postgres psql -U drophawk -d drophawk
111	make up # bring up the rest
112	make health
113	```
114
115	## Project documents
116
117	\| File \| Role \|
118	\|---\|---\|
119	\| [`CLAUDE.md`](./CLAUDE.md) \| Agent bootstrap + hard rules \|
120	\| [`SPEC.md`](./SPEC.md) \| Architecture and intent \|
121	\| [`CONTRACTS.md`](./CONTRACTS.md) \| Binding - pinned versions, SQL DDL, API contracts, algorithms \|
122
123	## Legal
124
125	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.