Install Fablewright #
This guide takes a new instance from a checkout to its first account. For an existing instance, use the upgrade procedure. Back up before replacing a running release.
Choose one deployment:
| Deployment | Needs | Provides |
|---|---|---|
| Docker Compose | Docker Engine, Compose plugin, and Git | A packaged app and persistent data volume. You provide HTTPS and off-machine backups. |
| Bare Node | Node 24 or newer, pnpm 12.21.0, and Git | Direct control of the process and files. You provide a service manager, HTTPS, and backups. |
| Cloudron | Cloudron 10.0.0 or later and its CLI | HTTPS, app storage, a mail relay, and platform backup management. |
There is no hosted Fablewright service. Writers need an instance that they or someone they trust runs. The app uses its own accounts on all three deployments.
Before installation #
Choose a public address and a private location for persistent data. Run one Fablewright app process against the database. Do not put several replicas behind a load balancer.
The Cloudron manifest allows 1 GiB of memory, or 1,073,741,824 bytes. This is a package limit, not a measured minimum for every deployment. Large imports and images need more memory than ordinary drafting. This repository has no capacity benchmark that establishes a writer count or minimum disk size.
File limits below use MiB: one MiB is 1,048,576 bytes. The interface labels those limits as MB.
Allow disk space for the database, uploads, backups, and temporary copies during restore drills or database compaction. Imported source files remain on disk. The operations guide explains storage growth.
Keep the new instance private until you create its first account. The first person to sign up becomes the admin. No installation code or email verification protects that claim.
Get the source on the machine where you will build or run Compose:
git clone https://tangled.org/katsuricata.com/Fablewright
cd Fablewright
For a release installation, select the release tag you intend to run before building. The version in package.json identifies the source, and docker-compose.yml selects a container tag independently.
Docker Compose #
The supplied docker-compose.yml pulls katsuricata/fablewright:1.0.0 from Docker Hub. From the repository directory:
docker compose pull
docker compose up -d
docker compose ps
Open http://localhost:3000. The supplied port mapping listens on the host's interfaces, not just localhost. Restrict access with the host firewall until you claim the instance.
The named volume fablewright-data holds /data/fablewright.db, /data/auth-secret, and /data/uploads. Compose can prefix the actual volume name with its project name. Keep using the same Compose project when restarting or upgrading.
docker compose down keeps that volume. Do not add -v unless you intend to delete the manuscripts, accounts, and uploads.
Compose configuration #
Do not copy .env.example unchanged. That file is for development and points ORIGIN at port 5173. For a public deployment, create a Compose .env with your own address:
ORIGIN=https://fable.example.com
TRUST_PROXY=1
Use TRUST_PROXY=1 only when the app is reachable through a trusted proxy alone. The proxy must replace forwarding headers. For a direct local trial, omit both values.
Compose substitutes .env values only where its YAML asks for them. The supplied file forwards the origin and signing-secret values, but not SMTP values. To add mail, create compose.override.yaml:
services:
fablewright:
environment:
SMTP_HOST: ${SMTP_HOST:-}
SMTP_PORT: ${SMTP_PORT:-587}
SMTP_SECURE: ${SMTP_SECURE:-false}
SMTP_USER: ${SMTP_USER:-}
SMTP_PASSWORD: ${SMTP_PASSWORD:-}
MAIL_FROM: ${MAIL_FROM:-}
Put the corresponding mail values in .env. Do not commit that file or share rendered Compose configuration: it can contain passwords. Mail needs SMTP_HOST, MAIL_FROM, and either ORIGIN or INSTANCE_ORIGIN.
The supplied request limit is 101M. It sits one MiB above the 100 MiB import file limit, which leaves room for multipart headers. Leave it in place unless your proxy needs a different value.
That value is a ceiling for imports, not an allowance for every route. The entry point weighs each body against its own route's limit before anything reads it: 12 MiB for a route that carries a document, and 2 MiB for anything else. Those limits are fixed and need no setting. Raising BODY_SIZE_LIMIT does not raise them. Lowering it below 12 MiB makes a large save fail, and below 100 MiB an import fails.
Apply the configuration with the override explicitly:
docker compose -f docker-compose.yml -f compose.override.yaml up -d
Use the same -f arguments for later Compose commands that create containers. An explicit file list avoids differences in automatic override discovery.
The supplied file fixes the database path, the 101M request limit, and XFF_DEPTH=1. Change those entries in your deployment configuration if needed. Setting a different value in .env alone does not override a literal YAML value.
Build the Docker image yourself #
If you need an image from this checkout, build it with the local tag:
docker build --build-arg APP_COMMIT=$(git rev-parse --short HEAD) \
-t katsuricata/fablewright:local .
FABLEWRIGHT_TAG=local docker compose up -d --pull never
Keep FABLEWRIGHT_TAG=local in the deployment's .env for later commands. Add the override file arguments above if you use one. The Docker build supplies Node and pnpm. You do not need them on the host.
Docker behind a proxy #
For a proxy on the same host, replace the supplied port mapping with 127.0.0.1:3000:3000. For a containerized proxy, use a private Docker network and remove the public mapping. Do not leave a second public mapping through a merged override.
Forward the original Host and replace X-Forwarded-Proto and X-Forwarded-For. Serve the site over HTTPS. Allow request bodies above 100 MiB at both proxy and app if you need the largest supported import.
Set ORIGIN to the public HTTPS address. Set TRUST_PROXY=1 too if the app must use the forwarded client address for sign-in limits. With several domains, use INSTANCE_ORIGIN instead of ORIGIN. See the proxy rules.
Bare Node #
Use Node 24 or newer and pnpm 12.21.0, the version pinned by the Dockerfiles. With Node and npm installed, you can install pnpm with:
npm install --global pnpm@12.21.0
Install the full dependency set before building. Several build tools are development dependencies.
From the checkout:
mkdir -p .agents/skills
pnpm install --frozen-lockfile
cp .env.example .env
The skills directory is required by the dependency permissions in pnpm-workspace.yaml. Without it, a clean install can fail with ERR_PNPM_NO_AGENT_SKILLS_DIR.
Trial run #
Edit .env. Set ORIGIN=http://localhost:3000 for a local production trial. For a public install, use its HTTPS address instead. Set a persistent BETTER_AUTH_SECRET with at least 32 random characters.
This command generates a value for that secret:
node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))"
Keep the value private. Put it in BETTER_AUTH_SECRET in .env. Then build and start:
APP_COMMIT=$(git rev-parse --short HEAD) pnpm build
node --env-file=.env server.js
Open http://localhost:3000. The example database path, data/dev.db, is suitable for a trial. Use an absolute path outside the checkout for a permanent instance.
Run from the application directory. The migration folder is resolved from the working directory. Keep server.js as the entry point. Neither pnpm preview nor node build exercises the same startup path.
Permanent service with systemd #
The supplied unit expects /opt/fablewright, a system user named fablewright, and Node at /usr/bin/node. If Node is elsewhere, change ExecStart in both app and backup units. A shell version manager is not available inside the service.
On a Linux host, create the user and directories if they do not exist:
sudo useradd --system --user-group --home-dir /var/lib/fablewright \
--shell /usr/sbin/nologin fablewright
sudo install -d -m 0755 /opt/fablewright
sudo install -d -o fablewright -g fablewright -m 0750 /var/lib/fablewright
Build on the target host or a compatible system. node_modules can contain platform-specific packages. Copy the production files from the checkout:
sudo cp -a build node_modules package.json server.js scripts drizzle /opt/fablewright/
sudo cp deploy/fablewright.service /etc/systemd/system/
Do not copy the development .env or database into the service directory. The unit sets DATABASE_URL=file:/var/lib/fablewright/fablewright.db and listens on 127.0.0.1:3000.
Create a private environment file:
sudo install -d -m 0750 /etc/fablewright
sudo install -m 0600 /dev/null /etc/fablewright/environment
sudoedit /etc/fablewright/environment
Put your ORIGIN, BETTER_AUTH_SECRET, and optional mail values in that file, using NAME=value lines. Do not use export. Then create a drop-in:
sudo systemctl edit fablewright
Enter:
[Service]
EnvironmentFile=/etc/fablewright/environment
Start the service:
sudo systemctl daemon-reload
sudo systemctl enable --now fablewright
sudo systemctl status fablewright
Put an HTTPS reverse proxy in front of 127.0.0.1:3000. Use an SSH tunnel if you need to claim the instance before that proxy is ready. Read the proxy rules above before enabling forwarded headers.
The environment file is not part of an instance backup. Keep a protected copy of it with the deployment records. Restore needs the same signing secret if you want existing sessions to survive.
Install the backup timer after the app works. The backup unit does not automatically inherit the app's drop-in. Add the same EnvironmentFile to it if the tool needs those values.
Cloudron #
Install the Cloudron CLI on your workstation. Sign in to the server that will host the app:
cloudron login my.example.com
Install from the catalogue #
The public catalogue lists every published version. Install the latest one:
cloudron install --versions-url https://tangled.org/katsuricata.com/Fablewright/raw/main/CloudronVersions.json
You can also add that URL to the Cloudron dashboard under Community apps, then install Fablewright from the app grid.
The catalogue uses the image katsuricata/fablewright-cloudron from Docker Hub. Cloudron pulls the image before it starts the app. You do not need Docker on the workstation for this path.
Build from this checkout #
From the repository checkout:
cloudron install --build-arg APP_COMMIT=$(git rev-parse --short HEAD)
The CLI uploads the source and builds it on the server. The package consists of CloudronManifest.json, Dockerfile.cloudron, and the scripts in cloudron/. No local Docker installation is needed for this build path. A source build is separate from the catalogue, and Cloudron does not offer catalogue updates for it.
Cloudron provides the address and HTTPS. Its startup script sets the database path, signing secret, proxy trust, request limit, and SMTP values. It leaves ORIGIN unset and uses the primary Cloudron address as INSTANCE_ORIGIN. Do not try to configure those managed values through .env.
The app stores its data in /app/data. The backup hook writes a consistent database snapshot under /app/data/cloudron-backup. The platform backs up the rest of the directory too. Allow space for that second database copy.
Create the first Fablewright account after installation. Cloudron users do not automatically become Fablewright accounts. Aliases support password sign-in. Passkeys and reset links use the primary address.
For updates, read the upgrade guide first. Keep the platform backup enabled. A catalogue install updates from the dashboard. A source build needs cloudron update --build-arg APP_COMMIT=$(git rev-parse --short HEAD) from the selected checkout.
First account and acceptance test #
Create the first account while access is still restricted. Its library includes The Wonderful Wizard of Oz. Claiming the instance closes sign-up; open it again on Instance only if writers should register themselves. On Instance, set the instance name. Add another admin if someone else must be able to recover access.
Before inviting writers:
- Open
/api/healthand make sure that the version and commit match the release. - Create a disposable project and type a few words.
- Wait for the saved state, then reload and make sure that the words remain.
- Download a project archive and make sure that it contains
manuscript.json. - If you configured email, request a reset for your own account and test the link.
- Take a full backup and copy its directory off the machine.
- Run a restore drill with the same database path and signing-secret environment.
A reset link goes to the server log when mail is unavailable. Protect those logs. Do not test recovery by deleting the only admin or by restoring over a running instance.
Continue with the operations guide for scheduled backups and monitoring. Writers can use the writer's guide or /help.