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

Click Deploy on Railway — Documenso and PostgreSQL build automatically (the Next.js build takes a few minutes)
Confirm NEXT_PUBLIC_WEBAPP_URL and NEXTAUTH_URL are set to your Railway domain
Confirm the three 32-character secrets are set, and save them externally
Provide your base64-encoded .p12 certificate and its passphrase (see Signing Certificate below)
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:

Generate a self-signed certificate with OpenSSL, giving it a strong passphrase
Base64-encode it (base64 -w 0 cert.p12) and set NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS to the result
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

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.