How the env files work
The setup uses two separate env files for two different purposes:
| File | Purpose | Used 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:GIDfrom.env.deploy, so the bind-mounted database is owned by your host user. - Persistence — the SQLite database is stored at
./data/expenses.dbon the host. Back up that file to back up your expenses. - Authorization — read from
AUTHORIZED_USERS_CONFIG_PATHat runtime. See the configuration reference for the file format and failure behaviors. - Audit logging — optionally set
UNAUTHORIZED_LOG_PATH=/data/unauthorized.login.envfor a dedicated audit log in the persisted volume. - Lifecycle —
restart: unless-stoppedkeeps 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.