Skip to content

Self-Hosting Guide

How to stand up the Signal bot on your own host, in order.

The setup tooling does the configuration, validation and Signal registration.

  • A Linux host with Docker and Docker Compose, Node 22 or newer, python3 and sqlite3.
  • A phone number for the bot. It must receive SMS or voice calls, and you must keep paying for it: whoever controls the number can take the bot. VoIP numbers are often unreliable for Signal verification.
  • Optionally, a workstation with SSH access to the host. deploy.sh works from there. Set REMOTE_HOST and REMOTE_PATH at the top of deploy.sh to your host.
Terminal window
git clone https://git.juntogroups.org/irregulars/irregularchat-monorepo.git
cd irregularchat-monorepo/selfhost/messaging-apps/signal-messenger

From your workstation, run ./deploy.sh setup wizard. On the host itself, run node setup/cli.mjs wizard.

The wizard:

  1. Creates .env from .env.example, generating the database password and the bot API key.
  2. Asks for the core settings: the bot’s number, and admins by Signal UUID.
  3. Asks which features you want. File archive, AI, link analysis, SSO, docs and so on; it asks only for the settings those need.
  4. Validates everything before writing.

You can do the same in a browser (setup portal) or with the AI assistant (setup agent).

Many defaults in compose.yml point at IrregularChat’s services (irregularchat.com, irregulars.io). If you run a different community, set your own URLs. setup check --all lists the ones still on IrregularChat’s defaults.

Choose one:

  • Primary device (recommended for a number dedicated to the bot): ./deploy.sh setup primary. You’ll need a captcha solved from the host’s IP (setup opens one through the host for you), then the SMS code.
  • Linked device of a phone: ./deploy.sh link, then scan the QR code with that phone (Settings → Linked devices → +).

Details: Bot Setup and the Signal Account.

4. Initialize the database (first run only)

Section titled “4. Initialize the database (first run only)”
Terminal window
docker compose up -d postgres
docker exec -i signal-bot-postgres \
psql -v ON_ERROR_STOP=1 -U signal_bot -d signal_bot \
< database/000_base_schema.sql

The base schema may not include every later migration. Later migrations go through the integrity-gated runner, never a wildcard psql. See the repo’s docs/DATABASE.md.

Terminal window
./deploy.sh deploy --no-cache

This builds the image, starts the bot, Postgres and Redis, and ships the setup tooling to the host for its weekly checks.

Terminal window
./deploy.sh setup # start screen: Signal registered, bot running, config clean
./deploy.sh setup doctor # every check; offers fixes

Then send !help in a group the bot is in.

  • Account backup. Set up the nightly encrypted backup and the weekly restore drill (docs/runbooks/signal-data-backup.md). setup doctor schedules the drill and itself, and checks the rest.
  • PIN. Set a registration-lock PIN: ./deploy.sh setup pin.
  • Ongoing upkeep: setup/MAINTENANCE.md lists what runs by itself and what a person still does.

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