Deploy and Host flatnotes on Railway

flatnotes is a lightweight, self-hosted note-taking web app that stores every note as an ordinary Markdown file. It offers a distraction-free editor, full-text search, tags, wikilinks, responsive mobile access, and raw or WYSIWYG editing without requiring a database or proprietary storage format.

About Hosting flatnotes

This community template deploys flatnotes v5.5.4 from the official digest-pinned container image. Railway exposes only the web app on port 8080, checks /health, and mounts one persistent volume at /data for notes, attachments, and the search index. Password authentication is enabled with the default username admin; Railway generates a fresh login password and a separate JWT signing key for every deployment. The upstream entrypoint initializes volume ownership and runs the service as UID/GID 1000. No database, worker, migration, external API key, or public demo is required. This template is not affiliated with or endorsed by the flatnotes project.

Common Use Cases

Keep personal notes and journals as portable Markdown files.
Build a searchable, tagged knowledge base with wikilinks.
Edit notes from desktop or mobile while retaining control of the files.

Dependencies for flatnotes Hosting

Official dullage/flatnotes:v5.5.4 image pinned by immutable digest.
One Railway persistent volume mounted at /data.

Deployment Dependencies

Implementation Details

The template enables FLATNOTES_AUTH_TYPE=password, sets FLATNOTES_USERNAME=admin, and independently generates FLATNOTES_PASSWORD and FLATNOTES_SECRET_KEY. The first is the deployer's login credential; the second signs access tokens and should not be reused as a password. FLATNOTES_PORT=8080 aligns the image listener, Railway routing, and the upstream health check.

The complete /data directory is persistent. It holds Markdown notes, attachments, and the .flatnotes search index, which flatnotes can rebuild from the Markdown files. Railway permits one volume per service and does not replicate a volume-backed service, so this template intentionally uses one service and one replica.

There are no database migrations or worker processes. Before upgrading, back up /data, review the new release, pin its immutable image digest, and validate login, note create/read, and restart persistence in an isolated project. Roll back to the previous image digest and its matching volume backup if the new release changes on-disk behavior. Changing FLATNOTES_SECRET_KEY signs users out but does not change stored notes.

Why Deploy flatnotes on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying flatnotes on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.