Memos — Railway Deployment Template

> Open-source, self-hosted note-taking tool built for quick capture.
> Markdown-native, lightweight (~20MB Docker image), and fully yours.
> 61,000+ GitHub stars · MIT licensed · Single Go binary

Features

• Instant Capture — Timeline-first UI. Open, write, done. No folders to navigate.
• Total Data Ownership — Self-hosted on your infrastructure. Notes stored in Markdown, always portable. Zero telemetry.
• Radical Simplicity — Single Go binary, ~20MB Docker image, <128MB RAM. Runs comfortably on Railway's free tier.
• PostgreSQL Database — Railway-native PostgreSQL for production-grade persistence (replaces default SQLite).
• Open & Extensible — MIT-licensed with full REST and gRPC APIs for integration.

Screenshots

Timeline View	Compose Editor	Explore Feed

All screenshots captured from a live Railway deployment at memos-production-2206.up.railway.app.

Why Memos on Railway?

Prerequisites

• A Railway account
• A GitHub account (to fork and deploy)

One-Click Deploy

Click the button above and Railway will:

1. Clone this template repository
2. Provision a PostgreSQL database
3. Build and deploy the Memos container
4. Expose it on a *.railway.app domain

Or deploy manually:

1. Click New Project → Deploy from GitHub repo
2. Fork this repository to your GitHub account
3. Connect your fork to Railway
4. Add a PostgreSQL plugin (Railway injects DATABASE_URL)
5. Set the environment variables (see table below)
6. Deploy!

Environment Variables

Memos is configured entirely through environment variables. The template handles DATABASE_URL mapping to MEMOS_DSN automatically.

> * MEMOS_DSN is optional when using Railway's PostgreSQL addon.
> The entrypoint automatically reads DATABASE_URL from Railway if MEMOS_DSN is unset.
> For SQLite (no database addon), leave MEMOS_DSN empty.

Example Configuration

MEMOS_PORT=5230
TZ=America/New_York
MEMOS_LOG_LEVEL=info

Service Dependencies

• PostgreSQL: Managed by Railway's addon system. Data persists across deploys.
• Persistent Volume: At /var/opt/memos — stores SQLite metadata (when used) and uploaded assets.
• No Redis or external services needed — Memos is self-contained.

Local Development

Prerequisites

• Docker installed on your machine

Running with Docker

# Pull the latest stable image
docker pull neosmemo/memos:stable

# Run with SQLite (standalone)
docker run -d \
  --name memos \
  -p 5230:5230 \
  -v ~/.memos:/var/opt/memos \
  neosmemo/memos:stable

Open http://localhost:5230 — you'll be prompted to create an admin account.

Running with Docker Compose (PostgreSQL)

# docker-compose.yml
services:
  memos:
    image: neosmemo/memos:stable
    ports:
      - "5230:5230"
    volumes:
      - memos-data:/var/opt/memos
    environment:
      - MEMOS_DSN=postgres://memos:***@postgres:5432/memos?sslmode=disable
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: memos
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: memos
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memos"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  memos-data:
  pgdata:

docker compose up -d

Building from Source

git clone https://github.com/usememos/memos.git
cd memos

# Build frontend
cd web && pnpm install && pnpm release && cd ..

# Build backend
go build -trimpath -tags netgo,osusergo -o memos ./cmd/memos

# Run
./memos

Troubleshooting

"Connection refused" after deploy

1. Wait 30–60 seconds for the health check to pass.
2. Ensure the PostgreSQL addon is provisioned and DATABASE_URL is injected.
3. Check Railway logs: railway logs.

Database connection failures

FATA[0000] failed to connect to database: dial tcp ...

• Verify DATABASE_URL is set in Railway dashboard → Variables.
• If using custom MEMOS_DSN, ensure the connection string is correct.
• For Railway PostgreSQL, the sslmode=require parameter is required.

Data doesn't persist after restart

• Memos stores data at /var/opt/memos. Railway volumes must be mounted here.
• If using SQLite, the database file is stored at the volume path.
• If using PostgreSQL, only uploaded assets are on the volume.

Memory or performance issues

• Memos uses <128MB RAM under normal load.
• If using PostgreSQL, ensure your Railway plan has adequate connections.
• Check MEMOS_LOG_LEVEL=debug for verbose diagnostics.

Admin account lockout

If you lose access to the admin account:

# Connect to the Railway volume and reset directly
# This is a Railway shell session:
railway run
rm -f /var/opt/memos/memos.db

Then restart — Memos will prompt for a new admin account on next launch.

Resource Requirements

Updating

The stable tag follows Memos releases. To update:

1. In Railway dashboard, navigate to your Memos service.
2. Go to Settings → Deploy.
3. Click Redeploy — Railway pulls the latest neosmemo/memos:stable image.

For pinning a specific version, update Dockerfile:

FROM neosmemo/memos:v0.29.1

Security

• Container runs as non-root user (UID 10001:GID 10001)
• Base image receives Alpine Linux security updates
• Data volume is isolated from the container's ephemeral filesystem
• All secrets (DSN, passwords) are injected via environment variables — never hardcoded
• HTTPS is provided automatically by Railway's edge infrastructure

License

This template is MIT-licensed.
The upstream Memos project is also MIT-licensed.

Support & Community

• Memos Documentation
• Memos GitHub Issues
• Memos Discord
• Railway Documentation

Deploy and Host

Deploy this template on Railway with one click. Railway provides compute, TLS at the edge, and a public URL. The service restarts automatically on failures.

About Hosting

This template runs as a single container with no external database dependencies. All data is stored using built-in storage — no PostgreSQL, Redis, or additional services required.

Why Deploy

• One-click deploy — No configuration, no setup, just deploy
• Zero external dependencies — Single container, no external database needed
• Automatic HTTPS — Railway provisions TLS certificates automatically
• Self-healing — Automatic restarts on failure
• Persistent storage — Optional Railway volume for data persistence

Common Use Cases

• Self-hosted service for personal or team use
• Production deployment with zero maintenance overhead
• Privacy-focused alternative to cloud-hosted solutions
• Lightweight deployment on Railway's free tier

Dependencies for

Deployment Dependencies

Memos uses SQLite by default. An optional PostgreSQL database can be configured via the MEMOS_DSN or DATABASE_URL environment variable.

• Railway Account — hosting platform
• No external database, cache, or message queue required