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. Runtime variables are listed in the README.
Writers can use the writer's guide. Read the security model before hosting other people's work.
For common tasks, jump to backup, restore, restore drills, upgrade, account recovery, or 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 <backup> |
| Restore a backup | node scripts/ops.mjs restore --file <backup> |
| 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 <address> --generate |
| Delete an account | node scripts/ops.mjs delete-account --email <address> |
| 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 #
- Keep the instance private until you create the first account. That account becomes the admin.
- Set
ORIGINto the address writers will use. If the instance answers on more than one domain, leaveORIGINempty and setINSTANCE_ORIGINinstead. - If you want reset email, configure
SMTP_HOST,MAIL_FROM, and a declared address. Cloudron supplies them. Restart after changing environment values. - Take a backup and copy it off the machine.
- Run a drill and make sure that it passes.
- Open
/api/healthand make sure that it answers with the version and the commit you expect. - 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.
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.
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:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs backup \
--database /var/lib/fablewright/fablewright.db --keep 8
Run this command on Docker Compose:
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:
mkdir -p ./backups
docker compose cp 'fablewright:/data/backups/<backup-directory>' ./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-<time>. Delete it
when the restore is the one you wanted. A backup that holds no snapshot, such as
one taken before the hook existed, restores the copied database as it is.
Do not drill that snapshot. It holds no uploads, so a drill refuses it as soon as the database names an image. Take an ordinary backup inside the container and drill that instead. See Prove that a restore works.
From a workstation with the Cloudron CLI, replace fable.example.com with your
app's address:
cloudron exec --app fable.example.com -- gosu cloudron:cloudron \
node /app/code/scripts/ops.mjs backup --database /app/data/fablewright.db
cloudron exec --app fable.example.com -- gosu cloudron:cloudron \
node /app/code/scripts/ops.mjs drill --database /app/data/fablewright.db
These commands exercise the app tool, not a restore of the Cloudron platform archive. Test the platform restore separately on another app or server.
Run the backup on a schedule #
deploy/fablewright-backup.service and deploy/fablewright-backup.timer do this
weekly for a bare Node install. Install them the same way as the app unit:
sudo cp deploy/fablewright-backup.service deploy/fablewright-backup.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now fablewright-backup.timer
systemctl list-timers fablewright-backup.timer
The timer runs weekly and catches up after downtime. Choose a more frequent
schedule if losing a week of work is unacceptable. The app and backup units have
separate environments. Add the same private EnvironmentFile to the backup unit
if you keep the signing secret or other needed values there.
For Docker Compose, use the host's cron:
15 3 * * * cd /srv/fablewright && docker compose exec -T fablewright node scripts/ops.mjs backup --keep 8
Make sure a backup is sound #
node scripts/ops.mjs verify --file /data/backups/fablewright-2026-10-27T00-08-23Z-v1.0.0
The command opens the copy read only. It runs PRAGMA integrity_check and
PRAGMA foreign_key_check. It compares the database digest, upload file count,
and upload byte total with the manifest. It also prints the migration level,
last app version, and row counts.
The command refuses a directory that is not a backup this tool wrote. The
manifest must name format 1 and the database file fablewright.db. It must
record the size and the digest of the database, and both must match the file. It
must say whether the copy holds the signing secret and the uploads, and the
directory must agree. A secret or an uploads directory that the manifest does not
name fails the check, and so does one that the manifest names but the directory
does not hold. The directory must hold only manifest.json, fablewright.db,
auth-secret, and uploads. A link in place of a file fails the check, because
a restore would follow it out of the backup. The migrations must be readable.
A restore applies the same checks. It makes sure that the destination uploads directory is a directory, not a link, before it replaces anything.
Uploads have no per-file digest in this manifest. Matching counts and sizes do not prove that each image or imported file has unchanged contents. Verification also cannot recover a file already missing when the backup was taken. Read drill details and inspect important files after a restore.
Run it on the off-machine copy too. If verification fails, keep the files for diagnosis but do not trust that copy for a routine restore. Try another backup.
Restore #
Stop the app first. A running app keeps writing to the database it opened, and a restore moves that file aside.
- Stop the service. Use
systemctl stop fablewright,docker compose down, or the Cloudron stop button. - Make sure that the backup is sound with the
verifycommand above. - Run the restore for your deployment. The examples below use a backup directory named after the time and the version.
- Start the version that took the backup. The backup records it in
manifest.jsonasschema.lastVersion.
Bare Node:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs restore \
--file /var/lib/fablewright/backups/fablewright-2026-10-27T00-08-23Z-v1.0.0 \
--database /var/lib/fablewright/fablewright.db
Docker Compose, after docker compose down:
docker compose run --rm fablewright node scripts/ops.mjs restore \
--file /data/backups/fablewright-2026-10-27T00-08-23Z-v1.0.0
docker compose up -d
The service entry point runs first, so the restore sees the same signing secret and the same data volume. The container is removed after the command.
Cloudron uses the app's Restore button. The platform restores its archive and
runs the restore hook before the app starts. Do not run restore by hand against
/app/data on Cloudron.
The tool renames the database it replaces, with its journal files, to
fablewright.db.pre-restore-<timestamp>. It copies the secret and uploads that
the backup contains. A backup that fails verification stops before replacement.
A missing upload already absent from the backup can still pass those checks.
A link where the destination uploads directory belongs stops the restore before
it writes anything.
Restore merges backed-up uploads into the destination directory. It does not
remove extra files or preserve an earlier secret separately. Keep a full backup
of the destination before restoring. The renamed database alone is not a full
undo of the restore. If the deployment supplies BETTER_AUTH_SECRET, make sure
that it matches the restored instance's secret.
After startup, review accounts, project memberships, and secret links. The backup can restore permissions or credentials revoked after it was taken. Check the words, pictures, and source downloads before deleting the pre-restore database.
Delete the pre-restore database after the restored instance has run for a while
and the words look right. It holds the database from before the restore, and it is
not part of the next backup.
Prove that a restore works #
A backup is a copy. Until something restores it, it is a copy you hope works. A drill is that exercise, and it writes down what it found.
node scripts/ops.mjs drill
Run it with the app's DATABASE_URL, or pass --database.
The command does four things:
- It takes a backup, or uses the one
--file DIRnames. - It restores the backup into an empty temporary directory, which stands in for the data directory of a clean server.
- It reads the restored copy back.
- It appends the result to
<data-dir>/restore-drills.ndjsonand prints it.
It never restores over the live database. It can write a backup and a drill record beside it, so the command needs write access there. Run it while the app serves, with the same database path and signing-secret environment:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs drill \
--database /var/lib/fablewright/fablewright.db
The temporary directory is removed at the end. Allow space for the database and
backed-up uploads, plus a new backup if the command creates one. --scratch DIR
chooses a parent directory for a new temporary subdirectory, including on another
disk. It never names a destination for a live restore.
What a drill checks #
| Check | Passing means |
|---|---|
| The backup | The digest matches the manifest, and SQLite reads the file. |
| Database | SQLite integrity and declared foreign-key checks pass. Plain identifiers without foreign keys are outside that relationship check. |
| Schema | The copy holds the migrations the manifest recorded, and none that this build does not ship. |
| What it holds | The supported row counts match the manifest, including accounts, passkeys, manuscript data, history, sharing, goals, and import reports. |
| Words | No scene claims a positive word count while holding empty text. The drill cannot compare it with unsaved browser prose. |
| Signing secret | A restored secret file matches the backup. With no file, a nonempty BETTER_AUTH_SECRET passes, but the tool cannot compare it with the old host's value. |
| Accounts | The database has no accounts yet, or at least one password credential exists. The drill does not test anybody's password. |
| Images and files | Upload counts and byte totals match. Missing referenced files appear in the detail and do not always fail the overall drill. Inspect that detail. |
A failed check exits with status 1 and names what did not come back. The record holds the same words, so a later reader sees the failure too.
Read the record #
The trail is one JSON line per drill, newest last:
tail -n 1 /data/restore-drills.ndjson
Instance in the app shows the newest record. Until the first drill it says that no restore has been exercised on this instance.
A clean server, step by step #
A local drill exercises the backup and restore tool. To test recovery on another machine, install the runtime and supply the protected signing-secret environment there too:
-
Take a backup and copy its directory to the second machine.
-
Install the same release there. It needs no start: the tool reads the backup.
-
Drill the copy, naming the database the restored instance will use:
node /opt/fablewright/scripts/ops.mjs drill \ --file ~/fablewright-2026-10-30T19-40-11Z-v1.0.0 \ --database /var/lib/fablewright/fablewright.db -
Restore it for real:
node /opt/fablewright/scripts/ops.mjs restore \ --file ~/fablewright-2026-10-30T19-40-11Z-v1.0.0 \ --database /var/lib/fablewright/fablewright.db -
Start the instance and sign in with an account that existed before the backup.
-
Open a project, read a scene, and open its version history.
-
Download one project export and open the zip. The drill cannot press a download button, so this step is yours.
Record the date and result with the deployment records. The drill log covers the tool's checks, not the later browser steps. Record the sign-in, scene inspection, and export results separately.
What a drill does not cover #
- The machine, its disk, and the network path between the two.
- An export from the restored instance, which needs a browser and a session.
- A writer's sign-in, which needs the password only that writer knows.
- The Cloudron archive. A drill in the container proves the database and the tool, and reads nothing the platform wrote. Restore that archive into a second Cloudron to prove it.
Run a drill after every schema-changing upgrade and at least once a quarter. Choose a more frequent schedule for valuable work or frequent upgrades. A drill needs room for copied uploads as well as the database. Read every check's detail, even when the overall result passes.
Upgrade #
Migrations run when the app starts. They run inside one transaction, so a migration that fails leaves the database at its old shape and the process exits. The database is never half migrated.
Take a backup before every upgrade. That backup is the only path back to the previous database.
Docker Compose #
-
Take a backup with the command above and copy it off the machine.
-
Read the release notes in
CHANGELOG.md. They record the changes a release adds and say whether a rollback needs a database restore. -
Change
FABLEWRIGHT_TAGin.env, or the default indocker-compose.yml. -
Pull and restart:
docker compose pull docker compose up -d -
Open the admin page and make sure that the version is the one you meant to install, and read the log for a migration failure.
Bare Node #
Build the selected release in a separate checkout first. Do not install dependencies or run a development build over the running service directory. Read the changelog and keep the previous release files until you accept the upgrade.
- Ask writers to finish saving.
- Stop the service, then take a final backup and copy it off the machine.
- Replace
build/,node_modules/,package.json,server.js,scripts/anddrizzle/in/opt/fablewrightwith the new release. - Start the service.
- Open the admin page and make sure that the version is the one you meant to install, and read the log for a migration failure.
Cloudron #
- Read the release notes.
- If the instance uses the community catalogue, use the update button on the app's dashboard. The catalogue URL is https://tangled.org/katsuricata.com/Fablewright/raw/main/CloudronVersions.json.
- For a source-built package, select the new source and run the update command below.
- Open the admin page and make sure that the version is the one you meant to install, and read the log for a migration failure.
From the package checkout:
cloudron update --build-arg APP_COMMIT=$(git rev-parse --short HEAD)
Cloudron takes a backup before update unless you explicitly disable it. Keep that backup enabled. A source-built custom package does not acquire new releases just because its repository changes. A catalogue install follows the catalogue URL and offers each published version.
When an upgrade fails #
A failed migration stops the start. The log says which migration failed and the database is unchanged. Read the message, then either fix the cause or restore the backup from step one.
A rollback needs a database from before the upgrade, because migrations only move forward. An older build refuses to start against a newer database, and prints:
fablewright: this build is older than the database it was given.
database /data/fablewright.db
this build 1.0.0 (1a2b3c4)
last opened by 1.0.1
newer migrations 20261101120000_some_later_change
Restore the database backup taken before the upgrade, then start the version
that took it. To start anyway, set FABLEWRIGHT_ALLOW_NEWER_SCHEMA=1.
To roll back:
- Stop the app.
- Restore the backup taken before the upgrade.
- Start the older version.
On Cloudron, the restore button does all three in one operation.
Some migrations only add a column. An older build reads such a database without a
problem, because it ignores the column. If the release notes say that every
migration in the release only adds a column, you can set
FABLEWRIGHT_ALLOW_NEWER_SCHEMA=1 and keep the newer database. The app prints a
warning at every start while the setting is on. Do not use it when a migration
changed data.
The migration contract #
These rules keep an upgrade readable. They apply to a change to the schema.
- A migration is a folder under
drizzle/.pnpm db:generatecreates one. - An applied migration is immutable. The app matches an applied migration by its
folder name, so editing an applied
migration.sqlchanges nothing on an existing database and changes what a new database receives. Add a new folder instead. drizzle/meta/_journal.jsonmust not exist. The migration reader throws when it finds one, so every startup fails.src/lib/server/db-state.spec.tschecks for it.- A release bumps the version in
package.json, andCloudronManifest.jsoncarries the same version. A test compares them.
Operators do not need pnpm or drizzle-kit to apply a released migration. Startup applies it. The development guide covers creating migrations, which is a contributor task.
Recovery history #
Every save can keep a version, and a project version holds a copy of the whole project. Left alone, that history makes the database grow with the writing and never stops. An instance therefore expires the versions the app took on its own, and keeps the versions a writer asked for.
| What a writer did | What the app holds | When it goes |
|---|---|---|
| Saved a scene version by hand | scene_snapshot with manual |
Never, unless an operator asks |
| Saved a project version by hand | project_checkpoint with manual |
Never, unless an operator asks |
| Saved a scene, restored one, hit a conflict, or edited through a guest link | an auto, pre_restore, or conflict scene version |
After the window, past the newest 20 per scene |
| Edited a note or a plot card | item_version |
After the window, past the newest 20 per note or card |
| Split or merged a scene | a structure scene version and project version |
After the window (newest 20 per scene / 5 per project) |
| Added or moved a book, part, chapter, or scene | a structure project version |
After the window, past the newest 5 per project |
A label never protects a version. The app writes labels itself, on a version kept before a restore and on the words a guest's save replaces, so the source of the version is what the policy reads.
One scene keeps at most 50 conflict versions while the app runs, and the oldest goes as a new one arrives. A guest link saves without a writer beside it, and the window is applied only at startup or from Instance, so the cap is what stops a burst of saves from growing the file in between.
The window is instance_setting.history_retention_days, which is 365 days on a
new instance. An admin changes it on Instance → Recovery history, where the
page also shows how much history the instance holds. A window of 0 keeps every
version.
The app applies the window at startup and when an admin saves a nonzero window on Instance. A failed startup sweep is logged and does not stop the app. Long-running instances can keep eligible history until the next startup or manual sweep. Hand-saved versions count toward the minimums too.
Prune by hand #
node scripts/ops.mjs prune-history
Without --apply, the command reports what is due and removes nothing. It reads
the window from the instance, unless --days N names another one. A run says how
many rows each table holds and how many are older than the window.
node scripts/ops.mjs prune-history --apply
--all includes the scene and project versions a writer saved by hand. Pass it
only when the disk is the problem: those versions have no other copy.
Give the space back #
Deleting rows frees pages inside the file, and later saves use those pages, so the database stops growing. The file itself stays the same size until SQLite rewrites it.
node scripts/ops.mjs prune-history --apply --vacuum
--vacuum rewrites the database after the delete and reports how much came back.
It reads and writes the whole file, so run it while the instance is quiet, and
take a backup first. A vacuum needs free space in the data directory: as much as
the database itself.
What expires first #
A long project holds the most history in the project versions taken before a structural change, because each one carries every scene. Those expire first. A scene's automatic version is small by comparison.
An export carries every version the instance still holds, so pruning before an export makes a smaller archive. Prune only after the backup you mean to keep: an expired version cannot be restored from anywhere else.
Uploads, imports and disk #
Note images are stored in uploads/ as <imageId>.webp. The instance keeps a
full-size <imageId>.orig when the setting preserves originals, or when the
writer asks for it on that upload. An admin turns on Keep full-size original
images on Instance. The writer can clear Keep the full-size original on
one image. Removing an image in the UI or replacing it leaves the files on disk,
because a project copy can share an image id.
The app also tries to keep each imported file in uploads/imports/ as
<sourceId>.<extension>. When storage succeeds, the project's import report
points at it and the writer can download it from the library. A kept file is as
big as what the writer imported, so a 90 MB Word document leaves another 90 MB
on disk. An import can succeed even if the source file or report cannot be saved.
Deleting a project moves it to the trash on the library page. Delete forever
removes the project's rows, membership and history. It does not unlink files, so
prune-uploads is the command that gives the space back. It removes image and
import files that no row names. That happens after a project is deleted forever,
or after an account deletion removes it.
Import limits #
The import file limit is 100 MiB (MAX_IMPORT_BYTES), shown as 100 MB in the UI.
The server request limit defaults to BODY_SIZE_LIMIT=101M, which leaves room
for multipart headers above a full-size file. server.js, Compose, systemd and
the Cloudron startup script use the same default. A zip can hold a
manuscript.json of up to 128 MiB after expansion.
That request limit is the adapter's ceiling, not an allowance for every route.
The entry point answers 413 for a smaller body first: 12 MiB for a route that
carries a document, and 2 MiB for anything else. Those two figures are fixed, so
raising BODY_SIZE_LIMIT gives an import more room and nothing else more.
One import or export runs at a time, because each holds the event loop for
seconds and hundreds of megabytes. A writer importing while another import runs
waits for their turn; four requests may wait and the next is answered with 503
and Retry-After. The wait is visible in the import panel as a message, so no
click disappears without a reason.
A reverse proxy can impose a lower limit. Increasing the request limit does not increase the app's file limit.
The import and export guide covers formats, conversion losses, and archives too large to reimport.
Prune orphaned files #
Run a dry run first. It reports total, referenced and unreferenced files and the reclaimable bytes.
node scripts/ops.mjs prune-uploads
Delete the unreferenced files with --apply:
node scripts/ops.mjs prune-uploads --apply
The command reads files directly in uploads/ and uploads/imports/. It does
not sweep arbitrary nested subdirectories. Do not use the uploads directory for
unrelated files.
The command leaves files younger than one hour for a later run. The app writes
images to disk before it records them in the database. The delay protects new
images and uploads that are still in progress. Change the delay with
--grace SECONDS. Use --grace 0 only while the app is stopped. It removes the
delay. The report counts the files left because they were new.
Drop preserved originals #
If you want to free disk space by dropping stored originals while keeping the display WebP copies, run a dry run:
node scripts/ops.mjs prune-uploads --originals
Pass --apply to delete each .orig file and then update its row (bytes = 0):
node scripts/ops.mjs prune-uploads --originals --apply
An original is dropped only when its display copy is on disk and is not empty. The app renames the display copy into place first, so when it is missing the original is the only copy of that image and the command keeps it. The report names how many it kept for that reason, and how many files it could not delete; a file it could not delete keeps its row, and the command exits with a non-zero code.
The full-size copy is what the writer asked for, so take a backup before dropping originals. They cannot be recreated from the display copy.
Accounts, mail and lockout #
An account on this instance has an email address and a password. The first account becomes the admin and closes sign-up. The admin can open sign-up again on Instance or create accounts by hand.
The instance name #
The admin changes the instance name on Instance → Name and sign-up. The wordmark, the tab title and the landing page use it. A fresh instance starts as Fablewright. The same page holds the sign-up switch, which is off until the admin turns it on.
Add an account #
On Instance → Accounts, fill in Name and Email under Add an account, and choose Create the account. Leave the password empty and the instance generates one. The page shows the password once, so copy it before you leave. The new account is a writer. Choose Make an admin on its row if it needs instance settings.
Mail is optional #
A reset link can arrive by email, or it can go to the server log. Both are supported, and the app tells the writer which one this instance uses.
For Compose, pass SMTP values through an override or environment entries.
Putting them in .env alone is not enough. The installation guide
shows the override. Restart the container or service after changing values.
On Cloudron the sendmail addon supplies the relay, and start.sh reads it. A
bare Docker install sends no mail until these variables are set:
| Variable | Purpose |
|---|---|
SMTP_HOST |
The SMTP server. Mail stays off when this is empty. |
SMTP_PORT |
Defaults to 587. Use 465 with SMTP_SECURE=true. |
SMTP_SECURE |
true when the port expects TLS from the first byte. |
SMTP_USER / SMTP_PASSWORD |
Login for a relay that needs one. |
MAIL_FROM |
The sender line. Mail stays off when this is empty. |
A relay that stops answering cannot block a reset: the send has a ten-second connect timeout, and a failure writes the link to the log instead.
Mail also needs an address the instance declared. A reset link must carry one,
because the request that asks for it names its own Host. Someone who knows an
account email can request a link using a host they control. A link to that host
exposes its token when the writer opens it. An instance with
SMTP_HOST and MAIL_FROM but neither ORIGIN nor INSTANCE_ORIGIN sends no
mail. It writes the link to the log and says so at boot. Set ORIGIN, or
INSTANCE_ORIGIN when the instance answers on several domains.
Sign-in and reset limits #
The sign-in, sign-up, forgot-password and reset-password forms are throttled. The counts live in the process, so a restart clears them. A second app process keeps separate counts.
| Action | Limit |
|---|---|
| Failed sign-in for one email | 5 in 5 minutes. A success clears the count. |
| Failed sign-in from an address | 50 in 15 minutes. |
| Sign-up from an address | 20 in 1 hour. |
| Reset request for a mailbox | 3 in 15 minutes. |
| Reset request from an address | 20 in 15 minutes. |
| Reset submission from an address | 20 in 15 minutes. |
server.js writes the client address into X-Forwarded-For before the app reads
it: from the socket on a direct install, or from the trusted proxy chain with
TRUST_PROXY=1. A proxy must pass the address in that header. Without
TRUST_PROXY=1, every writer behind the proxy looks like the proxy and shares
one bucket.
A password must be at least 10 characters. The sign-up form, the admin's set password form and the command line all use that minimum.
When a writer forgets a password #
- The writer opens
/forgot-passwordand enters their address. The page answers the same way whether or not the address has an account. - If the address has an account, the app tries to send a link by email when mail
and a declared address are available. Otherwise, or if sending fails, it writes
the link to the log as
[fablewright] password reset for <address>: <link>. With no declared address, the logged link is a path. Put the correct instance address in front before sending it. With a declared address, it is already an absolute URL. Treat either form as a credential. - The link opens
/reset-password. A new password ends every session on that account. The link works once and expires after an hour.
The admin can skip all three steps. Instance → Accounts sets a password for any account and ends its sessions, then shows the password once so the admin can pass it on. If the admin leaves the field empty, the instance generates one.
A password reset does not remove passkeys, because a passkey is a separate credential. If you suspect compromise, disable the account and set a new password. Re-enable it for the writer to review passkeys on Your account. Remove every unrecognized passkey. Until that review, those credentials remain usable. The list shows when each passkey was added.
When the admin is the one locked out #
The admin console needs a session, so it cannot help here. Use the command line. It works with the app stopped, and it needs no mailer and no browser:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs reset-password \
--email kat@example.com --generate \
--database /var/lib/fablewright/fablewright.db
From Docker Compose, use docker compose exec while the app runs, or docker compose run --rm fablewright while it is stopped:
docker compose run --rm fablewright node scripts/ops.mjs reset-password \
--email kat@example.com --generate
The command prints the new password once, ends every session for that account and
prints how many it ended. It writes the same password hash the sign-in form reads.
Pass --password instead of --generate to choose the password yourself. The
tool does not print that value, but shell history and process arguments can
expose it. Prefer --generate in a private terminal, then change the password
through Your account.
Sign in with the new password, then change it on the account page.
Disabling an account #
Instance → Accounts disables an account, which ends its sessions and refuses its next sign-in. The instance keeps at least one admin who can sign in: the last one cannot be disabled or demoted. Keep a second admin if the instance must never be locked out. To make one, open Instance → Accounts and choose Make an admin on another account.
To re-enable, use the same screen. The button says Enable.
Deleting an account #
A writer deletes their own account from Your account → Delete this account. Deletion is immediate and cannot be undone. It removes the account, its sessions, its passkeys, and every project only that account could open, with every word in them. Projects belonging to someone else stay. The departing account loses its access.
A project other people can open is not one writer's to destroy. Deletion stops until the writer names a co-author to take it on. That co-author becomes the owner, with the words as they stand. A project with readers but no co-author is blocked until the project is deleted or a co-author is added.
The Sharing page adds a co-author or a reader. The sharing guide describes it. A shared project is handed over by the rule above.
The only account on an instance cannot delete itself from the web. An instance with no accounts is claimable by anyone who opens it, so the page explains how to erase the instance instead. At a shell, the command line allows it:
sudo -u fablewright node /opt/fablewright/scripts/ops.mjs delete-account \
--email kat@example.com \
--database /var/lib/fablewright/fablewright.db
The command removes the account and the projects only it could open. It refuses a
project other people can open unless --delete-shared-projects says to remove
those too, which takes everyone's words with it.
The web also refuses deletion by the last admin who can sign in. Promote another account first. Secret links do not count as members for project handover. An owner's project with only guest links can be deleted with that account.
Account deletion does not erase earlier backups, downloaded archives, or copied
logs. Document your backup retention if writers need to know when those copies
expire. Run prune-uploads to reclaim unreferenced files after permanent deletion.
The admin console deliberately has no delete button. The admin can disable an account instead, which is reversible. Removing somebody's writing is not a moderation tool.
Monitoring and health #
/api/health is public and unauthenticated. It reads one row, so a 200 means
that the database opened and the schema exists. It answers with the version and
the commit, and never a word of anybody's writing.
curl -s http://127.0.0.1:3000/api/health
{ "ok": true, "version": "1.0.0", "commit": "1a2b3c4" }
The Docker image, Compose file and Cloudron manifest all point their health
check at it. A monitor can poll it, and a check that returns anything other than
200 is worth waking somebody for.
Read the logs at the same time:
- Docker Compose:
docker compose logs -f fablewright - systemd:
journalctl -u fablewright -f - Cloudron:
cloudron logs -f
Look for [fablewright] ... listening on ... to find the startup build and listen
address. Earlier lines can come from container startup or database migration.
The entry point reports a commit only if APP_COMMIT is available at runtime.
The admin page and health response use the embedded build identity.
The health check does not prove that saves, mail, image delivery, backups, or restores work. Test those separately after an upgrade. A reset link that could not be mailed appears in the same process log, so restrict log access.
Disk #
Four things grow with the writing: the database, its WAL journal, the uploads
directory and the backup directory. A Cloudron install also holds the
cloudron-backup snapshot, so plan for twice the database there.
du -sh /data/fablewright.db /data/fablewright.db-wal /data/uploads /data/backups
A full disk stops saves. Keep free space, copy backups off the machine, and run
prune-uploads after permanent deletions. prune-history slows the growth of
the database. --vacuum gives the space back, but it needs room for a second copy
of the database while it runs.
Moving an instance #
A move is a backup and a restore. The database, the signing secret and the uploads travel together, so a backup is the whole move.
- Install the same release on the new machine without exposing an unclaimed app.
- Ask writers to finish saving, then stop the old instance.
- Take a final backup and copy its directory to the new machine.
- Copy protected deployment values separately, including an environment-supplied signing secret.
- Verify and drill the copied backup before restoring it.
- Restore with the new machine's database path while its app is stopped.
- Configure the new host's address, proxy, mail, permissions, and backup schedule.
- Start the new instance and test sign-in, prose, images, history, and an export.
- Point the public address at the new machine and test it through the public proxy.
Keep the old instance stopped. Do not permit writes on both machines during a DNS change. The final backup excludes any words that never reached the old server, so resolve failed saves before the move.
Passkeys survive a server move when the public origin stays the same and the
account database moves with it. A change of domain requires replacement
passkeys. Password sign-in remains the fallback. Update ORIGIN or
INSTANCE_ORIGIN before sending reset links from a new address.
Browser drafts and device preferences do not travel in the server backup.
Unsaved browser drafts remain tied to the original address. Account preferences
travel with the database. Cloudron-to-Cloudron moves can use the platform's
restore or migration tools instead of a manual restore into /app/data.
Troubleshooting #
The troubleshooting guide groups failures by symptom. It covers startup, rejected forms, failed saves, mail, passkeys, imports, restores, and disk space. Writers must preserve unsaved words before following server troubleshooting steps.
Start with the log and /api/health. The version and commit answer the first
question of a bug report, and the log names the migration or the path that failed.
What this does not cover #
- Transfer to another machine or object store. The tool writes to a local path,
or a mounted destination named with
--out. It does not upload backups or manage credentials for remote storage. - Metrics and alerting.
/api/healthanswers with the version and the commit, and a monitor can poll it. There is no metrics endpoint and no audit log. - Point in time recovery. A backup is a copy at one moment, not a journal you replay.
- A storage quota per writer. Import accepts files up to 100 MB and keeps a copy
of each one, and each note image is capped at 10 MB. Nothing limits the total.
Watch free space and run
prune-uploadsafter permanent deletions. - A managed mail service. The app sends through the SMTP relay you configure, or writes the link to the log.
- Automatic upgrades. Every platform upgrade is an operator action, and a backup comes first.