JustAnalytics/Documentation

Railway Deployment

Deploy JustAnalytics on Railway with one-click template setup

Railway Deployment

Deploy your own JustAnalytics instance on Railway. The template provisions a PostgreSQL database and configures all necessary environment variables.

Time to data: 5 minutes

One-Click Deploy#

Deploy on Railway

This creates:

  • A web service running the JustAnalytics Next.js application
  • A PostgreSQL database for analytics data storage
  • Pre-configured environment variables with generated secrets

Manual Setup#

If you prefer to set up manually:

Create a Railway project

  1. Go to railway.app and create a new project
  2. Add a PostgreSQL plugin to your project
  3. Copy the DATABASE_URL from the plugin's variables

Deploy from GitHub

  1. Click New Service > GitHub Repo
  2. Select your JustAnalytics fork/repo
  3. Railway will auto-detect the Node.js runtime

Configure environment variables

Set the following variables in your Railway service:

| Variable | Required | Description | |----------|----------|-------------| | DATABASE_URL | Yes | Auto-populated from PostgreSQL plugin | | NEXTAUTH_URL | Yes | Your Railway public URL (e.g., https://your-app.up.railway.app) | | NEXTAUTH_SECRET | Yes | Generate with openssl rand -base64 32 | | GOOGLE_CLIENT_ID | No | Google OAuth credentials | | GOOGLE_CLIENT_SECRET | No | Google OAuth credentials | | RESEND_API_KEY | No | For email notifications | | CRON_SECRET | No | For cron job authentication | | STRIPE_SECRET_KEY | No | For billing (if self-hosting with billing) |

Configure build & deploy

Railway should auto-detect these, but verify:

  • Build command: npm ci && npx prisma generate && npm run build
  • Start command: npx prisma db push --skip-generate && npm start
  • Health check path: /api/health

Set up custom domain (optional)

  1. In Railway, go to Settings > Networking > Custom Domain
  2. Add your domain (e.g., analytics.yourdomain.com)
  3. Configure DNS with the provided CNAME record
  4. Update NEXTAUTH_URL to match your custom domain

Cost Estimate#

Railway's Starter plan includes $5/month of free usage, which covers:

  • ~500 hours of compute (enough for 24/7 with a small instance)
  • 1 GB PostgreSQL storage
  • Suitable for sites with up to ~100k pageviews/month

For higher traffic, upgrade to the Pro plan ($20/month) for more resources.

Scaling#

Database#

For sites with 1M+ events/month, consider:

  • Enabling the data aggregation cron job (hourly rollups)
  • Setting up data retention policies via the dashboard
  • Upgrading to a larger PostgreSQL instance

Compute#

Railway supports horizontal scaling. Increase replicas in railway.json:

{
  "deploy": {
    "numReplicas": 2
  }
}

Cron Jobs#

JustAnalytics uses cron jobs for:

  • Hourly aggregation — rolls up raw events into hourly/daily stats
  • Uptime checks — pings monitored endpoints
  • Alert evaluation — checks alert rule conditions

On Railway, set up a cron service or use an external cron provider (e.g., cron-job.org) to call:

POST https://your-app.up.railway.app/api/cron/aggregate
Authorization: Bearer YOUR_CRON_SECRET

Troubleshooting#

Build fails with Prisma errors#

Ensure prisma generate runs before next build:

npm ci && npx prisma generate && npm run build

Database connection issues#

  1. Verify DATABASE_URL is set and contains valid credentials
  2. Check Railway PostgreSQL plugin is running
  3. Try restarting the service

CORS errors on tracking script#

Ensure NEXTAUTH_URL matches your actual deployment URL exactly (including https://).