Skip to main content

​
Deploy to Railway

Railway is a modern deployment platform that makes it easy to deploy Umami with PostgreSQL in minutes. No Docker knowledge required.

​
What is Railway?

Railway is a deployment platform that provisions infrastructure, automatically deploys your code, and handles scaling. Perfect for hosting Umami with minimal configuration.
Benefits:
  • One-click deployment
  • Automatic PostgreSQL provisioning
  • Free tier available (with limits)
  • Automatic HTTPS
  • Custom domains
  • Environment variable management
  • Automatic deploys from Git

​
Quick Deploy

The fastest way to deploy Umami to Railway:
1

Create Railway Account

Sign up at railway.app using:
  • GitHub account (recommended)
  • Email and password
Using GitHub allows automatic deployments when you push code changes.
2

Fork the Repository (Optional)

If you want to customize Umami or enable automatic deployments:
  1. Go to github.com/umami-software/umami
  2. Click Fork in the top right
  3. This creates a copy in your GitHub account
3

Deploy to Railway

Click the deploy button (if available in Umami’s README) or:
  1. Go to Railway dashboard
  2. Click New Project
  3. Select Deploy from GitHub repo
  4. Choose umami-software/umami or your fork
  5. Click Deploy Now
4

Add PostgreSQL Database

If not already added:
  1. In your project, click + New
  2. Select Database
  3. Choose PostgreSQL
  4. Railway automatically creates the database
Railway automatically sets the DATABASE_URL environment variable connecting your app to the database.
5

Configure Environment Variables

Add required environment variables:
  1. Click on your Umami service
  2. Go to Variables tab
  3. Add the following:
APP_SECRET=your-random-secret-here
Generate a random secret:
openssl rand -base64 32
The DATABASE_URL is automatically set by Railway. Don’t override it unless you’re using an external database.
6

Deploy

Railway automatically deploys when you:
  • Push changes to your GitHub repository
  • Add a service or database
  • Change environment variables
Watch the deployment logs in the Railway dashboard.
7

Get Your URL

Once deployed:
  1. Click on your Umami service
  2. Go to Settings tab
  3. Find Domains section
  4. Railway provides a free domain: your-app.up.railway.app
  5. Click Generate Domain if not already created
Access Umami at: https://your-app.up.railway.app
8

Login and Configure

Open your Umami URL and login:
  • Username: admin
  • Password: umami
Change the default password immediately in Settings → Profile!

​
Custom Domain Setup

Add your own domain to Railway:
1

Add Domain in Railway

  1. Go to your Umami service
  2. Click Settings tab
  3. Scroll to Domains
  4. Click + Custom Domain
  5. Enter your domain (e.g., analytics.yourdomain.com)
2

Configure DNS

Railway will show you DNS records to add:
Add a CNAME record in your domain registrar:
Type: CNAME
Name: analytics (or your subdomain)
Value: your-app.up.railway.app
TTL: 3600
3

Wait for DNS Propagation

DNS changes can take 5 minutes to 48 hours to propagate globally.Check status:
dig analytics.yourdomain.com
4

Verify SSL

Railway automatically provisions SSL certificates via Let’s Encrypt.Access your domain with HTTPS:
https://analytics.yourdomain.com

​
Environment Variables

Configurable options for Railway deployment: 
APP_SECRET=your-random-secret-string
  • APP_SECRET: Random string for encrypting sessions (required)
  • DATABASE_URL: Automatically set by Railway PostgreSQL
# Custom port (Railway sets this automatically)
PORT=3000

# Base path for serving Umami
BASE_PATH=/analytics

# Disable telemetry
NEXT_TELEMETRY_DISABLED=1

# Custom tracker script name
TRACKER_SCRIPT_NAME=custom-script.js

# Force SSL
FORCE_SSL=1

# CORS max age
CORS_MAX_AGE=86400
See the full list in Environment Variables.

​
Database Management

​
Access Railway PostgreSQL

Connect to your Railway PostgreSQL database:
Install Railway CLI:
npm install -g @railway/cli
Login and connect:
railway login
railway link
railway connect postgres

​
Backup Database

Railway doesn’t automatically backup your database. Set up regular backups!
# Using Railway CLI
railway run pg_dump -Fc > backup.dump

# Using connection URL
pg_dump -Fc postgresql://user:password@host:port/db > backup.dump
Restore from backup: 
pg_restore -d $DATABASE_URL backup.dump

​
Scaling and Resources

​
Monitor Usage

Railway provides resource monitoring:
  1. Go to your service
  2. Check Metrics tab for:
    • CPU usage
    • Memory usage
    • Network traffic
    • Deployment history

​
Upgrade Resources

Railway’s free tier includes:
  • 500 hours of usage per month
  • $5 credit
  • Shared CPU and memory
Upgrade to Pro for:
  • Unlimited usage
  • Better performance
  • More databases
  • Priority support
To upgrade:
  1. Click on your workspace name
  2. Go to Billing
  3. Choose a plan

​
Deployment Settings

​
Configure Build Settings

  1. Click on Umami service
  2. Go to Settings
  3. Adjust:
Railway auto-detects the build command from package.json:
pnpm run build-docker
This is configured in the Umami repository.
Railway runs:
pnpm start-docker
This starts Umami in production mode.
Railway monitors:
GET /api/heartbeat
Returns 200 OK when Umami is healthy.

​
Auto-Deploy from GitHub

Enable automatic deployments:
  1. Connect your GitHub account
  2. Fork the Umami repository
  3. Link it to Railway
  4. Railway deploys on every push to main branch
Create a railway.json in your repository to customize deployments.

​
Troubleshooting

Check deployment logs:
  1. Click on your service
  2. Go to Deployments tab
  3. Click on failed deployment
  4. View logs for errors
Common issues:
  • Missing APP_SECRET
  • Database connection failed
  • Build errors
  • Out of memory
Verify PostgreSQL is running:
  1. Click on PostgreSQL service
  2. Check status is “Active”
  3. Verify DATABASE_URL is set in Umami service
If using external database, check:
  • Firewall allows Railway IPs
  • Credentials are correct
  • Database is accessible
Check resource usage:
  1. View Metrics tab
  2. Look for CPU/memory spikes
  3. Upgrade plan if consistently high
Optimize:
  • Use ClickHouse for high-volume sites
  • Enable caching
  • Optimize database queries
Verify DNS configuration:
dig your-domain.com
Check:
  • DNS records point to Railway
  • SSL certificate provisioned (can take a few minutes)
  • No conflicting DNS records
  • Wait for DNS propagation (up to 48 hours)

​
Updating Umami

Update to the latest version:
If you connected via GitHub:
  1. Sync your fork with upstream: 
    git remote add upstream https://github.com/umami-software/umami.git
git fetch upstream
git merge upstream/main
git push
  2. Railway auto-deploys the update
Database migrations run automatically during deployment.

​
Cost Optimization

Tips to stay within Railway’s free tier:
  • Use the free 500 hours efficiently
  • Stop services when not needed
  • Delete unused databases
  • Monitor resource usage
  • Optimize database queries
Estimated costs:
  • Free tier: $0 (with limits)
  • Hobby: $5/month
  • Pro: $20/month (unlimited usage)

​
Next Steps

Add Your Website

Start tracking your first website

Custom Domain

Set up your own domain for Umami

Environment Variables

Configure advanced features

Database Backups

Set up automated backups

Build docs developers (and LLMs) love

Get started for freeTalk to us