# Install Fablewright This guide takes a new instance from a checkout to its first account. For an existing instance, use [the upgrade procedure](operations.md#upgrade). 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](operations.md#uploads-imports-and-disk) 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: ```sh 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](https://hub.docker.com/r/katsuricata/fablewright). From the repository directory: ```sh docker compose pull docker compose up -d docker compose ps ``` Open . 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: ```dotenv 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`: ```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: ```sh 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: ```sh 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](operations.md#behind-a-reverse-proxy). ## 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: ```sh npm install --global pnpm@12.21.0 ``` Install the full dependency set before building. Several build tools are development dependencies. From the checkout: ```sh 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: ```sh 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: ```sh APP_COMMIT=$(git rev-parse --short HEAD) pnpm build node --env-file=.env server.js ``` Open . 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: ```sh 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: ```sh 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: ```sh 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: ```sh sudo systemctl edit fablewright ``` Enter: ```ini [Service] EnvironmentFile=/etc/fablewright/environment ``` Start the service: ```sh 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](operations.md#run-the-backup-on-a-schedule) 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: ```sh cloudron login my.example.com ``` ### Install from the catalogue The public catalogue lists every published version. Install the latest one: ```sh 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: ```sh 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](operations.md#cloudron-1) 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: 1. Open `/api/health` and make sure that the version and commit match the release. 2. Create a disposable project and type a few words. 3. Wait for the saved state, then reload and make sure that the words remain. 4. Download a project archive and make sure that it contains `manuscript.json`. 5. If you configured email, request a reset for your own account and test the link. 6. Take a full backup and copy its directory off the machine. 7. 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](operations.md) for scheduled backups and monitoring. Writers can use [the writer's guide](using-fablewright.md) or `/help`.