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.
Prerequisites
Section titled “Prerequisites”- A Linux host with Docker and Docker Compose, Node 22 or newer,
python3andsqlite3. - 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.shworks from there. SetREMOTE_HOSTandREMOTE_PATHat the top ofdeploy.shto your host.
1. Clone the repository
Section titled “1. Clone the repository”git clone https://git.juntogroups.org/irregulars/irregularchat-monorepo.gitcd irregularchat-monorepo/selfhost/messaging-apps/signal-messenger2. Configure
Section titled “2. Configure”From your workstation, run ./deploy.sh setup wizard. On the host itself,
run node setup/cli.mjs wizard.
The wizard:
- Creates
.envfrom.env.example, generating the database password and the bot API key. - Asks for the core settings: the bot’s number, and admins by Signal UUID.
- Asks which features you want. File archive, AI, link analysis, SSO, docs and so on; it asks only for the settings those need.
- 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.ymlpoint at IrregularChat’s services (irregularchat.com,irregulars.io). If you run a different community, set your own URLs.setup check --alllists the ones still on IrregularChat’s defaults.
3. Put the bot on Signal
Section titled “3. Put the bot on Signal”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)”docker compose up -d postgresdocker exec -i signal-bot-postgres \ psql -v ON_ERROR_STOP=1 -U signal_bot -d signal_bot \ < database/000_base_schema.sqlThe 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.
5. Deploy
Section titled “5. Deploy”./deploy.sh deploy --no-cacheThis builds the image, starts the bot, Postgres and Redis, and ships the setup tooling to the host for its weekly checks.
6. Verify
Section titled “6. Verify”./deploy.sh setup # start screen: Signal registered, bot running, config clean./deploy.sh setup doctor # every check; offers fixesThen send !help in a group the bot is in.
7. Keep it healthy
Section titled “7. Keep it healthy”- Account backup. Set up the nightly encrypted backup and the weekly
restore drill (
docs/runbooks/signal-data-backup.md).setup doctorschedules the drill and itself, and checks the rest. - PIN. Set a registration-lock PIN:
./deploy.sh setup pin. - Ongoing upkeep:
setup/MAINTENANCE.mdlists what runs by itself and what a person still does.