Docker and reverse proxy
The container speaks plain HTTP. You put your own reverse proxy in front of it to add HTTPS. Any proxy works.
With Compose
See the Docker Compose guide for a complete compose.yaml you can copy, plus the config, .env and Caddy files.
Without Compose
docker run -d --name tallymoth --restart unless-stopped \
--read-only --cap-drop ALL --security-opt no-new-privileges:true \
-m 128m \
-p 127.0.0.1:8080:8080 \
-e TALLYMOTH_TRUST_PROXY=1 -e TALLYMOTH_TRUSTED_HOPS=1 \
-v tallymoth-data:/data \
-v $PWD/config:/config:ro \
ghcr.io/javedh-dev/tallymoth:latestA named volume works right away. For a bind mount, give the folder to user 65532 first: chown 65532:65532 ./data.
How much memory it needs is on Performance.
Reverse proxy
Send only /v1/events and /healthz to port 8080. Two things matter, whatever proxy you use:
- Turn off access logs for these routes. They would record client IPs, which tallymoth itself never stores.
- Tell tallymoth about the proxy. Set
TALLYMOTH_TRUST_PROXY=1, and setTALLYMOTH_TRUSTED_HOPSto the number of proxies in front:1for one proxy,2for Cloudflare plus your own.
Caddy
events.example.com {
log {
output discard
}
handle /v1/events {
reverse_proxy 127.0.0.1:8080
}
handle /healthz {
reverse_proxy 127.0.0.1:8080
}
handle {
respond 404
}
}Caddy gets its own certificate.
nginx
server {
listen 443 ssl;
server_name events.example.com;
# ssl_certificate ... (certbot or similar)
access_log off;
location = /v1/events {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Forwarded-For $remote_addr;
client_max_body_size 64k;
}
location = /healthz {
proxy_pass http://127.0.0.1:8080;
}
location / { return 404; }
}Setting X-Forwarded-For to $remote_addr throws away anything the client sent, so with TALLYMOTH_TRUSTED_HOPS=1 the server sees the address nginx saw.
Check it
curl https://events.example.com/healthzokThen send a test event through the proxy (Send events).
Letting Grafana reach port 8081
Port 8081 needs a read key, but it should still never be public. In order of safety:
- One Docker network. Put Grafana and tallymoth on the same network, use
http://tallymoth:8081, and publish nothing. - Localhost only. Publish
127.0.0.1:8081:8081and connect through an SSH tunnel or VPN. - Another machine. Publish on a private address and let only Grafana's address through the firewall.
Health and logs
The image checks itself: tallymoth healthcheck calls /healthz on the public port, and docker ps shows healthy. (The scratch image has no curl, so the program does it.)
The server logs to stderr: start, config reload and errors. It writes no request logs, and errors never include IPs, headers or request bodies. docker logs tallymoth shows them.