Quick Start

This guide covers Docker install and the first login.

Install

Use Docker. Image: suwmlee/bonita:latest. Web port: 12346.

Minimal run

docker pull suwmlee/bonita:latest
docker run -d -p 12346:12346 suwmlee/bonita:latest

Full example

Mount media and data, and set the first admin (only used when the database is created):

docker run -d \
    --name bonita \
    -p 12346:12346 \
    -e PUID=0 \
    -e PGID=0 \
    -e TZ=Asia/Shanghai \
    -e FIRST_SUPERUSER_EMAIL="[email protected]" \
    -e FIRST_SUPERUSER_PASSWORD="changepwd" \
    -e MAX_CONCURRENCY=5 \
    -v <path/to/media>:/media \
    -v <path/to/data>:/app/backend/data \
    suwmlee/bonita:latest

Optional: use Redis as the Celery broker:

docker run -d \
    --name bonita \
    -p 12346:12346 \
    -e PUID=0 \
    -e PGID=0 \
    -e CELERY_BROKER_URL="redis://host.docker.internal:6379/0" \
    -e CELERY_RESULT_BACKEND="redis://host.docker.internal:6379/0" \
    -e MAX_CONCURRENCY=5 \
    -v <path/to/media>:/media \
    -v <path/to/data>:/app/backend/data \
    suwmlee/bonita:latest

docker compose (recommended)

services:
  bonita:
    container_name: bonita
    image: suwmlee/bonita:latest
    ports:
      - "12346:12346"
    environment:
      - PUID=0
      - PGID=0
      - TZ=Asia/Shanghai
      - [email protected]
      - FIRST_SUPERUSER_PASSWORD=changepwd
      - MAX_CONCURRENCY=5
    volumes:
      - <path/to/data>:/app/backend/data
      - <path/to/media>:/media
    restart: unless-stopped

docker compose up -d

Point the media mount at the same files Emby sees (same bind or hard links). Matching watch history and collections is much easier when paths line up.

Environment variables

Variable	Default	Meaning
PUID / PGID	0	User/group inside the container; must be able to read/write mounts
TZ	Asia/Shanghai	Timezone
FIRST_SUPERUSER	admin	Initial admin name (first DB create only)
FIRST_SUPERUSER_EMAIL	[email protected]	Login email (first DB create only)
FIRST_SUPERUSER_PASSWORD	changepwd	Login password (first DB create only)
MAX_CONCURRENCY	1 in the image	Celery worker concurrency. 1 runs child tasks inline; higher values dispatch in parallel
MAX_CONCURRENT_TASKS	5	Cap on concurrent transfer tasks
CELERY_BROKER_URL	SQLite	External broker, e.g. Redis
CELERY_RESULT_BACKEND	SQLite	External result backend
MONITOR_USE_POLLING	false	Set true for SMB/CIFS mounts
MONITOR_POLLING_INTERVAL	30	Poll interval in seconds
WATCH_HISTORY_SYNC_INTERVAL	900	Full watch-history sync interval in seconds
BONITA_CONFIG	./data/config.yaml	YAML config path

You can also put settings in config.yaml under /app/backend/data/. YAML overrides environment variables.

PROJECT_NAME: Bonita

CELERY_BROKER_URL: redis://192.168.1.10:6379/0
CELERY_RESULT_BACKEND: redis://192.168.1.10:6379/0

MAX_CONCURRENT_TASKS: 5
WATCH_HISTORY_SYNC_INTERVAL: 900

MONITOR_USE_POLLING: true
MONITOR_POLLING_INTERVAL: 30

Open the UI

Visit http://<host-ip>:12346 and sign in with the email and password above.

Suggested first steps:

1. Service settings — proxy if scraping needs one; Emby host, username, and API key if you want sync
2. Scraping configs — create one and save to get defaults
3. Task configs — source/output folders, optional scraping and auto-watch
4. For live watch updates, register the webhook in Emby (Media servers)

Service management

The image uses s6-overlay. Long-running services are nginx and bonita (bonita runs FastAPI plus Celery worker and beat).

docker exec bonita /command/s6-rc -a list

docker exec bonita /command/s6-rc -d change bonita
docker exec bonita /command/s6-rc -u change bonita

docker logs bonita
docker exec bonita /command/s6-svstat /run/service/bonita

FAQ

Wrong password after a rebuild

FIRST_SUPERUSER_* is applied only when the database is first created. Change the password in the UI afterwards. Resetting the admin means deleting db.sqlite3 in the data volume, which also drops other settings.

Container will not start

1. docker logs bonita
2. docker exec bonita /command/s6-rc -a list
3. Check PUID/PGID can write the data and media mounts

New files on a network share are ignored

Set MONITOR_USE_POLLING=true.

Next steps

• Basic configuration
• Media servers
• Features
• GitHub Issues