Deploy to Railway

One-click deployment of Documenso on Railway

Railway provides a simple platform for deploying Documenso with automatic provisioning of PostgreSQL and other services. This guide walks through deployment using Railway’s template system.

Quick Deploy

The fastest way to deploy Documenso on Railway:

Click the button above to start the deployment process. Railway will automatically:

• Create a new project
• Provision a PostgreSQL database
• Build and deploy the Documenso application
• Generate secure random values for secrets

Manual Deployment

If you prefer to set up Railway manually or need more control:

Step 1: Create Railway Account

1. Sign up

   Create an account at Railway using GitHub authentication.

2. Install Railway CLI (Optional)

   npm install -g @railway/cli
   railway login
   

Step 2: Create New Project

1. Create project

   In the Railway dashboard, click “New Project” and select “Deploy from GitHub repo”.

2. Connect repository

   Connect your GitHub account and select the documenso/documenso repository (or your fork).

3. Configure build

   Railway will automatically detect the railway.toml configuration and use Docker for building.

Step 3: Add PostgreSQL Database

1. Add database service

   Click “New” → “Database” → “Add PostgreSQL”.

2. Wait for provisioning

   Railway will provision a PostgreSQL database and generate connection credentials.

Step 4: Configure Environment Variables

Add these required environment variables in Railway’s dashboard:

Core Configuration

NEXTAUTH_SECRET · string · required

Generate with: openssl rand -hex 32

NEXT_PRIVATE_ENCRYPTION_KEY · string · required

Generate with: openssl rand -hex 32

NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY · string · required

Generate with: openssl rand -hex 32

NEXT_PUBLIC_WEBAPP_URL · string · required

Railway will provide this as ${{RAILWAY_PUBLIC_DOMAIN}} or use your custom domain.

NEXT_PRIVATE_INTERNAL_WEBAPP_URL · string

Set to http://localhost:3000 for Railway deployments.

Database (Auto-configured)

Railway automatically injects these from the PostgreSQL service:

NEXT_PRIVATE_DATABASE_URL=${{Postgres.DATABASE_URL}}
NEXT_PRIVATE_DIRECT_DATABASE_URL=${{Postgres.DATABASE_URL}}

SMTP Configuration

You must configure SMTP for Documenso to send emails. Railway does not provide SMTP services.

NEXT_PRIVATE_SMTP_TRANSPORT · string · required

Set to smtp-auth or your preferred transport.

NEXT_PRIVATE_SMTP_HOST · string · required

Your SMTP server hostname (e.g., smtp.sendgrid.net).

NEXT_PRIVATE_SMTP_PORT · number · required

SMTP port (typically 587 for TLS).

NEXT_PRIVATE_SMTP_USERNAME · string · required

SMTP authentication username.

NEXT_PRIVATE_SMTP_PASSWORD · string · required

SMTP authentication password.

NEXT_PRIVATE_SMTP_FROM_NAME · string · required

Sender name (e.g., “Documenso”).

NEXT_PRIVATE_SMTP_FROM_ADDRESS · string · required

Sender email address (e.g., “[e-mail]”).

Signing Certificate

Option 1: Base64-encoded Certificate (Recommended)

The easiest way to provide a signing certificate on Railway is to use base64-encoded contents:

1. Generate certificate locally

   # Generate certificate
   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
     -keyout private.key \
     -out certificate.crt \
     -subj "/C=US/ST=State/L=City/O=Organization/CN=yourdomain.com"
   
   # Create PKCS12 file
   openssl pkcs12 -export -out cert.p12 \
     -inkey private.key \
     -in certificate.crt \
     -passout pass:your-cert-password
   
2. Encode certificate to base64

   base64 -i cert.p12 | tr -d '\n' > cert.p12.base64
   cat cert.p12.base64
   
3. Add to Railway environment variables

   NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS="<paste base64 content here>"
   NEXT_PRIVATE_SIGNING_PASSPHRASE="your-cert-password"
   

Option 2: Using Railway Volumes

For persistent file storage:

1. Create volume

   In Railway dashboard: Service → Settings → Volumes → Add Volume

   Mount path: /opt/documenso

2. Upload certificate

   Use Railway CLI to upload the certificate:

   railway run bash
   # Inside the container:
   # Upload cert.p12 to /opt/documenso/
   
3. Configure environment

   NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH="/opt/documenso/cert.p12"
   NEXT_PRIVATE_SIGNING_PASSPHRASE="your-cert-password"
   

Step 5: Deploy

Once all environment variables are configured:

1. Trigger deployment

   Railway will automatically build and deploy when you push to your connected GitHub repository.

2. Monitor build

   Watch the build logs in the Railway dashboard to ensure successful deployment.

3. Access your instance

   Once deployed, access Documenso at your Railway-provided URL (e.g., https://your-app.railway.app).

Configuration Options

Custom Domain

To use a custom domain:

1. Add domain in Railway

   Service → Settings → Domains → Add Custom Domain

2. Configure DNS

   Add the CNAME record to your DNS provider as shown in Railway.

3. Update environment variables

   NEXT_PUBLIC_WEBAPP_URL="https://documenso.yourdomain.com"
   

Storage Options

By default, Documenso stores documents in the PostgreSQL database. For production, consider using S3:

NEXT_PUBLIC_UPLOAD_TRANSPORT="s3"
NEXT_PRIVATE_UPLOAD_REGION="us-east-1"
NEXT_PRIVATE_UPLOAD_BUCKET="your-bucket-name"
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID="your-access-key"
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY="your-secret-key"

OAuth Providers

Enable Google or Microsoft sign-in:

Google OAuth

NEXT_PRIVATE_GOOGLE_CLIENT_ID="your-client-id"
NEXT_PRIVATE_GOOGLE_CLIENT_SECRET="your-client-secret"

Microsoft OAuth

NEXT_PRIVATE_MICROSOFT_CLIENT_ID="your-client-id"
NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET="your-client-secret"

SMTP Provider Setup

Railway doesn’t include SMTP services. Here are some recommended providers:

SendGrid

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.sendgrid.net"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME="apikey"
NEXT_PRIVATE_SMTP_PASSWORD="your-sendgrid-api-key"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Postmark

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-api"
NEXT_PRIVATE_SMTP_HOST="smtp.postmarkapp.com"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_APIKEY_USER="your-server-token"
NEXT_PRIVATE_SMTP_APIKEY="your-server-token"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Resend

NEXT_PRIVATE_SMTP_TRANSPORT="resend"
NEXT_PRIVATE_RESEND_API_KEY="your-resend-api-key"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

Managing Your Deployment

View Logs

View application logs in real-time:

Railway Dashboard

# Click on your service → "Logs" tab

Database Access

Connect to your PostgreSQL database:

railway connect Postgres

Or use the connection string from environment variables to connect with your preferred database client.

Restart Service

railway restart

Update Deployment

Railway automatically deploys when you push to your connected branch:

git pull origin main
# Make changes
git add .
git commit -m "Update configuration"
git push origin main

Troubleshooting

Build Failures

If the build fails:

1. Check build logs

   Review the build logs in Railway dashboard for error messages.

2. Verify railway.toml

   Ensure railway.toml points to the correct Dockerfile:

   [build]
   builder = "DOCKERFILE"
   dockerfilePath = "/docker/Dockerfile"
   
3. Check environment variables

   Verify all required environment variables are set correctly.

Application Not Starting

If the application builds but doesn’t start:

1. Check application logs

   Look for error messages in the logs tab.

2. Verify database connection

   Ensure NEXT_PRIVATE_DATABASE_URL is correctly set to the Postgres service.

3. Check certificate configuration

   Visit https://your-app.railway.app/api/certificate-status to check certificate status.

Database Connection Issues

If you see database connection errors:

1. Verify database is running

   Check that the PostgreSQL service is active in Railway dashboard.

2. Check environment variable references

   Ensure you’re using ${{Postgres.DATABASE_URL}} syntax for Railway’s service references.

3. Test connection manually

   railway connect Postgres
   \conninfo
   

Email Not Sending

1. Verify SMTP credentials

   Double-check all SMTP environment variables are set correctly.

2. Test SMTP connection

   Use an SMTP testing tool to verify your credentials work outside Railway.

3. Check application logs

   Look for SMTP-related errors in the logs.

Costs and Limits

Railway Pricing

Railway uses a usage-based pricing model:

• Developer Plan: $5/month base + usage
• Pro Plan: $20/month base + usage
• Includes 500 execution hours and 100GB egress per month

Monitor your usage in the Railway dashboard to avoid unexpected charges.

Database Storage

PostgreSQL storage on Railway:

• Included: 1GB
• Additional storage billed at $0.25/GB/month

Consider using S3 for document storage to minimize database size.

Performance Optimization

Scaling

Railway automatically scales based on demand, but you can optimize:

1. Enable vertical scaling

   Service → Settings → Resources → Adjust memory/CPU limits

2. Use S3 for storage

   Move document storage to S3 to reduce database load.

3. Add caching

   Consider adding Redis for session storage and caching.

Database Optimization

# Enable connection pooling if using an external pooler
NEXT_PRIVATE_DATABASE_URL="postgresql://user:pass@pooler:6432/documenso"
NEXT_PRIVATE_DIRECT_DATABASE_URL="${{Postgres.DATABASE_URL}}"

Backup and Recovery

Database Backups

Railway provides automatic daily backups for PostgreSQL:

• Access backups: Database service → Backups tab
• Restore from backup: Click “Restore” on desired backup

Manual Backup

# Using Railway CLI
railway connect Postgres
pg_dump documenso > backup.sql

Certificate Backup

Store your signing certificate securely outside Railway. It’s critical for signature validation.

Keep a secure backup of:

• The original cert.p12 file
• The certificate password
• The base64-encoded contents (if using that method)

Next Steps

Custom Domain

Set up a custom domain for your Railway deployment

Environment Variables

Learn about all configuration options

Monitoring

Set up monitoring and alerting

OAuth Setup

Configure Google or Microsoft sign-in