Mobile App
Updated: 2026-09-21
Members use Bellamy Book on phone the same way as on the website: your self-hosted stack is enough. There is no separate mobile server to deploy.
How members use it
- Install Bellamy Book from the App Store or Google Play.
- Open the app and enter your API URL — the public API address of your instance (e.g.
https://api.example.comorhttps://social.example.comif API and site share one host). - Sign in (or register, if you allow public registration).
- Allow notifications when asked (for chat and call alerts in the background).
The Connect field is for API_PUBLIC_URL (where /api and hubs live). Do not tell members to type a frontend-only host if the API is on a different domain.
| Enter this | Do not enter (when API is separate) |
|---|---|
https://api.example.com (API_PUBLIC_URL) | Frontend-only host with no API (e.g. SPA-only https://app.example.com) |
Same host as the site if Traefik serves /api there | Internal Docker names (api:8080), localhost, or /api path alone |
Give members the same public API base you set as API_PUBLIC_URL (scheme + host, no /api suffix required — the app adds it).
To switch communities later: Settings → Change server.
What you need as operator
Your normal self-host kit already covers mobile (dockerProd / dockerPublish):
- Public HTTPS API URL (
API_PUBLIC_URL) — this is what members type in the app - Chat / notification hubs reachable on that API host (or set hub overrides below)
- Expo push worker running (background notifications)
- Storage / LiveKit / Google configured the same as for the website (if you use those features)
Smoke check: open https://your-api-host/api/mobile/bootstrap in a browser — you should see JSON (no login required).
Env (optional)
Most installs need no extra mobile-only secrets. Storage and Google already live on the server; the app reads them after Connect.
Only set these in Compose .env when you need them:
# Force members to update when you ship a newer store build
# Mobile__MinAppVersion=1.0.0
# Only if chat/notification hubs are NOT on the same public host as the API
# Mobile__ChatHubUrl=https://your-api-host
# Mobile__NotificationHubUrl=https://your-api-host
Related (same as website — not mobile-specific):
| Feature | Env |
|---|---|
| Google Sign-In | Same Web ExternalAuth__Google__ClientId as the website, plus Authorized redirect URI https://YOUR_FRONTEND_ORIGIN/auth/google/callback. No Android/iOS OAuth clients. |
| Voice / video calls | LiveKit__Url, LiveKit__ApiKey, LiveKit__ApiSecret (optional). Native v1: in-app + Expo push while the app is open or in background; no CallKit ring when the app is killed. |
| Media / avatars | Storage__Provider + R2__PublicUrl or Minio__PublicUrl |
Tell your members
- Download Bellamy Book on App Store / Play Store.
- Enter the API URL (
API_PUBLIC_URL), e.g.https://api.your-community.example.com— not a frontend-only URL. - Allow notifications for chat and calls.
Troubleshooting
| Symptom | Check |
|---|---|
| Cannot connect | They typed API_PUBLIC_URL (not frontend-only); HTTPS; https://your-api-host/api/mobile/bootstrap returns JSON |
| Works on PC, fails on phone | Do not use localhost — use the public API domain (or LAN IP only for local testing) |
| No push | Member allowed notifications; Expo push worker is running |
| Google button missing | Set ExternalAuth__Google__ClientId; reconnect in the app |
| Google opens the website instead of the app | The instance frontend must include the native bounce (state=bb-native. → bellamybook://google-oauth). Rebuild/redeploy the site that FRONTEND_PUBLIC_URL points at. Do not add bellamybook:// to the Google Web client. |
| Forced update | Mobile__MinAppVersion is higher than the installed app |