Run Marfa on Railway or a server
Keep an instance running away from your own computer, on Railway, in a container you run, or under your own supervisor.
An instance is one server program, marfa-server, with one SQLite database and one folder of files. There's no database server to set up, and one database takes one server: keep a host at one replica, and turn off anything that stops an idle service, since the server runs its housekeeping and backups in the background.
| Where | How |
|---|---|
| A Mac or Linux machine of your own that stays on | Install on a Mac or Linux machine, with one command. |
| Railway, with an HTTPS address from the start | On Railway, from the Marfa template. |
| A container platform or a host you run yourself | In a container, with one volume. |
| Your own supervisor, without a container | Run it without a container. |
Choose a host says what a host needs.
On Railway
Railway runs the release image with a volume and gives it an HTTPS address.
Deploy the template
Open the Marfa template, choose a workspace and deploy. Check that the image is a version tag, such as ghcr.io/withmarfa/marfa-server:<version>, never latest. The template makes the two secrets for you.
Claim the instance
In the server's Deployments tab, open the deploy logs and find the line Claim this Marfa at https://<address>/setup with setup code: <code>. Open the address, enter the code and choose the owner's username and password. A restart before you claim prints a new code.
Copy the secrets
From the server's Variables tab, copy MARFA_KEY_SALT and MARFA_AUTH_SECRET to a password manager. They aren't in the volume, and a volume restored without its salt refuses every key.
To use your own domain, add it in Railway and set MARFA_CLAIM_ADDRESS to it, such as https://marfa.example.com, before you claim: a passkey belongs to the address it was made at. Give your instance an address covers a move after that.
Keep the template's other choices: one replica, Serverless off, image auto updates off, and the volume at /data with Railway's daily volume backups. The Railway guide in the marfa repository lists every setting the template makes, and how to restore a volume backup and remove the project.
In a container
Every release publishes ghcr.io/withmarfa/marfa-server:<version> for linux/amd64 and linux/arm64. It holds the release's marfa-server and marfa on a base with no shell, and runs as user 65532, not root. Start it from the version tag, so that a restart never changes the build under your database:
docker pull ghcr.io/withmarfa/marfa-server:0.0.87
docker run --name marfa -d --restart unless-stopped -p 127.0.0.1:8600:8600 \
-v marfa-data:/data --env-file marfa.env ghcr.io/withmarfa/marfa-server:0.0.87- Publish the port on
127.0.0.1, for a proxy or tunnel on the same machine. A bare-p 8600:8600opens it to every network the machine is on. To use another host port, change only the host side, such as-p 127.0.0.1:9000:8600: the image's health check asks port 8600 inside the container. - Mount one volume at
/data. A named volume works as it is. A host folder must belong to user 65532 with mode700, or run the container as the folder's owner withdocker run --user <uid>. marfa.envis optional. On a first start without secrets, the server makes them and keeps them in/data/marfa.secrets. To hold them yourself, putMARFA_KEY_SALTandMARFA_AUTH_SECRETin the file, with any other start-only setting. Either way, keep a copy outside the volume.
Then claim the instance through the CLI inside the container:
docker exec marfa marfa --socket /data/control/marfa.sock setup open --address https://marfa.example.com --no-browserOpen the link it prints within five minutes, and choose the owner's username and password. --address is the address people sign in at, which your proxy or tunnel serves.
Check the image
Each image has a build attestation for the version's index and for each platform's image. Check it with the GitHub CLI before you run it:
gh attestation verify oci://ghcr.io/withmarfa/marfa-server:<version> \
--repo withmarfa/marfa \
--signer-workflow withmarfa/marfa/.github/workflows/release.yml \
--source-ref refs/tags/v<version>The command checks the digest the tag points to. To run exactly what you checked, read the digest with docker buildx imagetools inspect, check oci://ghcr.io/withmarfa/marfa-server@<digest>, and start the container from that digest.
Run it without a container
Under a supervisor of your own, such as systemd on a server, install the two programs and run marfa server run, with the settings in its environment. It starts the marfa-server beside it, and stops it when the supervisor stops marfa server run. The server reads its environment, not a file, so have the supervisor load marfa.env.
MARFA_DATABASE_PATH=/srv/marfa/data/marfa.db
MARFA_BLOB_PATH=/srv/marfa/data/blobs
MARFA_LISTEN_HOST=127.0.0.1
MARFA_PORT=8600Without the two secrets, the first start makes them and keeps them in marfa.secrets beside the database. Claim the instance as the server's own account, with marfa --socket /srv/marfa/data/control/marfa.sock setup open --no-browser.
Keep it running
Point a monitor at GET /health, which needs no credential: it answers 503 when the database, a write, the disk or file storage is down, and its claimed says whether the instance has an owner yet. It stops within eight seconds of SIGTERM, so allow ten. Its exit status tells your supervisor what to do:
| Status | Meaning | Your supervisor |
|---|---|---|
0 | A clean stop. | Starts it again if you want it running. |
1 | A failed start, such as a port in use or a setting outside its rules. The log names the cause. | Starts it again once the cause is fixed. |
78 | The server won't open the database, such as one another release wrote, and changed nothing. | Doesn't start it again. See The server refuses its database. |
marfa server run handles status 78 itself, staying up and idle so a supervisor doesn't restart it.
The data directory
The database and the files are the whole of your data: keep them on local storage that survives a restart, such as a container volume. The directory holds:
marfa.secrets is there only when the server made the secrets. marfa.settings.key seals secret settings, such as the object store's secret key: keep it with the data, or each must be set again. To bring the instance back from a copy, see Restore a copy of the data directory.
The server keeps its data only where it can make it private. It refuses a folder that another account can write to or replace, and names the folder and the command that fixes it. It follows a symbolic link that you or root made in a path no other account can change, and refuses any other.
One server holds the database and the blob folder while it runs, so a second is refused: leave the .server-lock files in place. A blob folder on a network file system, whose locks may not hold, makes blob_storage degraded in Health.
The private socket
control/marfa.sock lets a command on the same machine, run as the server's own account, act with the machine's authority instead of a credential. Two tasks need it: claiming the instance and recovering the owner's password. Everything else works from any machine with a key or a sign-in.
The socket's folder must belong to the server's account, with mode 700 and no access control list that opens it to anyone else. MARFA_CONTROL_SOCKET moves the socket: an absolute path of 103 bytes or fewer.