---
title: "Deploy flatnotes"
description: "Markdown notes with password authentication and persistent file storage."
category: "Other"
url: https://railway.com/deploy/flatnotes
---

# Deploy flatnotes

Markdown notes with password authentication and persistent file storage.

**[Deploy flatnotes on Railway](https://railway.com/template/flatnotes)**

- **Creator:** Heron Technology
- **Category:** Other
- **Total deploys:** 1

## Template content

### flatnotes

- **Image:** dullage/flatnotes:v5.5.4@sha256:a509830073d6548d35450a98be3a432716430b674cc70ac93cbbaed1555b5a28
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# 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

* [flatnotes v5.5.4 source](https://github.com/dullage/flatnotes/tree/v5.5.4)
* [flatnotes environment-variable reference](https://github.com/dullage/flatnotes/wiki/Environment-Variables)
* [Railway volume documentation](https://docs.railway.com/reference/volumes)

### 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.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — [Jul'26] Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/flatnotes