Home / Documentation / Deployment

Deployment

Run (ex)SpenserBot with Docker Compose on any machine that can reach Telegram and your LLM endpoint.

How the env files work

The setup uses two separate env files for two different purposes:

FilePurposeUsed by
.env Bot runtime variables: TELEGRAM_BOT_TOKEN, LLM_*, AUTHORIZED_USERS_CONFIG_PATH, … docker-compose.yml env_file: — injected into the running container
.env.deploy Compose interpolation only: ${UID}, ${GID} --env-file .env.deploy flag — resolved at docker compose up time, not passed to the container

Deployment steps

# 1. Clone the repository
git clone git@github.com:Cirius1792/expense-report-bot.git
cd expense-report-bot

# 2. Runtime env file (for the container environment)
cp .env.example .env
# edit .env with your Telegram token, LLM credentials, and authorization paths

# 3. Compose interpolation file (for host file ownership)
cp .env.deploy.example .env.deploy
# edit UID/GID if your host user is not 1000:1000

# 4. Allow your user — the whitelist file must be reachable at the
#    container path set in .env (see below)
mkdir -p data
echo '{"authorized_users": ["YOUR_TELEGRAM_USER_ID"]}' > data/authorized-users.json

# 5. Start
docker compose --env-file .env.deploy up -d
Important path difference. In .env, set AUTHORIZED_USERS_CONFIG_PATH=/data/authorized-users.json (the container path, not the default local path from .env.example) and place the whitelist file in ./data/ on the host, which is bind-mounted to /data in the container.

Container behavior

  • User & permissions — the container runs as the UID:GID from .env.deploy, so the bind-mounted database is owned by your host user.
  • Persistence — the SQLite database is stored at ./data/expenses.db on the host. Back up that file to back up your expenses.
  • Authorization — read from AUTHORIZED_USERS_CONFIG_PATH at runtime. See the configuration reference for the file format and failure behaviors.
  • Audit logging — optionally set UNAUTHORIZED_LOG_PATH=/data/unauthorized.log in .env for a dedicated audit log in the persisted volume.
  • Lifecycle — restart: unless-stopped keeps the bot running across reboots.

Day-2 operations

docker compose --env-file .env.deploy logs -f   # follow logs
docker compose --env-file .env.deploy down      # stop the bot
docker compose --env-file .env.deploy up -d     # start again

To update, pull the latest code (or tag) and re-run up -d. Your data in ./data/ is untouched.

Docker image

Releases are tag-triggered: pushing a vX.Y.Z tag builds and pushes the image to ghcr.io/Cirius1792/spencer-bot (tags: full version, minor, and latest) and creates a GitHub Release. You can either run from a source checkout (steps above) or pull the published image directly — see the releases page for available versions.