Skip to Content
Recall

Self-hosting

Architecture, configuration, the image and its admin CLI, backups, deploys and the repo layout.

Architecture

A request to recall.zakiego.com goes to a Cloudflare Worker (apps/edge). The Worker sends app paths (/app, /v1, /mcp, /health, /api/auth and the old dashboard paths) through a Cloudflare tunnel to your server, and everything else (/, /docs and assets) to Cloudflare Pages, which serves the static site (apps/site). On your server, a Docker host runs one Recall container (apps/server): one Go binary with the dashboard, REST, MCP, auth and the OAuth server, the job loop for ingest, extract, profile and ask, and embeddings through ONNX Runtime. The container keeps its state in the /data volume: recall.db (SQLite with FTS5 and sqlite-vec), models/ for the cached embedding model, uploads/ for files waiting for ingest, and backups/ for pre-deploy snapshots. For LLM work, the container calls an LLM gateway at POST /v1/chat.

  • One container. The server is one Go binary (recall) with the dashboard's files built in. The dashboard, the REST API, the MCP server, sign-in and the OAuth server, and the job loop all run in one process.
  • One SQLite file. recall.db in the data volume holds everything: users, sessions, workspaces, documents, chunks, memories, the FTS5 and sqlite-vec indexes, profiles and jobs. Migrations run at boot.
  • Embeddings on the box. multilingual-e5-small runs through ONNX Runtime in a child process that stops after 5 idle minutes (RECALL_EMBED_IDLE_MS in compose.yaml; 10 without it), so its memory goes back between bursts of work. The model downloads on first use (about 120 MB) and is cached in the volume under models/, so later boots don't fetch it again.
  • LLM calls through a gateway. Extraction, profiles and Ask call an LLM gateway's POST /v1/chat endpoint with a bearer key. The reply is an AI SDK UI message stream that Recall reads to the end and parses as JSON. Search never calls it.
  • Public routing. A Cloudflare Worker on recall.zakiego.com/* sends app paths to the container through a Cloudflare tunnel, and everything else to the static site on Cloudflare Pages. The container's port is published on the host's loopback interface only, so the tunnel is the only way in.

What the edge worker routes

PathGoes to
/app/*the app (the dashboard)
/v1/*, /mcp, /healththe app
/api/auth/*the app (sign-in and the OAuth server)
/login, /search, /ask, /graph, /add, /keys, /settings/*, /invite/*the app, which answers 302 to the same page under /app
everything elseCloudflare Pages

App requests pass through untouched: method, headers, body, streaming responses, cookies and redirects. If Pages answers with a redirect to its own hostname, the worker rewrites it to the public one.

The old-path redirects are temporary (302) on purpose. A cached permanent redirect from / would have hidden the landing page from anyone who visited during the switch.

Environment variables

Set these in the container's environment (the compose file reads an optional .env next to it). Secrets are only ever named here, never shown.

NameMeaning
RECALL_URLPublic base URL, origin only (the dashboard is at /app under it). Used as the auth base URL, the trusted origin, the WebAuthn origin, and the base for invite links. Defaults to a localhost URL for development
SESSION_SECRET32 or more random characters. Signs the OAuth requests handed to the login and consent pages and encrypts OAuth client secrets, so keep it stable. Without it, the login page says login isn't set up
PASSKEY_RP_IDOptional passkey relying party id. Defaults to the hostname of RECALL_URL
ADMIN_PASSWORD_HASHOptional. Only read when there are no users: creates the first owner from this pbkdf2 hash (make one with hash-password). Has no effect once any user exists
GATEWAY_URLBase URL of the LLM gateway
GATEWAY_KEYBearer key for the gateway. Without it every LLM call fails
EXTRACT_MODELModel for extraction, profiles and Ask. Defaults to claude-haiku-5-5
FALLBACK_MODELUsed when the gateway rejects EXTRACT_MODEL. Defaults to claude-haiku-5-5 (no fallback)
RECALL_DEFAULT_CONTAINERContainer used when a request names none. Defaults to default
DATA_DIRWhere recall.db, models/, uploads/ and backups/ live. /data in the image
RECALL_DB_PATHOptional override for the database file. Defaults to recall.db in DATA_DIR
MODELS_DIROptional override for the model cache. Defaults to models/ in DATA_DIR
RECALL_JOBSSet to off to run without the job loop. Nothing gets extracted, Ask returns 503, and no reminder emails go out
RESEND_API_KEYOptional. A Resend API key (sending access is enough) for reminder emails
RECALL_EMAIL_FROMOptional. The sender for reminder emails, on a domain verified in Resend, like Recall <reminders@example.com>. Email needs both this and RESEND_API_KEY; without them the app runs and says email isn't configured
GOOGLE_CLIENT_IDOptional. Google OAuth client ID for the Gmail connector
GOOGLE_CLIENT_SECRETOptional. Its client secret
CONNECTOR_SECRETOptional. 32 or more random characters that encrypt stored connector tokens. The Gmail connector stays off until all three are set

The image

The Dockerfile builds from the repo root. The site and the edge worker never enter the image.

  • Three stages. The first builds the dashboard (apps/app, Vite). The second builds the Go server (apps/server) with the dashboard's files embedded, and fetches ONNX Runtime. The final stage is gcr.io/distroless/cc-debian12: the recall binary and ONNX Runtime, no shell and no package manager. ONNX Runtime ships glibc builds only, so Alpine is out.
  • About 77 MB.
  • Runs as uid 1000. /data is a volume owned by that user.
  • Starts with recall serve.
  • A health check runs recall healthcheck (it fetches /health) every 30 s (5 s timeout, 3 retries) after a 60 s start period, which covers the first-boot model download.

The compose file adds:

  • restart: unless-stopped,
  • logs capped at 30 MB per container (3 files of 10 MB),
  • a named volume mounted at /data.

First boot

On boot the app opens the database (running migrations), creates the first user if ADMIN_PASSWORD_HASH is set and there are no users yet, warms up the embedding model, and starts the job loop. With no users and no hash, the login page tells you to create the first owner with the CLI. API keys keep working either way.

Admin CLI

The image's entrypoint is the admin CLI, recall (the server is recall serve). It opens the same database (running migrations like the app does) and prints only its result to stdout, so --quiet and --json output can be piped. Run it from the compose project directory:

# Users
docker compose exec app recall create-user alice                                  # new workspace "alice", alice owns it
docker compose exec app recall create-user bob --workspace alice --role member    # join an existing workspace
docker compose exec app recall create-user carol --workspace team --new-workspace # create workspace "team"
docker compose exec app recall list-users [--workspace <slug>]

# API keys
docker compose exec app recall create-key <name> [--workspace <slug>]
docker compose exec -T app recall create-key <name> --workspace alice --quiet > key.txt
docker compose exec app recall list-keys [--workspace <slug>]
docker compose exec app recall revoke-key <id>

# Other
docker compose exec app recall hash-password          # pbkdf2 hash for ADMIN_PASSWORD_HASH
docker compose exec -T app recall backup /data/backups/manual.db.gz
docker compose exec app recall backfill-dates [--workspace <slug>] [--container <name>]  # one-off: date older facts

# People
docker compose exec app recall backfill-people [--workspace <slug>] [--container <name>] [--now]
docker compose exec app recall suggest-people-merges [--workspace <slug>] [--container <name>]  # read-only
  • Every command takes --json. create-key --json prints {"id","name","prefix","workspace","key"}.
  • create-user asks for the password (or reads it from stdin). It checks the workspace before asking: --workspace <slug> fails when no such workspace exists unless --new-workspace is passed, so a typo can't create a stray workspace. A new workspace needs --role owner, which is the default.
  • --workspace can be left out of create-key and list-keys while there's only one workspace.
  • revoke-key works on any key, whatever its workspace.
  • backfill-people links facts saved before people existed. By default it queues one job per container for the app's job loop; --now runs it in the CLI process instead (it needs GATEWAY_URL and GATEWAY_KEY, which the container has). Facts already checked are skipped, so it's safe to run again.
  • suggest-people-merges lists people who are likely the same person: a shared email or handle, or look-alike names the embedding agrees on. It only reads. Merge the pairs you agree with on the People page.
  • -T turns off the TTY so redirected output holds only the result.
  • backfill-dates queues jobs and returns. The running server's job loop sends the facts to the gateway in batches. See dating older facts.

In a dev checkout, build the binary (go build -tags sqlite_fts5 -o bin/recall ./cmd/recall in apps/server) and run bin/recall <command>.

Backups

Nightly snapshot

A scheduled job on the host runs scripts/backup.sh every night:

  1. Inside the running container, recall backup - takes a consistent snapshot with SQLite's online backup API. It's safe while the app writes. The copy is switched out of WAL mode so it's one self-contained file, checked with quick_check, and gzipped.
  2. The gzip streams out of the container to the host and is checked with gzip -t.
  3. It's uploaded to an S3-compatible bucket under a dated key, and the uploaded size is checked against the local file.
  4. Both local copies are deleted.

A lifecycle rule on the bucket deletes snapshots after 30 days. The model cache isn't backed up, since the app downloads it again. If the container is restarting when the job runs, the snapshot gets 3 tries, 60 s apart, before the run fails. The script also refuses to run with less than 500 MB of free disk. Credentials come from the host's secret store at run time and are never written to a file.

Pre-deploy snapshots

Before every deploy, scripts/pre-deploy.sh snapshots the running database to /data/backups/pre-deploy-<UTC timestamp>.db.gz inside the volume and keeps the newest 3. A failed snapshot stops the deploy. On a first deploy there's no running app and nothing to back up. The hook also reinstalls the nightly backup job when scripts/backup.sh has changed.

Restore outline

Get a snapshot. Download one from the bucket, or copy a pre-deploy snapshot out of the volume with docker compose cp. Unzip it.

Check it before touching live data. Run pragma integrity_check and a row count with sqlite3 against the restored file.

Swap it in. Stop the app. Move the old recall.db and its -wal and -shm files aside (they must not sit next to the restored file). Copy the restored file into the volume as uid 1000, so the app can write to it. The image has no shell, so do the file steps in a throwaway container (any image with sh) that mounts the volume.

Start and check. Start the app and confirm /health returns 200. Remove the moved-aside files once everything looks right.

What a restore brings back:

  • Logins are whatever the snapshot holds. Someone who changed their password after it signs in with the old one, and passkeys added after it are gone.
  • A snapshot from before multi-user (migration 0004) has no users. On boot the app recreates the first owner from ADMIN_PASSWORD_HASH. If that isn't set, create an owner with create-user.

Deploys

A push to main fires a GitHub webhook on your server, which runs the deploy script in the checkout. The script pulls with git pull --ff-only, takes a snapshot with scripts/pre-deploy.sh and stops if that fails, tags the running image as :prev, then runs docker compose up --build --wait, which blocks until /health is healthy. If the new image is healthy, it keeps running. If the build or the health check fails, the script retags :prev and starts it again. Either way, old images are pruned at the end.

  • The deploy builds exactly what's on main, never local edits.
  • The snapshot runs before anything changes. If it fails, the deploy stops there.
  • The swap is health-gated. Compose waits for the health check, which fetches /health. If the build or the health check fails, the script puts the previous image back and starts it.
  • Each deploy keeps only one previous image (:prev).

Why a rollback after a migration is unsafe

Migrations run at boot and only go forward. If a new image migrates the database and then fails its health check, the script rolls back to the previous image, which now runs against a database it doesn't fully know. It may not read or write the new schema correctly.

/health catches this. The app compares the migrations recorded in the database with the ones it ships. When the database has migrations the build doesn't know, /health returns 503 with "error": "db_newer_than_app" and the unknown migration names (see GET /health). The rolled-back container then shows as unhealthy instead of looking fine.

To get out of it, deploy the newer build again (after fixing what failed), or restore the newest pre-deploy snapshot, which was taken before the migration ran.

Repo layout

PathWhat
apps/serverThe engine in Go: API, MCP, auth and the OAuth server, jobs, the admin CLI. Built into the Docker image
apps/appThe dashboard: a Vite single-page app under /app, embedded into the server binary
apps/siteThe public landing page and these docs (Next.js with Fumadocs, static export to Cloudflare Pages)
apps/edgeThe Cloudflare Worker on recall.zakiego.com/* that splits traffic between the site and the app
compose.yaml, Dockerfile, scripts/, ops/Deploy and backup, run from the repo root

The JS apps are a pnpm workspace. Every Go command takes -tags sqlite_fts5 (FTS5 is compiled in only under that tag).

pnpm install
cd apps/server
scripts/fetch-onnxruntime.sh                                     # ONNX Runtime, once per checkout
go build -tags sqlite_fts5 -o bin/recall ./cmd/recall
DATA_DIR=../app/data bin/recall serve                            # the server on :3000
go test -tags sqlite_fts5 ./...                                  # needs the model in apps/app/data/models
cd ../app && npx vite dev                                        # the dashboard, http://localhost:4800/app
pnpm site:dev                                                    # this site, from the repo root

On this page