TgWitness / Documentation

Repository / docs/wiki/Server-and-Docker.md

Server and Docker

Keep the collector running. Persistent storage, server access and controlled updates.

04 · RUN AND PROTECT · All guides · Get help

On this page

Start with one workspace and persistent storage. The panel only listens on localhost, for remote access use HTTPS or an SSH tunnel.

Run with Docker Compose#

From the project directory, with Docker and Compose 2.20+ installed:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

Open http://127.0.0.1:8787 and paste the token. Data lives in the named volume at /data; a native data/live doesn't get imported automatically.

Check the service:

docker compose ps
docker compose logs --tail 100 tgwitness

"Healthy" just means the panel answers. Login, sources and an actual captured message are separate checks.

Access through an SSH tunnel#

Keep the collector bound to localhost. From your own computer:

ssh -L 8787:127.0.0.1:8787 user@your-server

Then open the local address while the tunnel is up. Another local port if 8787 is taken.

Add HTTPS#

You need a domain pointing at the server and ports 80/443 open. Copy deploy/env.example to .env and set:

TGWITNESS_DOMAIN=watch.your-domain.org

Then run:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt

Open https://watch.your-domain.org. Keep passing both -f files for status, logs, stop and updates. Caddy gets and renews the certificate on its own volume.

Updates and alternatives#

Full backup with everything stopped before updating. Keep the project name, volume, config and external vault key. Never update with docker compose down -v, it deletes the volumes.

Published images: deploy/compose/compose.image.yaml. Native service templates for Linux, macOS and Windows are in deploy/.

Next: Backup and recovery · Deployment reference · Troubleshooting