Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sandwichfarm/nostr-watch/llms.txt
Use this file to discover all available pages before exploring further.
@nostrwatch/docker-stacks provides a collection of Docker Compose configurations for deploying nostr-watch services. Each stack directory is self-contained with a docker-compose.yaml, sample .env and config.yaml files, and all necessary service definitions. Stacks range from simple clearnet relay monitoring to multi-network setups that route traffic through Tor and I2P via hedproxy. Every stack needs exactly two things configured: a .env file for secrets and a config.yaml for application behavior.
Prerequisites
- Docker Engine >=24
- Docker Compose v2 (the
docker composesubcommand — not the legacy standalonedocker-composebinary)
Available stacks
| Stack directory | Services | Description |
|---|---|---|
relaymon-clearnet/ | RelayMon | Standard clearnet relay monitoring |
relaymon-vpn/ | RelayMon, Gluetun | Relay monitoring routed through a VPN |
relaymon-multinet/ | RelayMon, Tor, I2P | Multi-network monitoring (clearnet + Tor + I2P) |
trawler-relaymon-clearnet/ | Trawler, RelayMon | Relay crawler and monitor on clearnet |
trawler-relaymon-multinet/ | Trawler, RelayMon, Tor, I2P | Relay crawler and monitor with multi-network routing |
Quick start
Choose a stack
Navigate to the stack directory that fits your deployment. For a minimal setup, start with
relaymon-clearnet.Edit config.yaml
Set your monitor slug, owner pubkey, publisher relays, and seed sources. Each stack directory includes a fully commented
config.yaml.example template.Environment variables reference
Environment variables are set in the.env file. Never commit .env files — only commit .env.example templates.
RelayMon
| Variable | Required | Description |
|---|---|---|
RELAYMON_NSEC | Yes | Signing key (nsec1... or hex) for publishing NIP-66 check results |
RELAYMON_KUMA_PUSH_URL | No | Full Uptime Kuma push URL |
RELAYMON_KUMA_BASE_URL | No | Uptime Kuma base URL (used with RELAYMON_KUMA_TOKEN) |
RELAYMON_KUMA_TOKEN | No | Uptime Kuma push token |
RELAYMON_HEALTH_AUTH_TOKEN | No | Token for authenticating health endpoint requests |
_FILE suffix variants for Docker/Kubernetes secrets. For example: RELAYMON_NSEC_FILE=/run/secrets/nsec.
Trawler
| Variable | Required | Description |
|---|---|---|
DEAMON_PUBKEY | No | Daemon public key for publishing relay lists |
DEAMON_PRIVKEY | No | Daemon private key for signing |
REDIS_HOST | No | Redis host (default: localhost) |
REDIS_PORT | No | Redis port (default: 6379) |
REDIS_DB | No | Redis database number (default: 0) |
REDIS_PASSWORD | No | Redis password |
Compose-managed variables
These are set directly indocker-compose.yaml and generally do not need to be changed:
| Variable | Default | Description |
|---|---|---|
RELAYMON_MODE | varies | clearnet or multinet — determines proxy setup |
RELAYMON_CONFIG_PATH | /opt/config.yaml | Path to config file inside the container |
RELAYMON_DB_PATH | /opt/data/relays.db | Path to RelayMon’s SQLite database inside the container |
RELAYMON_SKIP_PID_CHECK | true | Skip PID file check (required in containers) |
TRAWLER_CONFIG_PATH | /opt/trawler-config.yaml | Trawler config path inside the container |
TRAWLER_DB_PATH | /opt/data/trawler.db | Trawler database path inside the container |
Application config (config.yaml)
Controls application behavior — monitor identity, seed sources, check types, and intervals. Each stack directory includes aconfig.yaml.example with all available options commented.
Key sections:
| Section | Description |
|---|---|
monitor | Monitor identity: slug, name, owner pubkey, and announcement relays |
publisher | Relays that receive check result events (Kind 1066, Kind 20166) |
relaymon.networks | Networks to monitor: clearnet, tor, i2pd |
relaymon.seed | How the relay list is populated: events, config, db |
relaymon.checks | Which checks to run (open, read, info, dns) with intervals and timeouts |
relaymon.retry | Backoff strategy for failed relay connections |
Multi-network stacks
Themultinet stacks route relay connections through multiple overlay networks using hedproxy, which runs inside the RelayMon container and selects the correct proxy based on the relay URL domain:
| Network | Routing |
|---|---|
| Clearnet | Direct connections — no proxy |
| Tor | .onion relay URLs routed through the tor-proxy container (SOCKS5 on port 9050) |
| I2P | .i2p relay URLs routed through the i2pd container |
config/ (danted.conf, proxychains.conf, torrc) are pre-configured and generally do not need modification.
The multinet stacks include Tor and I2P containers, but firewall and network configuration on the host may be required depending on your environment.
Data persistence
All stacks mount./data:/opt/data for persistent storage. The data/ directory is created automatically on first run.
- RelayMon-only stacks: a single
relays.dbdatabase - Trawler + RelayMon stacks: separate
trawler.dbandrelaymon.dbon the same volume to avoid SQLite locking conflicts — RelayMon reads trawler’s database as a read-only seed source
Stopping and cleanup
Gluetun (VPN stack)
Therelaymon-vpn stack routes RelayMon traffic through a VPN via Gluetun. A .env.gluetun.example file is provided in the relaymon-vpn stack directory with provider-specific variable templates. See the Gluetun wiki for full provider documentation.