Server and Docker

Server and Docker

04 · RUN AND PROTECT · All guides · Get help

On this page

• Run with Docker Compose
• Access through an SSH tunnel
• Add HTTPS
• Updates and alternatives

Start with one workspace and persistent storage. The default panel binds to localhost; remote access needs 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 enter the token. The named volume contains the application's data at /data. A native installation's data/live directory is not automatically imported into that volume.

Check the service:

docker compose ps
docker compose logs --tail 100 tgwitness

A healthy container confirms the panel responds. Confirm Telegram authorization, source selection and a newly captured message separately.

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

Open the local panel address while the tunnel is connected. Substitute your SSH user and server. Use another local port if 8787 is already occupied.

Add HTTPS

Use a domain you control, DNS pointing to the server, and available inbound ports 80 and 443. 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 both Compose file arguments for later status, logs, stop and update commands. Caddy obtains and renews the certificate; its state has a separate persistent volume.

Updates and alternatives

Make a complete stopped backup before updating. Preserve the project name, data volume, configuration and external master key if used. Do not use docker compose down -v to update: it removes named volumes.

Published images can use deploy/compose/compose.image.yaml once the corresponding release image exists. Native service templates are available for Linux, macOS and Windows in the deployment templates.

Next: Backup and recovery · Deployment reference · Troubleshooting