Deployment Guide
This guide covers deployment, maintenance, and operations for the Signal Bot using the deploy.sh script.
Prerequisites
Section titled “Prerequisites”- Docker and Docker Compose v2+
- SSH access to the production server
- A registered Signal phone number for the bot
deploy.sh Command Reference
Section titled “deploy.sh Command Reference”The deploy.sh script manages all deployment operations.
./deploy.sh [command] [options]Commands
Section titled “Commands”| Command | Description |
|---|---|
deploy | Full deployment: sync code + config + setup tooling, rebuild, restart (default) |
sync | Sync code, config, setup tooling and memes without rebuilding |
rebuild | Rebuild container without syncing |
restart | Restart container without rebuilding |
logs [-t N] | Show last N log lines (default: 50) |
follow | Follow logs in real-time (Ctrl+C to stop) |
status | Show container status and startup logs |
shell | Open shell inside the container |
env | Show 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-status | Is the Signal account still registered? (device, health, last alert) |
link | Link the bot to a phone as a linked device (QR code + copied link) |
sync-setup | Ship setup/ and the account scripts to the host |
check-signal-cli | signal-cli version in the running container |
check-event-analysis | Validate event-analysis config and show runtime health |
check-shared | Compile and verify shared runtime packages (no remote changes) |
test-api | Test PeerTube and Local AI connectivity |
test-minio | Test MinIO S3 configuration |
test-shlink | Test Shlink URL shortener |
test-formatting | Test markdown-to-Signal formatting |
sync-db-memes | Download 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) |
help | Show usage information |
Options
Section titled “Options”| Option | Description |
|---|---|
-v, --verbose | Show verbose output |
-n, --no-cache | Force rebuild without Docker cache |
-t, --tail N | Number of log lines to show |
Examples
Section titled “Examples”# 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 3Deployment Workflow
Section titled “Deployment Workflow”Standard Code Update
Section titled “Standard Code Update”When making code changes:
# 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 50Quick Config Update
Section titled “Quick Config Update”For environment variable or config changes:
# 1. Edit local config filesvim compose.ymlvim .env.example # Copy to server manually
# 2. Sync config files./deploy.sh sync
# 3. Restart to apply./deploy.sh restartEmergency Restart
Section titled “Emergency Restart”If the bot stops responding:
./deploy.sh restart# or./deploy.sh deployServer Configuration
Section titled “Server Configuration”| Item | Value |
|---|---|
| Host | proxmox (Tailscale IP: 100.87.20.88) |
| Remote Path | /home/signal-bot-selfhosted/ |
| Container Name | signal-bot-selfhosted-signal-bot-1 |
| Compose Service | signal-bot |
Directory Structure
Section titled “Directory Structure”/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 filesWhat Gets Synced
Section titled “What Gets Synced”The deploy script syncs:
| Source | Destination | Notes |
|---|---|---|
./src/ | /home/signal-bot-selfhosted/src/ | Source code (excludes node_modules, .git) |
./compose.yml | /home/signal-bot-selfhosted/compose.yml | Creates backup first |
./Dockerfile.selfhosted | /home/signal-bot-selfhosted/Dockerfile.selfhosted | Build configuration |
./memes/ | /home/signal-bot-selfhosted/data/memes/ | Local meme files |
NOT synced (preserved on server):
.env- Contains credentialssignal-data/- Signal CLI registrationdata/postgres/- Database filesdata/redis/- Cache data
Docker Networks
Section titled “Docker Networks”The bot uses multiple Docker networks:
| Network | Purpose |
|---|---|
signal-bot-network | Internal bot communication |
minio-network | External: MinIO S3 access |
postgres-network | External: Shlink access |
Important: Use full container names (e.g., signal-bot-postgres) instead of short names to avoid DNS conflicts across networks.
Health Monitoring
Section titled “Health Monitoring”Health check (doctor)
Section titled “Health check (doctor)”./deploy.sh setup doctor # every check, with fixes./deploy.sh setup doctor --live # also tests each configured service and keyThe 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.
Built-in Health Endpoint
Section titled “Built-in Health Endpoint”curl http://localhost:8080/health # inside the container; host port 8082Returns 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.
Watchdog Features
Section titled “Watchdog Features”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
Manual Health Checks
Section titled “Manual Health Checks”./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 errorBackup Procedures
Section titled “Backup Procedures”Signal Account Data (CRITICAL)
Section titled “Signal Account Data (CRITICAL)”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/dataand 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.
# 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 snapshotsThe 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.
Database Backup
Section titled “Database Backup”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:
docker exec signal-bot-postgres pg_dump -U signal_bot -Fc signal_bot > signal_bot_$(date +%Y%m%d).dumpRecovery Procedures
Section titled “Recovery Procedures”Restore from Database Backup
Section titled “Restore from Database Backup”# Stop the botdocker compose stop signal-bot
# Restore databasedocker exec -i signal-bot-postgres psql -U signal_bot signal_bot < backup.sql
# Start the botdocker compose start signal-botRestore Signal Registration
Section titled “Restore Signal Registration”# 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.
Full Disaster Recovery
Section titled “Full Disaster Recovery”If the entire server is lost:
- Set up a new host with Docker, Node 22,
python3andsqlite3. - Clone the repository, and point
REMOTE_HOST/REMOTE_PATHindeploy.shat the new host. - Restore the account repository from the off-site copy (restic and the
password; see the runbook). Put
signal-data/databack (owned by uid 1000) andconfig/envback as.env. - Restore the latest database dump.
- Run
./deploy.sh deploy --no-cache, then./deploy.sh setup doctorto re-create the scheduled jobs. - If the account files could not be restored, re-register:
./deploy.sh setup primary.
Disk Space Management
Section titled “Disk Space Management”Check Docker Disk Usage
Section titled “Check Docker Disk Usage”ssh proxmox "docker system df"Clean Up Old Images
Section titled “Clean Up Old Images”# Keep last 5 images (default)./deploy.sh cleanup
# Keep last 3 images./deploy.sh cleanup 3This removes:
- Old signal-bot images
- Dangling images
- Build cache (keeps 2GB)
Troubleshooting Deployments
Section titled “Troubleshooting Deployments”Container Won’t Start
Section titled “Container Won’t Start”# Check logs for errors./deploy.sh logs -t 100
# Common issues:# - Missing environment variables# - Database connection failed# - Signal-CLI registration missingCode Changes Not Applied
Section titled “Code Changes Not Applied”# Force rebuild with no cache./deploy.sh deploy --no-cacheEnvironment Variables Missing
Section titled “Environment Variables Missing”# Check what's in the container./deploy.sh env
# Verify specific variablesssh proxmox "docker exec signal-bot-selfhosted-signal-bot-1 printenv | grep ADMIN"Security Considerations
Section titled “Security Considerations”Environment Variables
Section titled “Environment Variables”- Never commit
.envfiles to git - Use unique, strong passwords for database
- Rotate API tokens periodically
- Restrict admin UUIDs to trusted users
Container Security
Section titled “Container Security”- Container runs as
nodeuser (not root) - Network isolation via Docker networks
- Only necessary ports exposed
Signal Account Security
Section titled “Signal Account Security”- 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.
Related Documentation
Section titled “Related Documentation”- Self-Hosting Guide - Initial setup
- Bot Setup and the Signal Account - Configuration, Signal registration, PIN, doctor, backups
- Database Schema - Database setup and migrations
- Troubleshooting - Common issues
- Configuration Reference - Environment variables