Railway

Deploy Documenso on Railway with automatic builds from Git, managed PostgreSQL, and built-in networking. Use the one-click template or manual setup.

This guide is a community contribution and may be outdated. If you run into issues, check the GitHub Discussions for help.

Prerequisites

Before deploying, you need:

A Railway account (free tier available)
SMTP credentials for sending emails (required for document signing requests)
A custom domain (optional but recommended for production)

One-Click Deploy

The fastest way to deploy Documenso on Railway is using the official template:

This template automatically provisions:

Documenso application service
PostgreSQL database
Required environment variables with secure defaults

Click the deploy button

Click the "Deploy on Railway" button above. You'll be redirected to Railway and prompted to log in if needed.

Configure environment variables

Railway will prompt you to configure required variables. At minimum, set:

Variable	Description
`NEXT_PUBLIC_WEBAPP_URL`	The public URL for your deployment (use the Railway-provided URL initially, update later if using a custom domain)
`NEXT_PRIVATE_SMTP_HOST`	Your SMTP server hostname
`NEXT_PRIVATE_SMTP_PORT`	SMTP port (typically 587 or 465)
`NEXT_PRIVATE_SMTP_USERNAME`	SMTP username
`NEXT_PRIVATE_SMTP_PASSWORD`	SMTP password
`NEXT_PRIVATE_SMTP_FROM_ADDRESS`	Sender email address
`NEXT_PRIVATE_SMTP_FROM_NAME`	Sender display name

The template automatically generates secure values for NEXTAUTH_SECRET, NEXT_PRIVATE_ENCRYPTION_KEY, and NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY.

Deploy

Click "Deploy" to start the deployment. Railway builds the application from the Dockerfile and provisions the database.

This takes approximately 5-10 minutes for the initial build.

Access your deployment

Once deployed, Railway provides a URL like documenso-production.up.railway.app.

Click the URL in the Railway dashboard to access your Documenso instance.

Manual Deployment

If you prefer more control over the setup, deploy Documenso manually:

Create a new project

Log in to Railway
Click "New Project"
Select "Deploy from GitHub repo"
Connect your GitHub account if not already connected
Fork or select the Documenso repository

Configure the build

Railway automatically detects the railway.toml configuration file in the repository, which specifies:

[build]
builder = "DOCKERFILE"
dockerfilePath = "/docker/Dockerfile"

No additional build configuration is needed.

Add PostgreSQL database

In your project, click "New"
Select "Database"
Choose "PostgreSQL"
Railway provisions the database and automatically sets DATABASE_URL

Configure environment variables

Click on the Documenso service and go to the "Variables" tab. Add the following variables:

Required variables:

NEXTAUTH_SECRET=<generate with: openssl rand -base64 32>
NEXT_PRIVATE_ENCRYPTION_KEY=<minimum 32 character random string>
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=<minimum 32 character random string>
NEXT_PUBLIC_WEBAPP_URL=https://<your-railway-url>.up.railway.app
NEXT_PRIVATE_DATABASE_URL=${{Postgres.DATABASE_URL}}
NEXT_PRIVATE_DIRECT_DATABASE_URL=${{Postgres.DATABASE_URL}}
NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
NEXT_PRIVATE_SMTP_HOST=<your-smtp-host>
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=<your-smtp-username>
NEXT_PRIVATE_SMTP_PASSWORD=<your-smtp-password>
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso
NEXT_PRIVATE_SMTP_FROM_ADDRESS=noreply@yourdomain.com

Use ${{Postgres.DATABASE_URL}} to reference the Railway-managed PostgreSQL connection string. Railway automatically resolves this reference.

Optional variables:

Variable	Description	Default
`PORT`	Application port	`3000`
`NEXT_PUBLIC_DISABLE_SIGNUP`	Disable public signups	`false`
`NEXT_PRIVATE_SIGNING_PASSPHRASE`	Passphrase for signing certificate	-
`DOCUMENSO_DISABLE_TELEMETRY`	Disable anonymous telemetry	`false`

Deploy

Click "Deploy" or push a commit to trigger a new deployment. Railway builds and deploys the application automatically.

Environment Variables

Railway manages environment variables through its dashboard. The full list of configuration options is documented in Environment Variables.

Referencing Railway Services

Railway allows referencing other services in your project using the ${{ServiceName.VARIABLE}} syntax:

NEXT_PRIVATE_DATABASE_URL=${{Postgres.DATABASE_URL}}

This ensures connection strings stay in sync when Railway updates service configurations.

Database Setup

Railway's managed PostgreSQL handles database provisioning automatically. The database:

Runs PostgreSQL 15 by default
Includes automatic backups on paid plans
Provides connection pooling via the internal network

Database Connection

For Railway deployments, use the same connection string for both pooled and direct connections:

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

Documenso runs database migrations automatically on startup.

Accessing the Database

To connect directly to your database for debugging or maintenance:

Open the PostgreSQL service

In your Railway project dashboard, select the PostgreSQL service.

Open the Connect tab

The "Connect" tab shows the connection string and credentials.

Connect with your client

Use the provided connection string with your preferred PostgreSQL client.

Custom Domain

Railway provides a generated URL by default. To use your own domain:

Generate a domain

Click on your Documenso service
Go to "Settings" > "Networking"
Click "Generate Domain" to get a Railway subdomain, or proceed to add a custom domain

Add custom domain

In "Settings" > "Networking", click "Custom Domain"
Enter your domain (e.g., sign.yourdomain.com)
Railway provides DNS records to configure

Configure DNS

Add the following DNS records at your domain registrar:

Type	Name	Value
CNAME	sign	`<your-project>.up.railway.app`

DNS propagation can take up to 24 hours.

Update environment variable

Update NEXT_PUBLIC_WEBAPP_URL to match your custom domain:

NEXT_PUBLIC_WEBAPP_URL=https://sign.yourdomain.com

Railway automatically provisions and renews SSL certificates for custom domains.

Scaling Options

Railway provides several options for scaling your Documenso deployment:

Vertical Scaling

Increase resources for your service:

Open your Documenso service

In the Railway dashboard, select the Documenso service.

Open Settings

In "Settings" you can change the resource limits for the service.

Adjust memory and CPU

Raise the memory and CPU limits; Railway will scale within these limits based on demand.

Horizontal Scaling

Railway supports horizontal scaling through replicas:

Open service Settings

In the Railway dashboard, select your Documenso service and open "Settings".

Enable Horizontal Scaling

Turn on "Horizontal Scaling" so Railway can run multiple instances.

Set replicas

Choose how many replicas to run; Railway will load-balance traffic across them.

Documenso stores sessions in the database, so horizontal scaling works without additional configuration. However, ensure your database can handle the increased connection load.

Database Scaling

For high-traffic deployments:

Upgrade to a larger PostgreSQL instance in Railway
Consider using connection pooling with PgBouncer
Configure read replicas for read-heavy workloads

Cost Estimate

Railway uses usage-based pricing. Estimated monthly costs for Documenso:

Tier	Resources	Estimated Cost
Trial	$5 credit, limited hours	Free
Hobby	512MB RAM, shared CPU	$5-10/month
Pro	2GB RAM, dedicated CPU	$20-40/month
Team	Custom resources, priority support	$50+/month

Actual costs depend on:

Application memory usage (typically 500MB-1GB)
Database size and query volume
Egress bandwidth
Number of deployments

Railway charges based on actual resource consumption. Monitor usage in the Railway dashboard to optimize costs.

Free Tier Limitations

Railway's trial tier includes:

$5 of free credit
500 hours of execution time per month
Limited to 512MB RAM per service

This is sufficient for testing but not recommended for production.

base64 -i your-cert.p12 | tr -d '\n'

Add environment variables in Railway

In your Documenso service variables, set:

NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS=<base64-encoded-certificate>
NEXT_PRIVATE_SIGNING_PASSPHRASE=<certificate-password>

Your certificate must have a password. Certificates without passwords cause signing errors.

See Signing Certificate Configuration for detailed instructions.

Build fails

Application crashes on startup

Emails not sending

Database connection errors

Slow performance

On this page