# Operate a Fablewright instance This guide is for the person who runs the server. It covers backups, restores, upgrades, storage, accounts, monitoring, and moving an instance. For a first deployment, use [the installation guide](installation.md). Runtime variables are listed in [the README](../README.md#configuration). Writers can use [the writer's guide](using-fablewright.md). Read [the security model](security.md) before hosting other people's work. For common tasks, jump to [backup](#back-up), [restore](#restore), [restore drills](#prove-that-a-restore-works), [upgrade](#upgrade), [account recovery](#when-the-admin-is-the-one-locked-out), or [moving an instance](#moving-an-instance). ## Quick reference Every command takes `--help`. Run it inside the container, or on the host with Node, depending on the deployment. On a bare Node install, the systemd unit's `DATABASE_URL` is not in your shell. Add `--database /var/lib/fablewright/fablewright.db` to every command that reads or writes the database, or set `DATABASE_URL` in the shell. The Docker image sets it in the container environment. Cloudron's startup script exports it for the app process, not necessarily for a separate terminal. Pass `--database /app/data/fablewright.db` in Cloudron shell commands. | Task | Command | | --------------------- | ------------------------------------------------------------------ | | Back up | `node scripts/ops.mjs backup` | | Check a backup | `node scripts/ops.mjs verify --file ` | | Restore a backup | `node scripts/ops.mjs restore --file ` | | Prove a restore works | `node scripts/ops.mjs drill` | | Remove orphaned files | `node scripts/ops.mjs prune-uploads` | | Remove old history | `node scripts/ops.mjs prune-history` | | Reset a password | `node scripts/ops.mjs reset-password --email
--generate` | | Delete an account | `node scripts/ops.mjs delete-account --email
` | | Read the health check | `curl http://127.0.0.1:3000/api/health` | | Follow Docker logs | `docker compose logs -f fablewright` | | Follow systemd logs | `journalctl -u fablewright -f` | | Follow Cloudron logs | `cloudron logs -f` | ## First run 1. Keep the instance private until you create the first account. That account becomes the admin. 2. Set `ORIGIN` to the address writers will use. If the instance answers on more than one domain, leave `ORIGIN` empty and set `INSTANCE_ORIGIN` instead. 3. If you want reset email, configure `SMTP_HOST`, `MAIL_FROM`, and a declared address. Cloudron supplies them. Restart after changing environment values. 4. Take a backup and copy it off the machine. 5. Run a drill and make sure that it passes. 6. Open `/api/health` and make sure that it answers with the version and the commit you expect. 7. Sign in as the admin and open _Instance_. Sign-up closes when you claim the instance. Open it there if writers need to register themselves. ## What an instance holds The database and uploads share one data directory. The database holds manuscripts and accounts. Uploads hold note images and imported source files. A persistent signing secret keeps sessions valid across restarts. By default, the backup tool writes to `backups/` beside the database, and drills append to `restore-drills.ndjson` there. | Deployment | Directory | Database | Secret | | -------------- | ---------------------- | ------------------------------------- | --------------------------------- | | Docker Compose | `/data` in the volume | `/data/fablewright.db` | `/data/auth-secret` | | Bare Node | `/var/lib/fablewright` | `/var/lib/fablewright/fablewright.db` | `BETTER_AUTH_SECRET`, or the file | | Cloudron | `/app/data` | `/app/data/fablewright.db` | `/app/data/auth-secret` | `DATABASE_URL` chooses the database. The app stores uploads beside that file. The backup tool also looks there for `auth-secret`, unless `--data-dir` names another directory. The Docker entry point uses `DATA_DIR`, which defaults to `/data`, for its secret. If you customize the Docker database path, keep these paths aligned or set a persistent secret explicitly. A Cloudron install also holds `/app/data/cloudron-backup`, the copy of the database that the backup hook writes before each platform backup. See [Back up](#back-up). The container entry point and the Cloudron start script create `auth-secret` on first start and export it. Bare Node does not generate a persistent secret. Set `BETTER_AUTH_SECRET` in its service environment, or export a protected file's contents yourself. Without either, the app invents a value at startup and every restart ends existing sessions. A drill reports when the backup holds no secret. The tool is `scripts/ops.mjs`. It needs Node and nothing else, so it runs inside the container as well as on the host. The tool does not read `.env` or the app service's environment automatically. Use `node --env-file=/path/to/.env scripts/ops.mjs ...` for a Node environment file, or pass `--database`. Keep an environment-supplied signing secret in a separate protected copy: the tool copies `auth-secret`, not the value of `BETTER_AUTH_SECRET`. A successful drill with that variable assumes the operator will supply it again after a restore. ## Behind a reverse proxy When a proxy terminates TLS, the app has to know the public scheme and the client address. Set `ORIGIN` to the public URL when the instance has one. A declared origin pins the scheme, so the app does not read `X-Forwarded-Proto` for it. It does not supply the client address. Use `TRUST_PROXY=1` as well when the app must read the proxy's client-address header for sign-in limits. Cloudron supports more than one domain, so its start script leaves `ORIGIN` empty, sets `INSTANCE_ORIGIN` to the primary app domain and sets `TRUST_PROXY=1`. Enable the same value on Docker Compose or a bare Node install only when every request arrives through the proxy and the app port is not directly reachable. `TRUST_PROXY=1` makes the app trust `X-Forwarded-Proto` and resolve the client address from `X-Forwarded-For`. The entry point counts back `XFF_DEPTH` entries from the right, then writes that one address into the header. adapter-node and better-auth both read it, so neither can be given a fabricated address. The proxy must overwrite both headers and answer only for the host names this instance serves. A client that can reach the app directly and set the headers can choose its own scheme and its own sign-in throttle bucket. A proxy chain with more than one hop needs a larger `XFF_DEPTH`, and `ORIGIN` is the safer answer when it can be fixed. ## The public address, passkeys and reset links A passkey is bound to one domain. The browser will not offer it to another domain, and the server checks that the ceremony came from the address the instance declared. The address is `ORIGIN` when it is set, otherwise `INSTANCE_ORIGIN`. With neither, passkeys work on `localhost` only. Other addresses hide the controls, including `127.0.0.1` without a declared origin. A reset link carries that same address. It cannot carry the host the reset request arrived on, because whoever knows an address on the instance can ask for the link, and they choose that host. A link to a host they chose hands them the token the moment the writer opens it. So the link is built from `ORIGIN` or `INSTANCE_ORIGIN`, and an instance with neither writes the link to its log instead of emailing it. See [Accounts, mail and lockout](#accounts-mail-and-lockout). Cloudron supports alias domains, so its start script leaves `ORIGIN` empty and sets `INSTANCE_ORIGIN` to `CLOUDRON_APP_ORIGIN`. Passkeys therefore work on the primary app domain, and a reset link points there too. A writer who opens an alias domain signs in with a password. That is a property of WebAuthn, not a setting the app can change: no credential can cover two unrelated domains. A browser needs HTTPS or localhost to create a passkey. An instance served over plain HTTP on a LAN address cannot use them. Moving an instance to a new domain leaves its passkeys bound to the old one. The account page still lists them, so a writer can remove each one at the new address and add a replacement. ## Back up A full backup copies the database, uploads, and `auth-secret` file when present. An environment-supplied secret needs a separate protected copy. The backup is a directory named after the time and tool version. Its `manifest.json` records the database size, SHA-256 digest, migration level, and last app version to open it. `--database-only` copies the database and nothing else. It is for a deployment that copies the rest of the data directory itself. It is not a full backup, and a restore from it does not bring the uploads or the signing secret. You do not have to stop the app for a backup. SQLite's `VACUUM INTO` creates a consistent database copy while the app runs. The tool copies uploads separately. Avoid pruning files during a backup, and use a quiet period when practical. Run this command on a bare Node install: ```sh sudo -u fablewright node /opt/fablewright/scripts/ops.mjs backup \ --database /var/lib/fablewright/fablewright.db --keep 8 ``` Run this command on Docker Compose: ```sh docker compose exec fablewright node scripts/ops.mjs backup --keep 8 ``` The backup lands in `backups/` beside the database. `--keep 8` removes older backups beyond the newest eight and never removes the one it just wrote. The default is also eight. Copy the backup off the machine. A backup on the same disk as the instance can help after a bad upgrade. It does not survive the loss of that disk. Create a local destination, then copy the directory named in the backup output: ```sh mkdir -p ./backups docker compose cp 'fablewright:/data/backups/' ./backups/ ``` The copied directory on the Docker host still needs to reach a different machine or protected remote storage. Verification checks the copy you name, not your backup schedule or remote destination. ### Cloudron A Cloudron install uses platform backups and runs the tool through its backup hook. The platform copies `/app/data`, including the signing secret and uploads. The platform copies the database while the app is writing to it, so the manifest names a backup hook. Before each backup, the hook writes a `VACUUM INTO` copy into `/app/data/cloudron-backup`. Restore reads that snapshot instead of the live database files copied by the platform. The cost is a second copy of the database on disk and in the archive, so plan disk for twice the database. The restore hook runs before the app starts. It moves the copied database aside, so a restored instance keeps it as `fablewright.db.pre-restore-