SYSOP MANUAL

DOCKER + YOUR OWN SIGNAL NUMBER

self-hosting guide.

Run snorse-bot on a machine you control. This changes the trust boundary and removes the shared host’s admission limits. It also makes you the sysadmin.

should I self-host?

choose shared choose self-hosted
You want it to just work You want control of stored data
You trust the shared host Your group only trusts your host
You do not want server chores You can maintain Docker + backups
Safe capacity is available You need private or unlimited use

before touching a terminal

  • A separate Signal-capable phone number for the bot
  • A Linux/macOS host with Docker and Compose
  • Persistent storage and a backup destination
  • A long random state API token
!!! identity safety !!!

Never run two active copies of one Signal identity. Stop the old bot before migrating or restoring its state.

installation

  1. 1
    clone it 
    git clone https://github.com/mlevin5/snorse-bot.git
cd snorse-bot
cp .env.example .env
  2. 2
    configure it

    Set the bot number, UUID, state token, and service URLs in .env. SQLite needs no third-party database credentials.

  3. 3
    register Signal

    Use the local signal-cli REST API registration flow. Keep verification codes and identity state secret.

  4. 4
    start one copy 
    docker compose up -d
docker compose ps
docker compose logs -f bot
  5. 5
    test it

    Create, list, and cancel a reminder; restart and verify durable state.

data map + backups

signal-state
Signal registration, keys, and identity state.
state-data
SQLite scopes, reminders, admission metadata, and claims.

Back up both volumes together. Test restores. A backup you have never restored is a theory.

upgrade ritual

docker compose pull
docker compose build
docker compose up -d
docker compose ps

Back up first and verify commands afterward. Google Calendar is optional; reminders work without it.