---
title: "Deploy Documenso — Open Source DocuSign Alternative"
description: "Self-hosted document signing with Postgres — no per-envelope fees"
category: "Other"
url: https://railway.com/deploy/documenso-esign-postgres
---

# Deploy Documenso — Open Source DocuSign Alternative

Self-hosted document signing with Postgres — no per-envelope fees

**[Deploy Documenso — Open Source DocuSign Alternative on Railway](https://railway.com/template/documenso-esign-postgres)**

- **Creator:** SilverBanana
- **Category:** Other

## Template content

### Documenso https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/documenso.svg

- **Image:** documenso/documenso:v2.9.0
- **Public domain:** Yes

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# Deploy and Host Documenso on Railway

Documenso is the leading open-source document signing platform — a self-hosted alternative to DocuSign and PandaDoc. Upload a PDF, place signature and field boxes, send it for signing, and get a legally sound audit trail, all on infrastructure you own. No per-envelope pricing, no seat limits. This template deploys Documenso with a managed PostgreSQL database and the signing certificate handled the Railway way.

---

## What This Template Deploys

| Service | Purpose |
| --- | --- |
| **Documenso** | The Next.js signing app, document editor, and API on port `3000` |
| **PostgreSQL** | Documents, users, recipients, fields, and the signing audit trail |

Both services run on Railway's private network with credentials injected automatically. Prisma runs the database migrations on first boot, and the signing certificate is supplied through an environment variable rather than a mounted file.

---

## About Hosting Documenso

Documenso digitally signs PDFs, and digital signing requires a certificate — a `.p12` file that cryptographically seals each document. On a normal server you mount that file into the container. **Railway can't mount a file from a host**, which is exactly where most Documenso-on-Railway attempts stall.

The correct approach, and the one this template uses, is `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` — the certificate base64-encoded and passed as an environment variable. Documenso's own documentation names this as the method for Railway and Vercel. Two rules that trip people up:

- **The certificate must have a passphrase.** A password-less `.p12` throws `Failed to get private key bags` and signing fails outright. Set `NEXT_PRIVATE_SIGNING_PASSPHRASE`.
- **Never generate the certificate inside the container.** If the container is rebuilt, an internally generated cert is lost and signatures become inconsistent. Always provide it externally.

Three secrets must be generated once and kept stable, each at least 32 characters: `NEXTAUTH_SECRET` (sessions), plus `NEXT_PRIVATE_ENCRYPTION_KEY` and `NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY` (which encrypt stored data). Documenso also needs both `NEXT_PRIVATE_DATABASE_URL` and `NEXT_PRIVATE_DIRECT_DATABASE_URL`; without a pooler, both use the same Railway Postgres string.

Typical cost: **~$5–15/month** on Railway for a small instance with Postgres. DocuSign bills per envelope and per seat; self-hosted Documenso has neither.

---

## How It Compares

| | Documenso (self-hosted) | DocuSign | PandaDoc | Documenso Cloud |
| --- | --- | --- | --- | --- |
| Cost model | Flat ~$5–15/mo infra | Per seat + envelope caps | Per user/month | Per-plan monthly |
| Document limit | Unlimited | Envelope quotas | Per plan | Plan-based |
| Data ownership | Full | Vendor | Vendor | Documenso-hosted |
| Audit trail | Yes | Yes | Yes | Yes |
| Open source | Yes (AGPLv3) | No | No | Yes |
| Self-hostable | Yes | No | No | No |

DocuSign carries the widest legal recognition and the biggest integration catalogue. Documenso wins on unlimited documents at a flat cost, open-source auditability, and keeping signed contracts on infrastructure you control.

---

## Deploy in Under 5 Minutes

1. Click **Deploy on Railway** — Documenso and PostgreSQL build automatically (the Next.js build takes a few minutes)
2. Confirm `NEXT_PUBLIC_WEBAPP_URL` and `NEXTAUTH_URL` are set to your Railway domain
3. Confirm the three 32-character secrets are set, and save them externally
4. Provide your base64-encoded `.p12` certificate and its passphrase (see Signing Certificate below)
5. Open your Railway domain, complete the setup wizard, upload a PDF, and send it for signing

Configure the `NEXT_PRIVATE_SMTP_*` variables so signing invitations and completion emails send.

---

## Common Use Cases

- **DocuSign replacement** — send contracts and agreements for signature with unlimited documents and no per-envelope fees
- **Client contract signing** — branded signing pages on your own domain for agencies, freelancers, and consultants
- **HR and onboarding** — offer letters, NDAs, and policy acknowledgements with a complete audit trail
- **Compliance-sensitive signing** — keep signed documents and signer data out of a third-party vendor's cloud

---

## Signing Certificate

Digital signing requires a password-protected `.p12` certificate, provided as base64 rather than a mounted file:

1. Generate a self-signed certificate with OpenSSL, giving it a strong passphrase
2. Base64-encode it (`base64 -w 0 cert.p12`) and set `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` to the result
3. Set `NEXT_PRIVATE_SIGNING_PASSPHRASE` to the passphrase

A self-signed certificate produces cryptographically valid, legally usable signatures in most jurisdictions. Adobe Approved Trust List recognition requires a CA-issued certificate or HSM.

---

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `NEXT_PUBLIC_WEBAPP_URL` | Required | Your Railway domain — used for links and signing URLs |
| `NEXTAUTH_URL` | Required | Same as your public URL — authentication callbacks |
| `NEXTAUTH_SECRET` | Required | Session signing key, 32+ chars — `openssl rand -base64 32` |
| `NEXT_PRIVATE_ENCRYPTION_KEY` / `_SECONDARY_KEY` | Required | Two encryption keys, 32+ chars each — keep both stable |
| `NEXT_PRIVATE_DATABASE_URL` | Auto-injected | PostgreSQL connection via Railway reference variable |
| `NEXT_PRIVATE_DIRECT_DATABASE_URL` | Auto-injected | Direct connection for migrations — same string without a pooler |
| `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` | Required | Base64-encoded `.p12` signing certificate |
| `NEXT_PRIVATE_SIGNING_PASSPHRASE` | Required | Certificate passphrase — the cert must have one |
| `NEXT_PRIVATE_SMTP_HOST` | Required | SMTP host for signing emails |
| `NEXT_PRIVATE_SMTP_PORT` | Required | SMTP port, e.g. `587` |
| `NEXT_PRIVATE_SMTP_USERNAME` / `_PASSWORD` | Required | SMTP credentials |
| `NEXT_PRIVATE_SMTP_FROM_ADDRESS` | Required | Sender address for emails |

> **The signing certificate must have a passphrase.** A password-less `.p12` causes a `Failed to get private key bags` error and signing won't work. Always set `NEXT_PRIVATE_SIGNING_PASSPHRASE`.

> **Keep the three secret keys stable.** `NEXTAUTH_SECRET` and both encryption keys must not change after first run, or sessions and encrypted data break. Generate once, back up externally.

---

## Dependencies for Documenso Hosting

- Railway account — Hobby plan (~$5–15/month) covers both services
- A password-protected `.p12` signing certificate (self-signed is fine for most use)
- An SMTP provider for signing invitations and completion notifications
- Optional: a CA-issued certificate or HSM for Adobe Trust List recognition

### Deployment Dependencies

- [Documenso GitHub Repository](https://github.com/documenso/documenso)
- [Documenso Self-Hosting Documentation](https://docs.documenso.com/docs/self-hosting/deployment/docker)
- [Documenso Railway Guide](https://docs.documenso.com/docs/self-hosting/deployment/railway)
- [Railway Variables Documentation](https://docs.railway.com/guides/variables)

### Implementation Details

The template runs the official `documenso/documenso` image on port `3000` against a managed Railway PostgreSQL service, using Documenso's `NEXT_PRIVATE_` prefix convention. Both `NEXT_PRIVATE_DATABASE_URL` and `NEXT_PRIVATE_DIRECT_DATABASE_URL` point at Postgres; Prisma uses the direct connection to run migrations, which execute automatically on startup.

The signing certificate is supplied through `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` as base64 rather than a mounted file, because Railway does not mount host files into containers. It must be generated externally and carry a passphrase — a certificate created inside the container is lost on rebuild, and a password-less one fails to load.

All data, including the signing audit trail, lives in PostgreSQL — the legal record of each agreement. Back it up before major upgrades with Railway's backup feature or `pg_dump`, and pin the image to a version tag rather than `latest`.

---

## Frequently Asked Questions

**Why is the certificate passed as base64 instead of a file?** Railway does not mount host files into containers, so Documenso's file-mount method doesn't apply. Its documented alternative for Railway is `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` with the certificate base64-encoded.

**I get "Failed to get private key bags" — why?** The `.p12` certificate has no passphrase. Documenso requires a password-protected certificate. Regenerate it with a passphrase and set `NEXT_PRIVATE_SIGNING_PASSPHRASE`.

**Is a self-signed certificate legally valid?** For most jurisdictions and purposes, yes — the signature is cryptographically sound and the audit trail is complete. Adobe Approved Trust List recognition specifically requires a CA-issued certificate or an HSM.

**Do my signed documents survive a redeploy?** Yes. Documents, recipients, and the audit trail live in PostgreSQL, which persists across redeploys. Back it up before major upgrades.

**Is the self-hosted version free?** Yes. Documenso is AGPLv3 with no license fees, per-document pricing, or seat limits. Enterprise features like SSO and 21 CFR Part 11 compliance require a license.

---

## Why Deploy Documenso on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Documenso on Railway you get open-source document signing with the certificate pitfall already solved — Documenso and PostgreSQL pre-wired over a private network, the `.p12` supplied the Railway way, encryption keys generated, automatic HTTPS, and migrations run for you. Unlimited documents, no per-envelope billing, and your signed contracts on infrastructure you own.

## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — [Jul'26] Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/documenso-esign-postgres