BeeCount Cloud (Self-hosted)

New in 3.0 · Recommended sync option for real-time multi-device collaboration

BeeCount Cloud is the official self-hosted sync server — deploy it in one Docker command and get:

• 🔄 Real-time multi-device sync: edit on phone A, pushed to phone B and Web within seconds
• 🌐 Web UI bundled: one Docker image = server + Web + PWA, ready in the browser
• 👥 Multi-user isolation: multiple users can register; their data is fully separated
• 🐳 One-command deploy: docker-compose file under 10 lines

Upgrade notes (1.9.0)

The complete MCP toolset and workflows require Cloud 1.9.0 or later and do not require App v4. Back up the database, attachments, and configuration first. The official image applies migration 0021_mcp_workflows on startup; source deployments must update dependencies and run alembic upgrade head. Existing MCP URLs and PAT configuration remain valid; reconnect clients after upgrading.

Disable Cloud's background recurring scheduler with MCP_RECURRING_ENABLED=false if needed, and avoid duplicate App and Cloud schedules for the same event. See the Cloud Changelog.

Project partnerships and setup help

Since Cloud 1.6.8, the top-right avatar → About dialog links to BeeCount project partnerships. AI settings also includes a provider setup guide below the provider section. These links open in a new tab and preserve your Cloud session.

Self-host operators can set PROJECT_PARTNERSHIPS_ENABLED: "false" under Compose's environment section and recreate the container to hide both links. No frontend rebuild is required.

1.6.8 also fixes offset-free MCP transaction timestamps: Cloud uses SCHEDULER_TIMEZONE, then TZ (the official image defaults to Asia/Shanghai), while explicit offsets retain their meaning. Existing transactions are not rewritten, and this release has no database schema migration. Upgrade with docker compose pull && docker compose up -d.

Who is it for?

User type	Why it fits
🏠 Households	Each member has their own account plus shared ledgers — invite family to write into the same book, Owner / Editor roles included
📱 One person, many devices	Phone / iPad / Web — seconds to sync, no more manual "upload / download"
🖥️ NAS / VPS owners	Docker one-shot, data stays on your own machine
👨‍💻 Technical users	Open source, auditable, fork-friendly

Upgrade notes (1.6.0)

• App 3.6.0's ledger multi-currency (transactions store the original currency + a converted snapshot in the ledger's base currency) requires Cloud ≥ 1.6.0: the server projection gains currency / conversion columns, ledger-level stats sum on the converted amount, and editing an amount on Web recomputes the conversion. Upgrade the server first, then the App.
• This release includes a database schema migration (the transactions table gains currency_code / native_amount columns + historical backfill), run automatically on image startup — docker compose pull && docker compose up -d is all you need, no manual steps.
• Older servers don't recognize these columns, so foreign transactions recorded by the new App lose their conversion on Web / across devices and ledger stats sum raw original amounts; upgrading to 1.6.0 brings it into alignment.

Upgrade notes (1.5.1)

• The App 3.5.1 Transaction flags require Cloud ≥ 1.5.1: in cloud mode the server's income/expense and budget summaries filter by the Exclude from Income/Expense and Exclude from Budget flags; older servers don't recognize the flags, so cloud-side stats would still count flagged transactions (local mode and single-device stats are unaffected and always correct). Always upgrade the server first, then the App.

Upgrade notes (1.5.0)

• The App 3.5.0 Multi-currency and Net worth over time require Cloud ≥ 1.5.0: the server provides base-currency sync, manual exchange rates, a rate proxy, and the net-worth-history read endpoint. Always upgrade the server first, then the App.
• No database schema migration in this release: net-worth-history is a read-only endpoint and multi-currency syncs at the user-global level (user-global projection), so docker compose pull && docker compose up -d is all you need — your data is untouched.
• Older servers don't recognize the base currency, so the conversion setting "won't sync" and the remote net worth trend is unavailable; upgrading to 1.5.0 brings them into alignment.

Upgrade notes (1.4.0)

• The App 3.4.0 Month Start Day requires Cloud ≥ 1.4.0: older servers ignore the setting (it looks like it "doesn't sync"). Upgrade the server first, then the App.
• Upgrading to 1.4.0 runs database migrations automatically and backfills a historical issue where some web-created transactions lacked an account link, making web account statistics too low — no manual action needed.
• Since 1.3.12 the web CSV import converts times using the client's timezone (fixes the 8-hour offset).

Deploy

Save the following as docker-compose.yml:

services:
  beecount-cloud:
    image: sunxiao0721/beecount-cloud:latest
    restart: unless-stopped
    ports:
      - "8869:8080"
    volumes:
      - ./data:/data

Start:

mkdir -p beecount && cd beecount
# Save the yaml above as docker-compose.yml
docker compose up -d

On first boot, Docker will:

1. Create ./data/beecount.db and run migrations
2. Generate ./data/.jwt_secret (32-byte secret, 0600)
3. Auto-create an admin account with a random 16-char password

Get the admin account

Option 1: from logs (recommended)

docker compose logs beecount-cloud | grep -A 10 "admin"

You'll see:

========================================================================
 BeeCount Cloud — First boot. Admin account auto-created:

   email:    [email protected]
   password: FIDodUnwprkw1zUi

   Credentials saved to /data/.initial_admin_password (0600, in volume)
========================================================================

Option 2: read the file

cat ./data/.initial_admin_password

Sign in

Web UI

Browser to http://<your-server>:8869, sign in as admin.

After first login, change the password immediately (top-right avatar → account settings).

Connect from the mobile app

1. Open BeeCount → Me → Cloud sync
2. Pick BeeCount Cloud
3. Enter server URL (e.g. http://192.168.1.100:8869) + admin email + password
4. First sign-in uploads your entire local ledger to the server

Add family / teammates

BeeCount Cloud does not allow self-registration (to prevent abuse on public servers). Accounts must be created by an admin.

1. Admin signs in to the Web UI → Users
2. Click Add user, enter their email + a temporary password
3. Hand them the credentials; they sign in from the app or Web

Each user's data is isolated by default. For multi-person scenarios use shared ledgers: an Owner generates an invite code in the App / Web and Editors join by entering it.

Shared ledgers (multi-user collaboration)

• Owner / Editor roles — Owners rename / invite / remove members; Editors co-write transactions and can't see the Owner's other ledgers
• Realtime sync — WebSocket fan-out, every member sees changes within seconds
• Who wrote it / who last edited it — every transaction is tagged with creator + last editor (avatar + role)
• Member balance stats — dedicated dialog on Web (chart-rich, bar + pie) / compact list on App
• Three-platform parity — invite / join / leave / kick works on iOS, Android, and Web

See the Shared ledgers doc for full usage.

Advanced config

Specify the bootstrap admin

The default is a randomly generated password. If you'd rather pick your own:

services:
  beecount-cloud:
    image: sunxiao0721/beecount-cloud:latest
    restart: unless-stopped
    ports:
      - "8869:8080"
    environment:
      BOOTSTRAP_ADMIN_EMAIL: [email protected]
      BOOTSTRAP_ADMIN_PASSWORD: <your-strong-password>
    volumes:
      - ./data:/data

These two env vars only take effect when the users table is empty — changing them later won't affect existing accounts.

Specify JWT secret

The server auto-generates /data/.jwt_secret. If you'd rather manage it yourself:

environment:
  JWT_SECRET: <32+ byte random string>

When this env is set, the server won't generate or read from the file.

Public deployment

Put nginx / Caddy in front for HTTPS + domain:

Users ─HTTPS─► Caddy/Nginx ─http://localhost:8869─► BeeCount Cloud

Both the app and Web accept https:// URLs.

Backup

All persistent data lives under ./data/:

• beecount.db — SQLite database (ledgers, transactions, users)
• attachments/ — file attachments (avatars, transaction images, custom category icons)
• backups/ — backup archives
• .jwt_secret — JWT signing key (if lost, all tokens invalidate; users must sign in again)

Backing up the entire data/ dir covers everything. Migrating to a new server is rsync + restart.

PWA support

The Web UI is a Progressive Web App:

• An "Install" icon appears in the browser address bar — click to pin to desktop / Dock / Start menu
• Installed as a standalone app: no browser chrome, near-native feel
• Reads cached data offline, auto-resyncs when back online

Upgrade

cd beecount
docker compose pull
docker compose up -d

Database migration runs automatically. data/ is untouched.

FAQ

Q: App can't connect to the server

Check:

• Firewall allows port 8869 (or whatever you mapped)
• Phone and server are on the same network (or use public IP / domain)
• Server URL prefix matches — http:// vs https://

Q: The admin banner isn't in docker compose logs

It's only logged on first boot. The password file is at ./data/.initial_admin_password. If that file is also gone, you can set BOOTSTRAP_ADMIN_EMAIL + BOOTSTRAP_ADMIN_PASSWORD env to create a new admin (only works if the users table is empty). To reset an existing user's password, sign in as any admin and edit them in Web → Users.

Q: Move the server to a new machine

• Old machine: docker compose down
• rsync the data/ directory to the new machine
• New machine: same docker-compose.yml, docker compose up -d
• Update the server URL in the mobile app and sign in again

Q: Can I change the theme color on Web?

Yes. Top-right avatar → Account settings → Theme color. Each user has their own preference, no interference.

Related repos

• BeeCount-Cloud — server + Web UI source
• BeeCount — mobile app source