Deploy to Render

Deploy Documenso on Render with managed PostgreSQL

Render provides a straightforward platform for deploying Documenso with automatic builds, managed databases, and free SSL certificates. This guide covers deployment using Render’s Blueprint system.

Quick Deploy

The fastest way to deploy Documenso on Render:

Click the button above to start deployment. Render will:

• Create a new web service
• Provision a PostgreSQL database
• Build and deploy the application
• Generate secure values for secrets

Manual Deployment

For more control over your deployment:

Step 1: Create Render Account

1. Sign up

   Create an account at Render using GitHub, GitLab, or Google.

2. Connect GitHub

   Link your GitHub account to enable deployments from repositories.

Step 2: Fork or Clone Repository

Fork the Documenso repository to your GitHub account, or use the official repository directly.

Step 3: Create PostgreSQL Database

1. Create database

   In Render dashboard:

   • Click “New +” → “PostgreSQL”
   • Choose a name: documenso-db
   • Select region closest to your users
   • Choose plan (Free tier available)
2. Wait for provisioning

   Render will provision the database and generate connection credentials.

3. Note connection details

   Save the Internal Database URL for later use.

Step 4: Create Web Service

1. Create new web service

   • Click “New +” → “Web Service”
   • Connect your GitHub repository
   • Select documenso/documenso (or your fork)
2. Configure build settings

   Render should auto-detect the render.yaml configuration:

   • Name: documenso-app
   • Environment: Node
   • Build Command: npm i && npm run build
   • Start Command: npx prisma migrate deploy --schema packages/prisma/schema.prisma && npx turbo run start --filter=@documenso/remix
   • Plan: Choose your plan (Free tier available)

Step 5: Configure Environment Variables

Add these environment variables in the Render dashboard:

Auto-Generated Variables

Render can auto-generate these:

NEXTAUTH_SECRET · string

Click “Generate” in Render to create a secure random value.

NEXT_PRIVATE_ENCRYPTION_KEY · string

Click “Generate” in Render to create a secure random value.

NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY · string

Click “Generate” in Render to create a secure random value.

Application URLs

NEXT_PUBLIC_WEBAPP_URL · string · required

Render provides this automatically. Use the Render external URL:

https://documenso-app.onrender.com

Or your custom domain if configured.

NEXT_PRIVATE_INTERNAL_WEBAPP_URL · string

Set to http://localhost:10000 for Render deployments.

Database Configuration

Connect to your PostgreSQL database:

NEXT_PRIVATE_DATABASE_URL · string · required

Use the Internal Database URL from your PostgreSQL service:

postgres://user:password@host/database

NEXT_PRIVATE_DIRECT_DATABASE_URL · string · required

Same as NEXT_PRIVATE_DATABASE_URL for Render deployments.

You can reference the database URL using Render’s syntax: ${documenso-db.DATABASE_URL}

SMTP Configuration

SMTP must be configured for Documenso to send emails. Render 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.

NEXT_PRIVATE_SMTP_PORT · number · required

SMTP port (typically 587).

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.

Signing Certificate

Option 1: Base64-Encoded Certificate (Recommended)

The recommended approach for Render deployments:

1. Generate certificate locally

   # Generate certificate and private key
   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 to base64

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

   NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS="<paste-base64-content>"
   NEXT_PRIVATE_SIGNING_PASSPHRASE="your-cert-password"
   
4. Clean up local files

   rm private.key certificate.crt cert.p12 cert.p12.base64
   

   Keep a secure backup of the certificate!

Option 2: Using Render Disks

For persistent file storage:

1. Create a disk

   In your web service settings:

   • Scroll to “Disks”
   • Click “Add Disk”
   • Name: documenso-certs
   • Mount Path: /opt/documenso
   • Size: 1GB
2. Upload certificate

   Use Render Shell to upload the certificate:

   # Access shell from Render dashboard
   # 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 6: Deploy

1. Save environment variables

   Click “Save Changes” in the Render dashboard.

2. Trigger deployment

   Render will automatically build and deploy your application.

3. Monitor build logs

   Watch the build logs to ensure successful deployment.

4. Access your instance

   Once deployed, access Documenso at your Render URL (e.g., https://documenso-app.onrender.com).

The first build may take 5-10 minutes as Render installs dependencies and builds the application.

Configuration Options

Custom Domain

To use a custom domain with your Render deployment:

1. Add custom domain

   In web service settings:

   • Scroll to “Custom Domains”
   • Click “Add Custom Domain”
   • Enter your domain (e.g., documenso.example.com)
2. Configure DNS

   Add the CNAME record to your DNS provider:

   CNAME documenso -> your-app.onrender.com
   
3. Update environment variable

   NEXT_PUBLIC_WEBAPP_URL="https://documenso.example.com"
   
4. Wait for SSL provisioning

   Render automatically provisions SSL certificates via Let’s Encrypt.

Storage Options

By default, documents are stored in PostgreSQL. For production, use 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"

Health Check Path

Render uses health checks to verify your application is running:

Health Check Path: /api/health

This is configured in render.yaml and automatically monitored by Render.

Auto-Deploy on Push

Render automatically deploys when you push to your connected branch (usually main):

git push origin main

SMTP Provider Recommendations

Render doesn’t provide SMTP services. Here are some recommended providers:

SendGrid (Free tier available)

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]"

Free tier: 100 emails/day

Mailgun

NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="smtp.mailgun.org"
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME="your-mailgun-username"
NEXT_PRIVATE_SMTP_PASSWORD="your-mailgun-password"
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

Access real-time logs from the Render dashboard:

1. Navigate to your web service
2. Click the “Logs” tab
3. View streaming logs or search historical logs

Database Access

Connect to your PostgreSQL database:

Render Shell

1. Go to your PostgreSQL service
2. Click “Connect”
3. Use the provided connection string

External Client

Use the External Database URL with your preferred client (TablePlus, pgAdmin, etc.)

Manual Deploy

Trigger a manual deployment:

1. Navigate to your web service
2. Click “Manual Deploy” → “Deploy latest commit”

Restart Service

1. Navigate to your web service
2. Click “Manual Deploy” → “Clear build cache & deploy”

Scale Service

Upgrade your plan for more resources:

1. Service Settings → “Instance Type”
2. Choose a larger plan
3. Save changes

Troubleshooting

Build Failures

If your build fails:

1. Check build logs

   Review error messages in the “Events” tab.

2. Verify Node.js version

   Ensure NODE_VERSION=22 in environment variables (or higher).

3. Check build command

   Verify build command matches:

   npm i && npm run build
   
4. Clear build cache

   Click “Manual Deploy” → “Clear build cache & deploy”

Application Crashes

If the application starts but crashes:

1. Check logs

   Look for error messages in the Logs tab.

2. Verify database connection

   Ensure NEXT_PRIVATE_DATABASE_URL is correctly set.

3. Check certificate status

   Visit https://your-app.onrender.com/api/certificate-status

4. Verify migrations ran

   Check logs for “Running database migrations” message.

Database Connection Issues

1. Verify database is running

   Check PostgreSQL service status in Render dashboard.

2. Check connection string

   Ensure you’re using the Internal Database URL, not External.

3. Test connection

   Use Render Shell to test database connectivity:

   psql $DATABASE_URL -c "SELECT 1;"
   

SSL/HTTPS Issues

1. Verify custom domain

   Ensure DNS is properly configured and propagated.

2. Check SSL certificate

   Render auto-provisions SSL certificates. Check status in Custom Domains section.

3. Force HTTPS

   Render automatically redirects HTTP to HTTPS.

Email Not Sending

1. Verify SMTP configuration

   Double-check all SMTP environment variables.

2. Test SMTP externally

   Verify your SMTP credentials work outside Render.

3. Check logs

   Look for SMTP-related errors in application logs.

4. Verify sender address

   Ensure NEXT_PRIVATE_SMTP_FROM_ADDRESS matches your SMTP provider’s verified domain.

Costs and Limits

Render Pricing

Free Tier

• Web Service: Free (with limitations)
  • Spins down after 15 minutes of inactivity
  • Limited to 750 hours/month
• PostgreSQL: Free
  • 90 days data retention
  • Expires after 90 days

Paid Plans

• Starter: $7/month per service
  • No spin down
  • Always available
• PostgreSQL: $7/month
  • 1GB storage included
  • Unlimited retention

Free tier databases expire after 90 days. Upgrade to a paid plan for production use.

Database Storage

• Free: 1GB included
• Additional storage: Billed based on plan

Use S3 for document storage to minimize database size and costs.

Performance Optimization

Database Connection Pooling

For high-traffic deployments:

1. Upgrade to a higher database plan
2. Configure connection pooling in your environment variables
3. Consider using PgBouncer for connection management

Instance Scaling

Scale your web service:

1. Service Settings → Instance Type
2. Choose a plan with more CPU/RAM
3. Enable auto-scaling (on higher plans)

Caching

Improve performance with Redis:

1. Add Redis service in Render
2. Configure Redis URL in environment variables
3. Use for session storage and caching

Backup and Recovery

Automatic Backups

Render provides automatic daily backups for paid PostgreSQL plans:

• Access: PostgreSQL service → Backups tab
• Retention: Based on your plan
• Restore: Click “Restore” on desired backup

Manual Backups

Create manual database backups:

# Using Render Shell
pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql

Certificate Backup

Always maintain a secure backup of your signing certificate outside Render.

Store securely:

• Original cert.p12 file
• Certificate password
• Base64-encoded contents

Advanced Configuration

OAuth Providers

Enable social authentication:

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"

Disable Public Signup

For private deployments:

NEXT_PUBLIC_DISABLE_SIGNUP="true"

Enable Billing Features

If using Stripe:

NEXT_PRIVATE_STRIPE_API_KEY="your-stripe-key"
NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET="your-webhook-secret"
NEXT_PUBLIC_FEATURE_BILLING_ENABLED="true"

Next Steps

Custom Domain Setup

Configure a custom domain on Render

Environment Variables

Complete environment variable reference

Email Configuration

Configure email providers

Monitoring

Set up monitoring and alerts