Self-hosting

Everything you need to run HelpBites yourself, from a laptop to production. No prior knowledge of the codebase assumed.

HelpBites is one support inbox for every app you run. It ships as a single Nuxt app plus a handful of stateful services you run alongside it. This guide covers what those services are, how to wire them up, every environment variable, and three ways to deploy: local dev, Dokploy (the blessed path), and plain Docker Compose behind your own reverse proxy.

• New here? Start with Quick start (local).
• Going to production? Read Architecture then jump to Dokploy or Plain Docker Compose.
• Just need a variable? Environment reference.

Architecture#

One app container, four stateful services. The app is the only holder of the Parse master key and the only thing your users and operators ever talk to.

                         ┌───────────────────────────────┐
   browser widget  ──────▶                               │
   operator panel  ──────▶   app  (Nuxt + Nitro, :3000)  │
   your own API    ──────▶                               │
                         └──┬───────┬────────┬────────┬──┘
                            │       │        │        │
              master key    │       │        │        │  hybrid search
                 ┌──────────▼──┐ ┌──▼────┐ ┌─▼─────┐ ┌▼──────────┐
                 │  sb-parse   │ │sb-redis│ │  S3   │ │  sb-meili │
                 │ (Parse 9)   │ │ (7)   │ │bucket │ │ (Meili)   │
                 └──────┬──────┘ └───────┘ └───────┘ └───────────┘
                        │  SSE fan-out,     attachments  knowledge
                 ┌──────▼──────┐ rate limits, + knowledge  search
                 │  sb-mongo   │ email throttle  docs
                 │ (Mongo 7)   │
                 └─────────────┘

Optional integrations (all off unless configured): a LLM endpoint for AI auto-reply, Mailgun for email notifications, APNs for native operator push, and a remote embeddings service if you don't want to run the model in-process.

Why the sb- prefix? On a shared Dokploy network, other projects run services literally named parse, redis, or mongo. Docker DNS would resolve a bare name to any of them. The prefix keeps HelpBites talking to its own services.

Scaling note: every write publishes on one Redis channel and each app process fans it out to its own SSE clients, so you can run multiple app replicas behind a load balancer. Rate limits are shared through Redis. The one per-process cost is the local embedding model (cached on a volume per instance) — if you scale out, either accept the per-replica model cache or point EMBEDDING_ENDPOINT at a shared embeddings service.

Prerequisites#

• Docker + the Compose plugin (docker compose version ≥ v2).
• A domain and TLS for production. Dokploy or a reverse proxy terminates TLS; no HelpBites service publishes a host port on its own.
• For building/hacking locally: Bun 1.x.
• Optional accounts, only if you want the matching feature: an S3 provider, a Mailgun account, an OpenAI-style LLM endpoint, an Apple developer account (push).

Nothing else. Mongo, Parse, Redis, and Meili all run as containers from the provided Compose file.

Quick start (local)#

The fastest path to a running app on your machine. Uses the dev Compose overlay, which publishes ports on localhost and adds a Parse dashboard and RustFS.

git clone https://github.com/elrumo/help-bites-oss.git help-bites
cd help-bites
cp .env.example .env          # defaults already point at localhost
bun install

Bring up the backing services (note the --profile dev — it adds RustFS and the Parse dashboard):

docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up -d sb-mongo sb-parse sb-redis sb-meili sb-rustfs

Apply the schema and search setup (both idempotent — safe to re-run any time):

bun run schema:apply
bun run search:setup

Run the app in dev mode:

bun run dev

Open http://localhost:3100. The first visit shows a sign-up form — that creates your first operator account. From there: create a project, upload knowledge, grab the widget snippet.

What you get locally:

Seed some demo knowledge and run the end-to-end smoke test against the running app:

bun run seed:knowledge
bun run smoke

The dev overlay (docker-compose.dev.yml) is never used in production — it exists only to expose localhost ports so bun run dev and the Parse dashboard can reach the stack.

Deploy on Dokploy#

This is what HelpBites is built for. Dokploy runs the base docker-compose.yml as a "Docker Compose" application and attaches domains per service — no service publishes a host port.

1. Create the application#

1. In Dokploy, Create → Compose (Docker Compose app).
2. Point it at your Git repository (Dokploy re-clones on each deploy) or paste the compose. Use the repo's docker-compose.yml as-is.
3. Set the build context so the app service's build: . finds the Dockerfile.

Persistence: a git-sourced deploy re-clones the code directory on every deploy, so nothing durable may live under it. All state lives in the named volumes (mongo-data, redis-data, meili-data, model-cache) — those survive redeploys. Don't bind-mount app state into the repo tree.

2. Set environment variables#

Paste your production values into Dokploy's Environment tab (this becomes the .env the app service reads via env_file: .env). See the Environment reference and the production .env example below. At minimum set: APP_URL, PARSE_ID, PARSE_MASTER_KEY, MEILI_MASTER_KEY, and the S3_* group.

The compose file injects the internal service URLs for you, so do not set these in production — they're overridden anyway:

PARSE_URL: http://sb-parse:1337/parse
REDIS_URL: redis://sb-redis:6379
MEILI_URL: http://sb-meili:7700
TRANSFORMERS_CACHE: /models
NITRO_PORT: "3000"

3. Attach domains#

From the Domains tab, attach domains by service name + container port:

Dokploy terminates TLS and routes to the container port. Point APP_URL at the app domain.

If you expose sb-meili publicly: the compose runs it with MEILI_ENV=production, and /health is unauthenticated. Set a strong MEILI_MASTER_KEY — it's the only thing protecting your search data and settings — and give the app its own scoped MEILI_API_KEY (see Meilisearch). Better still, restrict the domain to the addresses that need it (a Traefik ipAllowList middleware), or don't attach a domain to it at all if you don't need external search access.

4. Deploy#

Hit Deploy. On boot the app container runs, in order:

bun scripts/ensure-schema.mjs --apply      # create/patch classes, CLPs, indexes
bun scripts/migrate-workspaces.mjs --apply # an older install moves into one workspace
bun scripts/migrate-changelog-public.mjs --apply # projects whose board published the changelog get their own switch
bun scripts/ensure-search.mjs              # create Meili indexes + settings, backfill workspaceId
bun .output/server/index.mjs               # start the app

All are idempotent. ensure-search never fails the boot (Meili is optional). There is no separate migration step: the schema is reconciled, and an install from before workspaces is moved into one, on every boot (see Upgrades). With more than one app container, let one of them migrate and set RUN_MIGRATIONS=0 on the rest.

Then open your app domain and create the first operator.

Deploy with plain Docker Compose#

Not on Dokploy? Same compose, you just supply the reverse proxy. Because no service publishes a host port, put a proxy in front of app:3000.

1. Configure#

The quick way: scripts/install.sh help.example.com writes .env with generated secrets, bundled storage and the bundled Caddy (--profile proxy) for HTTPS. Point DNS for help.example.com and files.help.example.com at the server first; Caddy gets the certificates by itself. Without a domain it prepares a trial on http://localhost:3100.

By hand:

git clone https://github.com/elrumo/help-bites-oss.git && cd help-bites-oss
cp .env.example .env
$EDITOR .env      # replace every change-me value (see Environment reference)

Set APP_URL to your public HTTPS URL. Leave PARSE_URL, REDIS_URL, MEILI_URL as the compose provides them (internal service DNS). Production refuses to start while PARSE_MASTER_KEY or MEILI_MASTER_KEY still holds the change-me placeholder.

2. Start the stack#

docker compose up -d

This starts sb-mongo, sb-parse, sb-redis, sb-meili, and app (pulled from Docker Hub as elrumo/helpbites; add -f docker-compose.build.yml --build to build it from your checkout instead). parse-dashboard stays down (it's behind the dev profile), and so does the bundled sb-rustfs unless you opt in with --profile rustfs (see S3 storage).

3. Put a proxy in front#

The app container listens on 3000 but publishes nothing to the host. Add a reverse proxy on the same Docker network. A minimal Caddy example (auto-TLS) — save as Caddyfile and run Caddy on the compose network:

support.yourdomain.com {
    reverse_proxy app:3000
}

Or an nginx server block if you terminate TLS elsewhere:

server {
    listen 80;
    server_name support.yourdomain.com;

    location / {
        proxy_pass http://app:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Server-Sent Events (/v1/events) — do not buffer, keep it open.
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

SSE matters. HelpBites pushes live updates over /v1/events (Server-Sent Events). Any proxy in front must disable response buffering and allow long read timeouts on that path, or messages will arrive in laggy bursts. Caddy handles this automatically; nginx needs proxy_buffering off as shown.

4. Point a bucket at it#

If you're not using AWS S3, the simplest self-hosted option is the bundled RustFS (docker compose --profile rustfs up -d) — or point at a separate MinIO/Garage/RustFS deployment, then set the S3_* variables to match. See S3 storage.

Environment reference#

The app reads a .env file (Compose passes it to the app service via env_file: .env). Copy .env.example and fill it in. Below, Required means the app won't function without it; Recommended means a core feature degrades without it; Optional means a feature stays off until you set it.

Core#

Parse + MongoDB#

The app is the only master-key holder. In production, Compose sets PARSE_URL for you.

Redis#

Search (Meilisearch)#

Knowledge embeddings#

Semantic search runs a CLIP text encoder in-process by default (via transformers.js on the onnxruntime-node backend). You have three modes: local model (default), remote endpoint, or lexical-only.

AI support agents (auto-reply)#

Off unless a project has an assistant with autoReply enabled and an LLM configured. OpenAI-compatible / LiteLLM style.

Error tracking (GlitchTip or Bugsink)#

Optional, and either tracker (or both) can be set up. The bundled glitchtip Compose profile runs a Sentry-compatible GlitchTip instance with its own Postgres database. Attach a public domain to sb-glitchtip:8000; Sentry SDKs must be able to reach that domain. Follow the bootstrap and connection steps in ERRORS.md. The bugsink profile runs a single-container Bugsink on SQLite; attach a public domain to sb-bugsink:8000 the same way.

An external GlitchTip installation works too: set GLITCHTIP_URL and, if its API is on another origin, GLITCHTIP_API_URL (or the API URL field in Connect error tracking).

S3 storage#

Holds image attachments and uploaded knowledge documents. Works with any S3-compatible provider. The app throws when an upload is attempted and these aren't set, so configure them for any real deployment.

Attachments and knowledge docs are stored under unguessable, project-prefixed keys. The bucket is public-read by design (attachment URLs are shared into conversations). Knowledge source documents are only ever served through an authenticated admin route, not their public URL.

Email (Mailgun)#

Optional. Enables the email send API and the email notifications to end users and operators. All three of the first must be set or email is skipped (the send API answers 503).

Native push (APNs)#

Optional. Required only for the native operator app's push notifications.

Agent seeding (CLI only)#

Defaults for bun run add-agent; command-line args override them. Not read by the running app.

Script-only#

Read by helper scripts, not the app.

Example production .env#

# --- app ---
APP_URL=https://support.yourdomain.com

# --- Parse (change the master key!) ---
PARSE_ID=helpbites
PARSE_MASTER_KEY=<64+ random chars>
PARSE_SERVER_DATABASE_URI=mongodb://sb-mongo:27017/helpbites
# PARSE_URL / REDIS_URL / MEILI_URL are injected by docker-compose — leave unset.

# --- Meilisearch (strong key; the endpoint may be public) ---
MEILI_MASTER_KEY=<32+ random chars>
# The app's scoped key, from `docker compose exec app bun scripts/meili-key.mjs` after the first deploy.
MEILI_API_KEY=<printed key>

# --- Embeddings: run locally on CPU (default). To offload:
# EMBEDDING_ENDPOINT=https://embeddings.yourdomain.com/v1/embeddings
# EMBEDDING_API_KEY=...
# ...or go lexical-only:
# KNOWLEDGE_DISABLE_EMBEDDINGS=1

# --- S3 (example: AWS) ---
S3_ENDPOINT=s3.eu-west-1.amazonaws.com
S3_USE_SSL=true
S3_ACCESS_KEY=<key>
S3_SECRET_KEY=<secret>
S3_BUCKET=help-bites-prod
S3_PUBLIC_URL=https://help-bites-prod.s3.eu-west-1.amazonaws.com
S3_REGION=eu-west-1
S3_SET_PUBLIC_POLICY=false   # manage the bucket policy in AWS yourself

# --- Email (optional) ---
MAILGUN_API_KEY=<key>
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_API_BASE_URL=https://api.eu.mailgun.net
MAILGUN_FROM_EMAIL=[email protected]

# --- AI auto-reply (optional) ---
# LITELLM_API_BASE_URL=https://llm.yourdomain.com
# LITELLM_API_KEY=<key>
# LLM_DEFAULT_MODEL=mimo-pro-v2

# --- Native push (optional) ---
# APNS_KEY_ID=...
# APNS_TEAM_ID=...
# APNS_BUNDLE_ID=com.helpbites.operator
# APNS_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
# APNS_ENV=production

Generate secrets with, e.g.:

openssl rand -base64 48

External services#

You can run everything in the provided Compose file, or point HelpBites at managed services. Mix and match.

MongoDB#

Provided as sb-mongo (Mongo 7). To use a managed Mongo (Atlas, etc.) instead, drop sb-mongo and set PARSE_SERVER_DATABASE_URI to your connection string. Parse needs disableIndexFieldValidation (the compose sets this via PARSE_SERVER_DATABASE_OPTIONS) so the schema script can declare indexes on Mongo's own key names.

S3 storage#

Any S3-compatible bucket works. Two common setups:

Self-hosted (RustFS/MinIO/Garage — the dev overlay bundles RustFS on localhost:9000):

S3_ENDPOINT=localhost
S3_PORT=9000
S3_USE_SSL=false
S3_ACCESS_KEY=rustfsadmin
S3_SECRET_KEY=rustfsadmin
S3_BUCKET=help-bites
S3_PUBLIC_URL=http://localhost:9000/help-bites

AWS S3 — omit S3_PORT, use SSL, set the region, and manage the bucket policy yourself:

S3_ENDPOINT=s3.eu-west-1.amazonaws.com
S3_USE_SSL=true
S3_BUCKET=help-bites-prod
S3_PUBLIC_URL=https://help-bites-prod.s3.eu-west-1.amazonaws.com
S3_REGION=eu-west-1
S3_SET_PUBLIC_POLICY=false

The bucket is created on first use if missing. On non-AWS providers, the app also applies a public-read policy unless S3_SET_PUBLIC_POLICY=false.

Bundled RustFS (--profile rustfs) — if you don't want to run an external bucket, the compose can bring up a RustFS instance alongside the app. It's off by default; the app uses your external S3 unless you opt in. Enable it and point S3_* at it:

# start the stack with RustFS included
docker compose --profile rustfs up -d

# .env — use the bundled bucket
S3_ENDPOINT=sb-rustfs
S3_PORT=9000
S3_USE_SSL=false
S3_ACCESS_KEY=<pick one>          # sb-rustfs reuses these two
S3_SECRET_KEY=<pick a strong one> # (default rustfsadmin — change it)
S3_BUCKET=help-bites
S3_PUBLIC_URL=https://files.yourdomain.com   # a URL browsers can reach — see below

Notes:

• sb-rustfs and the app share S3_ACCESS_KEY / S3_SECRET_KEY. Set them once; RustFS boots with those credentials and the app authenticates with them.
• S3_PUBLIC_URL must be browser-reachable. sb-rustfs only exposes its ports on the internal network (like every other service here), so http://sb-rustfs:9000 works app→storage but not from a browser. Attach a domain to sb-rustfs → 9000 (Dokploy Domains tab) and set S3_PUBLIC_URL to it. The console is on 9001 if you want a UI.
• Data lives in four named volumes (rustfs-data-0…3). RustFS runs as UID 10001 and enforces a 4-path disk layout, so a one-shot sb-rustfs-init container pre-owns the volumes before it starts. This mirrors RustFS's own single-node reference compose — back up these four volumes like any other state.
• In production there's no published port for sb-rustfs; the dev overlay (docker-compose.dev.yml, --profile dev) publishes 9000/9001 on localhost for local use.

Meilisearch#

Provided as sb-meili (v1.53). bun run search:setup (and the boot entrypoint) creates the indexes, settings, and the userProvided embedder. If you expose it publicly, set a strong MEILI_MASTER_KEY. To use Meilisearch Cloud, set MEILI_URL and MEILI_MASTER_KEY and drop the sb-meili service.

The app shouldn't hold the master key, which can mint keys and delete every index. Give it a scoped one:

1. docker compose exec app bun scripts/meili-key.mjs (locally: bun run search:key). It creates the app's key, limited to the knowledge, conversations and endusers indexes and the actions the app uses, and prints it. Re-running prints the same key.
2. Put MEILI_API_KEY=<that key> in .env and redeploy.
3. Uncomment MEILI_MASTER_KEY: "" under the app service in docker-compose.yml and redeploy again: the app container no longer carries the master key; sb-meili keeps it.

Until MEILI_API_KEY is set the app uses MEILI_MASTER_KEY and logs a warning.

LLM endpoint (AI auto-reply)#

Any OpenAI-compatible / LiteLLM endpoint. Set LITELLM_API_BASE_URL, LITELLM_API_KEY, and LLM_DEFAULT_MODEL. Auto-reply stays off until a project has an assistant with autoReply enabled — the env vars just make it possible. Per-agent endpoint/key/model settings override the defaults. See docs/KNOWLEDGE.md for how knowledge grounds the answers.

Mailgun (email)#

Set MAILGUN_API_KEY, MAILGUN_DOMAIN, and MAILGUN_FROM_EMAIL. Pick the region base URL (MAILGUN_API_BASE_URL). Without all three, email notifications are simply skipped and the send API answers 503 — the app runs fine.

For delivery status, set MAILGUN_WEBHOOK_SIGNING_KEY (Mailgun → Sending → Webhooks → HTTP webhook signing key) and add https://<your domain>/v1/webhooks/mailgun for delivered, opened, clicked, permanent and temporary failure, complaints and unsubscribes, on every domain your projects send from. See docs/EMAIL.md.

APNs (native push)#

Only for the native operator app (helpbites-native). Create an APNs auth key in your Apple developer account and set the APNS_* group. Push stays disabled until these are present.

First run#

1. Create the first operator. Open APP_URL — a fresh install shows a sign-up form. That first sign-up becomes the first operator, so set SETUP_TOKEN (the form then asks for it) or finish it straight after deploying: until then anyone who finds the URL can claim the instance. (Add teammates later from the Team page, or docker compose exec app bun scripts/add-agent.mjs.) Admin API keys act as their owner, expire after 90 days unless you choose otherwise, and are revoked with a password reset. Changing an account's email asks for the password and tells the old address, and Parse locks an account for 15 minutes after ten wrong passwords.
2. Create a project. Panel → Projects → New project. You get a public key (pk_…) and a secret (sk_…). Set the site URL, allowed widget origins, the reply name, and notification emails.
3. Add knowledge (optional). Upload a SUPPORT_FAQ.md, review detected FAQs, organize them, and assign them to an assistant. See docs/KNOWLEDGE.md.
4. Connect your app. Mint identity tokens on your backend and drop in the widget (or use the API directly). Full walkthrough: docs/CONNECTING.md. Interactive API reference lives at APP_URL/_docs/scalar.

Mint a test token against a running deployment without writing any host code:

bun scripts/dev-token.mjs <projectId> <userId> "Demo user" [email protected]

Operations#

Schema migrations#

There is no manual migration step. The app container runs ensure-schema.mjs --apply on every boot: it creates missing classes, adds missing fields, and re-asserts CLPs and indexes. Existing data is preserved. To preview pending changes without applying (exits 2 when work is pending):

bun run schema

Backups#

All durable state is in named Docker volumes. Back these up:

Plus your S3 bucket (attachments + knowledge docs) — back that up with your provider's tooling. Example Mongo dump:

docker compose exec sb-mongo mongodump --db helpbites --archive > helpbites-$(date +%F).archive

Restore into an empty database with the stack stopped except Mongo:

docker compose up -d sb-mongo
docker compose exec -T sb-mongo mongorestore --db helpbites --archive --drop < helpbites-2026-01-31.archive
docker compose up -d

A nightly dump from cron is enough for most installs:

0 3 * * * cd /opt/helpbites && docker compose exec -T sb-mongo mongodump --db helpbites --archive | gzip > /var/backups/helpbites-$(date +\%F).archive.gz

Rebuilding the search index#

If Meili data is lost or you want to backfill:

bun run search:setup   # recreate indexes + settings
bun run reindex        # backfill conversations / end-users / FAQs (lexical)

Knowledge FAQs re-embed as they're reindexed (unless embeddings are disabled).

Scaling out#

Run multiple app replicas behind your load balancer — SSE fan-out goes through Redis pub/sub, so a client connected to replica A still gets events from a write on replica B. Rate limits are shared through Redis. If you scale the app, prefer EMBEDDING_ENDPOINT (a shared embeddings service) over each replica caching the model. Mongo, Redis, and Meili remain single logical instances (or their own managed clusters).

Health checks#

Mongo, Parse, Redis and app have a healthcheck; app waits for sb-parse and sb-redis to be healthy before starting. GET /v1/health/live only says the process is up (the container healthcheck uses it). GET /v1/health also checks Parse, Redis, Meilisearch, S3 and the worker: point your uptime monitor at that one.

Logs#

docker compose logs -f app          # the app
docker compose logs -f sb-parse     # data layer
docker compose logs --tail=100 app  # recent

Verifying a deployment#

The smoke test drives a real conversation end-to-end (auth, messages, attachments, SSE) against a running app. Point BASE at your deployment:

BASE=https://support.yourdomain.com bun run smoke

If SSE can't be reached from where you run it (e.g. through a strict proxy), skip just that check:

SKIP_SSE=1 BASE=https://support.yourdomain.com bun run smoke

Pure-logic unit tests (no running stack needed):

bun test

Quick manual checks:

• APP_URL/ loads the landing page.
• APP_URL/_docs/scalar renders the API docs.
• Sign-up creates an operator; the panel loads at /inbox.
• Send a widget/API message and confirm it appears live in the panel (SSE works).

Upgrades#

Read CHANGELOG.md first. Plain Compose pulls the new image; the entrypoint reconciles the schema on boot:

git pull                 # new compose file and Caddyfile, if any
docker compose pull
docker compose up -d

Pin a release with HELPBITES_VERSION=0.1.0 in .env (default latest). To roll back, set the previous version and run docker compose up -d again. Back up first: a rollback does not undo a schema change. Building from source instead: add -f docker-compose.build.yml and --build. On Dokploy, redeploy.

Volumes persist, so data carries over. The schema script patches the DB forward automatically. To also pull newer service images (Mongo/Parse/Redis/Meili), bump the pinned tags in docker-compose.yml deliberately and:

docker compose pull && docker compose up -d

Service image tags are pinned on purpose (mongo:7, parse-server:9.10.0, redis:7-alpine, meilisearch:v1.53.2). Upgrade them one at a time and test — Parse and Meili occasionally have breaking changes between majors.

Upgrading to workspaces#

Versions from before workspaces upgrade on their own, on the first boot of the new image:

• Everything moves into one workspace (DEFAULT_WORKSPACE_NAME). The oldest operator becomes its owner and every other operator an admin, which is the access everyone had before.
• Error-tracker settings move from the install into the workspace.
• Search documents gain their workspace id in place. Nothing is re-embedded.
• The panel looks the same with one workspace: the switcher only appears once there is a second.
• API keys keep working and now belong to that workspace.

The migration is idempotent; running it again changes nothing. Two things now need a setting that did not before:

• An assistant's LLM endpoint or an error-tracker URL typed into the panel that points at a private address (a LiteLLM or GlitchTip next to the app) needs ALLOW_PRIVATE_NETWORK=1.
• Outbound requests to those URLs now connect to the exact address that passed the safety check. Behind an HTTP proxy that allows hosts by name, they will be refused (the proxy is asked for an IP). No proxy is set by default.

Licensing notes for the services#

HelpBites itself is AGPL-3.0 (and ee/ commercial; see EDITIONS.md). The services it runs next to have their own licenses, which matter mostly if you offer HelpBites as a service:

Troubleshooting#

App can't reach Parse / "master key rejected". Parse 7+ refuses the master key from non-loopback addresses unless allow-listed. The compose sets PARSE_SERVER_MASTER_KEY_IPS: "0.0.0.0/0,::/0" for the internal network — keep it. Also confirm PARSE_ID and PARSE_MASTER_KEY match between the app and sb-parse.

Services resolve to the wrong container. On a shared network, use the sb- prefixed names (sb-parse, sb-redis, sb-mongo, sb-meili). A bare parse or redis may resolve to another project's service.

"Unsupported device" on boot / embeddings. ICON_EMBEDDING_DEVICE must be cpu (default) or cuda (Linux + GPU). wasm/webgpu are browser-only. To avoid the model entirely, set KNOWLEDGE_DISABLE_EMBEDDINGS=1 or point EMBEDDING_ENDPOINT at a remote service.

Slow first boot. The local embedding model downloads on first use and caches to TRANSFORMERS_CACHE (/models volume). Subsequent boots are fast. Disable embeddings or use a remote endpoint to skip the download.

Attachments/knowledge uploads fail with an S3 error. S3_ENDPOINT, S3_ACCESS_KEY, and S3_SECRET_KEY must all be set. On AWS, set S3_SET_PUBLIC_POLICY=false and manage the bucket policy yourself (the app can't set a public policy on a locked-down AWS bucket). Confirm S3_PUBLIC_URL actually resolves to the bucket from a browser.

Search returns nothing / degraded. If Meili is down the app falls back to a Parse keyword scan — functional but not hybrid. Check sb-meili health and MEILI_URL. Run bun run search:setup then bun run reindex.

Live updates lag or arrive in bursts. Your proxy is buffering SSE. Disable response buffering on /v1/events (proxy_buffering off in nginx; Caddy is fine by default) and allow long read timeouts.

Meili rejects requests / 403. In production it needs a key: the app sends MEILI_API_KEY, or MEILI_MASTER_KEY when that is unset. A scoped key made for another master key (the master key changed) is refused; run meili-key.mjs again with the current one. With only the master key, make sure the same value is set for both sb-meili and the app.

Email never sends. All three of MAILGUN_API_KEY, MAILGUN_DOMAIN, MAILGUN_FROM_EMAIL must be set, and MAILGUN_API_BASE_URL must match your Mailgun region (EU vs US).

Security checklist#

Before you expose a deployment:

• Changed PARSE_MASTER_KEY from the default to a long random value.
• Changed MEILI_MASTER_KEY (especially if sb-meili has a public domain), and gave the app a scoped MEILI_API_KEY.
• Set SETUP_TOKEN before the first visit, so only you can create the first operator.
• Changed S3_SECRET_KEY (RustFS reuses it as its root credential if self-hosting).
• APP_URL is your real HTTPS origin; TLS terminated by Dokploy/proxy.
• Did not attach a public domain to sb-parse unless you need it.
• Set restrictive allowed widget origins on each project (the widget only loads from listed origins; anything else gets no token).
• Project secrets (sk_…) live only on your backend — never shipped to a browser. Rotate from the project page if one leaks.
• The dev overlay (docker-compose.dev.yml) and the parse-dashboard service are not running in production. Use the bundled RustFS in prod via --profile rustfs (not the dev overlay), so it isn't published on localhost with dev-default credentials.
• Backups configured for mongo-data and your S3 bucket.
• On AWS S3, S3_SET_PUBLIC_POLICY=false and the bucket policy scoped to exactly what attachment serving needs.
• ALLOW_PRIVATE_NETWORK is off unless something the panel calls really lives on your private network.

Related docs: Editions · Connecting an app · Knowledge & AI assistants · API reference at APP_URL/_docs/scalar.