Skip to content

Deployment Guide

This guide covers deployment, maintenance, and operations for the Signal Bot using the deploy.sh script.

  • Docker and Docker Compose v2+
  • SSH access to the production server
  • A registered Signal phone number for the bot

The deploy.sh script manages all deployment operations.

Terminal window
./deploy.sh [command] [options]
CommandDescription
deployFull deployment: sync code + config + setup tooling, rebuild, restart (default)
syncSync code, config, setup tooling and memes without rebuilding
rebuildRebuild container without syncing
restartRestart container without rebuilding
logs [-t N]Show last N log lines (default: 50)
followFollow logs in real-time (Ctrl+C to stop)
statusShow container status and startup logs
shellOpen shell inside the container
envShow environment variables (masked)
setup [cmd]Configure the bot and its Signal account — start screen with no command; portal, wizard, agent, doctor, pin, primary, … (Bot Setup and the Signal Account)
signal-statusIs the Signal account still registered? (device, health, last alert)
linkLink the bot to a phone as a linked device (QR code + copied link)
sync-setupShip setup/ and the account scripts to the host
check-signal-clisignal-cli version in the running container
check-event-analysisValidate event-analysis config and show runtime health
check-sharedCompile and verify shared runtime packages (no remote changes)
test-apiTest PeerTube and Local AI connectivity
test-minioTest MinIO S3 configuration
test-shlinkTest Shlink URL shortener
test-formattingTest markdown-to-Signal formatting
sync-db-memesDownload all database memes to storage
cookies [browser]Extract browser cookies for yt-dlp and upload them
cleanup [N]Remove old Docker images (keep last N, default: 5)
helpShow usage information
OptionDescription
-v, --verboseShow verbose output
-n, --no-cacheForce rebuild without Docker cache
-t, --tail NNumber of log lines to show
Terminal window
# Standard deployment (sync + rebuild + restart)
./deploy.sh
# Deploy with fresh build (no cache)
./deploy.sh deploy --no-cache
# Only sync code without rebuilding
./deploy.sh sync
# View last 100 log lines
./deploy.sh logs -t 100
# Watch logs in real-time
./deploy.sh follow
# Check container status
./deploy.sh status
# Test integrations
./deploy.sh test-minio
./deploy.sh test-api
# Open shell for debugging
./deploy.sh shell
# Clean up old images (keep last 3)
./deploy.sh cleanup 3

When making code changes:

Terminal window
# 1. Make changes locally in src/src/
vim src/src/bot/command-handler.ts
# 2. Deploy with no-cache to ensure fresh build
./deploy.sh deploy --no-cache
# 3. Verify the deployment
./deploy.sh status
./deploy.sh logs -t 50

For environment variable or config changes:

Terminal window
# 1. Edit local config files
vim compose.yml
vim .env.example # Copy to server manually
# 2. Sync config files
./deploy.sh sync
# 3. Restart to apply
./deploy.sh restart

If the bot stops responding:

Terminal window
./deploy.sh restart
# or
./deploy.sh deploy

ItemValue
Hostproxmox (Tailscale IP: 100.87.20.88)
Remote Path/home/signal-bot-selfhosted/
Container Namesignal-bot-selfhosted-signal-bot-1
Compose Servicesignal-bot
/home/signal-bot-selfhosted/
├── .env # Environment variables (credentials)
├── compose.yml # Docker Compose configuration
├── Dockerfile.selfhosted # Docker build file
├── src/ # Bot source code (synced)
│ ├── src/ # TypeScript source
│ ├── dist/ # Compiled JavaScript
│ └── package.json
├── signal-data/ # Signal CLI account data (CRITICAL!)
├── data/
│ ├── postgres/ # PostgreSQL data volume
│ ├── redis/ # Redis data volume
│ ├── memes/ # Persistent meme storage
│ └── backups/ # Database backups
├── database/ # SQL migration scripts
│ ├── 000_base_schema.sql
│ └── 001_*.sql ...
└── memes/ # Local meme GIF files

The deploy script syncs:

SourceDestinationNotes
./src//home/signal-bot-selfhosted/src/Source code (excludes node_modules, .git)
./compose.yml/home/signal-bot-selfhosted/compose.ymlCreates backup first
./Dockerfile.selfhosted/home/signal-bot-selfhosted/Dockerfile.selfhostedBuild configuration
./memes//home/signal-bot-selfhosted/data/memes/Local meme files

NOT synced (preserved on server):

  • .env - Contains credentials
  • signal-data/ - Signal CLI registration
  • data/postgres/ - Database files
  • data/redis/ - Cache data

The bot uses multiple Docker networks:

NetworkPurpose
signal-bot-networkInternal bot communication
minio-networkExternal: MinIO S3 access
postgres-networkExternal: Shlink access

Important: Use full container names (e.g., signal-bot-postgres) instead of short names to avoid DNS conflicts across networks.


Terminal window
./deploy.sh setup doctor # every check, with fixes
./deploy.sh setup doctor --live # also tests each configured service and key

The doctor checks:

  • Configuration: .env, and settings no code reads any more.
  • Signal: registration, PIN, linked devices and the signal-cli version.
  • Bot: whether it’s running, and the host monitor.
  • Backups: the account backup and its off-site copies, and the weekly restore drill.
  • Upkeep: scheduled jobs, leftover files and disk space.

For each problem it offers the fix it can make. The same checks run weekly on the host and post problems to ntfy.

Terminal window
curl http://localhost:8080/health # inside the container; host port 8082

Returns 200 only when the bot is ready. Key fields:

{
"status": "healthy",
"bot": { "running": true, "uptime": 86400 },
"signal_account": { "registered": true },
"database": "connected",
"instance_id": "…",
"source_version": "…"
}

If the Signal account has been revoked, signal_account reads { "registered": false, "lost_at": …, "detail": …, "fix": … }. The bot then stops restarting signal-cli and posts a “relink” or “re-register” alert.

The bot includes automatic monitoring:

  • Daemon health check: Every 2 minutes
  • Auto-restart: On daemon death or disconnect — but not when the Signal account itself was revoked (no restart can fix that)
  • Message flow monitoring: Alerts if no messages for 10+ minutes
  • Restart notifications: Sends alerts to Bot Dev room; failures also reach ntfy via the host monitor
Terminal window
./deploy.sh setup # start screen: Signal, bot, config, backup at a glance
./deploy.sh signal-status # Signal registration and last alert
./deploy.sh status # container status
./deploy.sh logs -t 200 | grep -i error

signal-data/ holds the bot’s Signal identity: keys, sessions and groups. For a primary bot it is the only copy of its keys.

The account is backed up automatically on the bot host:

  • Every night: an encrypted, deduplicated restic snapshot of signal-data/data and the bot’s .env. SQLite is copied with its online backup, so the bot keeps running, and every copy is integrity-checked. Snapshots are kept for 14 days, 8 weeks and 12 months, and each run re-reads part of the repository.
  • Off-site: the repository is pushed to the off-site backup host every night.
  • Every week: a restore drill restores the latest snapshot to a sandbox, verifies every file, the databases and the account store, then deletes it.
  • Alerts: each job posts to ntfy if it fails or stops running.
Terminal window
# On the bot host (as root)
/usr/local/libexec/irregularchat/signal-data-backup.sh # take a snapshot now
/usr/local/libexec/irregularchat/signal-data-backup.sh --list # list snapshots

The restic password (/etc/irregularchat/restic-signal-data.pass) must be in the password manager. Without it the off-site copies cannot be read. Runbook: docs/runbooks/signal-data-backup.md.

The postgres-backup container (signal-bot-backup) dumps the database daily into data/backups/. It keeps 7 days, 4 weeks and 6 months, and those dumps are pushed off-site too. For a one-off dump:

Terminal window
docker exec signal-bot-postgres pg_dump -U signal_bot -Fc signal_bot > signal_bot_$(date +%Y%m%d).dump

Terminal window
# Stop the bot
docker compose stop signal-bot
# Restore database
docker exec -i signal-bot-postgres psql -U signal_bot signal_bot < backup.sql
# Start the bot
docker compose start signal-bot
Terminal window
# On the bot host (as root): verify into a sandbox first, then restore live
/usr/local/libexec/irregularchat/signal-data-restore.sh # sandbox, verified
/usr/local/libexec/irregularchat/signal-data-restore.sh --live # replace signal-data/data, verified

--live pauses the host monitor, stops the bot, and keeps the current data as signal-data/data.pre-restore-<UTC>. It then restores, verifies and starts the bot. If the keys are gone entirely, re-register the number with ./deploy.sh setup primary: the account ID and groups survive.

If the entire server is lost:

  1. Set up a new host with Docker, Node 22, python3 and sqlite3.
  2. Clone the repository, and point REMOTE_HOST/REMOTE_PATH in deploy.sh at the new host.
  3. Restore the account repository from the off-site copy (restic and the password; see the runbook). Put signal-data/data back (owned by uid 1000) and config/env back as .env.
  4. Restore the latest database dump.
  5. Run ./deploy.sh deploy --no-cache, then ./deploy.sh setup doctor to re-create the scheduled jobs.
  6. If the account files could not be restored, re-register: ./deploy.sh setup primary.

Terminal window
ssh proxmox "docker system df"
Terminal window
# Keep last 5 images (default)
./deploy.sh cleanup
# Keep last 3 images
./deploy.sh cleanup 3

This removes:

  • Old signal-bot images
  • Dangling images
  • Build cache (keeps 2GB)

Terminal window
# Check logs for errors
./deploy.sh logs -t 100
# Common issues:
# - Missing environment variables
# - Database connection failed
# - Signal-CLI registration missing
Terminal window
# Force rebuild with no cache
./deploy.sh deploy --no-cache
Terminal window
# Check what's in the container
./deploy.sh env
# Verify specific variables
ssh proxmox "docker exec signal-bot-selfhosted-signal-bot-1 printenv | grep ADMIN"

  • Never commit .env files to git
  • Use unique, strong passwords for database
  • Rotate API tokens periodically
  • Restrict admin UUIDs to trusted users
  • Container runs as node user (not root)
  • Network isolation via Docker networks
  • Only necessary ports exposed
  • Set a registration-lock PIN (./deploy.sh setup pin) and keep it in the password manager. Without one, anyone who gets control of the number can register it and take over the bot.
  • Keep the number. Use one you’ll keep paying for, that can receive SMS and voice calls.
  • Backups: signal-data/ is backed up nightly, encrypted and off-site. Keep the restic password in the password manager.
  • Don’t share registration data. Restored copies are never started against Signal: a second instance of the bot’s account must never connect.

Recent changes

  1. docs: Signal bot setup, Signal account, backups and maintenance; v5.33.0 notes @sac
  2. refactor(structure): flatten workers into apps/ directory gitayam