Deploy Documenso

Deploy and Host Documenso on Railway

Documenso is an open-source document signing platform — the self-hosted alternative to DocuSign, Adobe Sign and PandaDoc. Upload a PDF, drop signature, name, date and text fields onto it, and email each recipient a tokenised link. Recipients sign in the browser without creating an account, and when the last one finishes Documenso seals the file with a genuine PAdES digital signature backed by an X.509 certificate you control.

Self-host Documenso on Railway with everything already wired together: the application container, PostgreSQL for documents and audit logs, Redis driving the BullMQ queue that sends mail and seals finished PDFs, an object storage bucket for every file, Mailpit providing SMTP and a browsable inbox, and Gotenberg converting .docx uploads to PDF. Deploy Documenso and the signing certificate is generated on first boot, your owner account is created from the email and password you supply, and registration is scoped to your own email domain.

Getting Started with Documenso on Railway

Set DOCUMENSO_ADMIN_EMAIL, DOCUMENSO_ADMIN_PASSWORD and DOCUMENSO_ADMIN_NAME before deploying. The password needs a special character, an uppercase letter and a number, or the account is rejected. Open the public URL when the deployment goes green and sign in: the account is already email-verified and holds the admin role, so there is no confirmation link to chase.

Click Upload Document and pick a PDF. In the editor add a recipient, switch to Add Fields, and drag a Signature field onto the page. Send Document emails every recipient a signing link. To watch that mail arrive, open the Mailpit service's URL and log in with the credentials in MP_UI_AUTH — every message the instance sends lands there.

Sign it yourself to confirm the chain works: open the link, add a signature, click the field to insert it, then choose Complete. The status turns to Completed within seconds and the download carries a real cryptographic signature. Administration lives at /admin, the queue dashboard at /api/jobs/board.

About Hosting Documenso

Documenso is a TypeScript application built on React Router and Prisma, released under AGPL-3.0. Teams self-host it when signed agreements are too sensitive to sit with a third party, and because per-seat signature pricing scales badly once a whole company sends contracts.

Key features:

• Drag-and-drop fields: signature, initials, name, date, text, number, checkbox, radio, dropdown
• Reusable templates and direct signing links for repeat paperwork
• Signing order, expiry dates and automatic reminders
• Full audit trail, plus a signing certificate attached to the completed file
• Teams and organisations with roles, plus Google, Microsoft and OIDC sign-in
• REST API and webhooks for wiring signature requests into your own product

The application container serves the web UI and API and, because the queue driver runs in-process, also consumes background jobs. PostgreSQL holds document metadata, recipients, fields, users and the audit log. Redis backs the BullMQ queue that delivers email, seals completed PDFs and sweeps for reminders and expiries. The bucket holds the PDF bytes. Mailpit gives the instance a working SMTP endpoint from the first minute and can relay to a real provider later, and Gotenberg runs LibreOffice headlessly so .docx uploads become PDFs before signing.

Why Deploy Documenso on Railway

Railway removes the assembly work around a multi-service signing stack.

• Postgres, Redis and object storage provisioned and wired by reference
• Private networking keeps the database, queue and converter off the internet
• TLS and a public domain issued automatically
• The signing certificate is generated at boot and kept on a volume
• Vertical scaling and metrics without touching a server

Common Use Cases

• Sending client contracts, statements of work and NDAs from an agency
• Collecting signed offer letters and policy acknowledgements in HR
• Embedding signature requests into your own SaaS via the REST API and webhooks
• Keeping regulated agreements inside infrastructure you control

Dependencies for Documenso

• Documenso — documenso/documenso:latest, built from gridalpha/documenso-railway, which adds the boot-time keystore and owner account
• PostgreSQL 18 — Railway managed; documents, recipients, users, audit log
• Redis — Railway managed; BullMQ queue, retries and cron schedules
• Object storage bucket — Railway managed; uploaded and sealed PDFs
• Mailpit — axllent/mailpit:latest; SMTP endpoint and browsable inbox
• Gotenberg — gotenberg/gotenberg:8-libreoffice; .docx to PDF conversion

Environment Variables Reference

Deployment Dependencies

• Source: github.com/documenso/documenso
• Image: hub.docker.com/r/documenso/documenso
• Docs: docs.documenso.com
• Runtime: Node.js 22, PostgreSQL 14+, Redis 6.2+

Hardware Requirements for Self-Hosting Documenso

Documents live in object storage, so the application volume only holds the signing keystore. Size PostgreSQL for the audit log, which grows with every view and signature event.

Self-Hosting Documenso with Docker

The image needs a PostgreSQL database and a signing keystore. Generate the keystore with OpenSSL and give it a password — one without a password fails to load:

openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -sha256 \
  -keyout key.pem -out cert.pem -subj "/CN=sign.example.com/O=Example Ltd"
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem \
  -passout pass:your-passphrase

Then run the container, mounting that file and adding your NEXT_PRIVATE_SMTP_* values:

docker run -d --name documenso -p 3000:3000 \
  -v "$(pwd)/cert.p12:/opt/documenso/cert.p12:ro" \
  -e NEXT_PUBLIC_WEBAPP_URL="https://sign.example.com" \
  -e NEXT_PRIVATE_DATABASE_URL="postgres://user:pass@host:5432/documenso" \
  -e NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://user:pass@host:5432/documenso" \
  -e NEXTAUTH_SECRET="$(openssl rand -hex 32)" \
  -e NEXT_PRIVATE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="$(openssl rand -hex 32)" \
  -e NEXT_PRIVATE_SIGNING_PASSPHRASE="your-passphrase" \
  documenso/documenso:latest

Migrations run at startup. On Railway this is all configured, keystore included.

Is Documenso Free to Self-Host?

Documenso is free and open source under AGPL-3.0: no seat limits, no per-signature fees, no feature paywall on the community edition. Documenso's own cloud starts around $30 per user per month, and an enterprise licence key unlocks a few extras but is not required. On Railway you pay only for the compute, storage and bandwidth the services use.

FAQ

What is Documenso? An open-source electronic signature platform: upload PDFs, place signature and form fields, send them for signing, and get back a file carrying a cryptographic signature and an audit trail.

What does this Railway template deploy? The Documenso application, PostgreSQL, Redis, an object storage bucket, a Mailpit mail service and a Gotenberg converter — all connected, with a public URL and TLS.

Why does Documenso need Redis and object storage? Redis runs the BullMQ queue that sends email, seals completed PDFs and drives reminders and expiries; the fallback in-database queue is not built for production load. Object storage keeps PDF bytes out of PostgreSQL so downloads stay fast as the archive grows.

How do I use my own signing certificate in self-hosted Documenso? Run base64 -i cert.p12 | tr -d '\n', set the result as NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS and NEXT_PRIVATE_SIGNING_PASSPHRASE to its password. Nothing is then generated.

How do I send real email instead of using the built-in inbox? Point NEXT_PRIVATE_SMTP_HOST, _PORT, _USERNAME and _PASSWORD at your provider, with NEXT_PRIVATE_SMTP_SECURE=true for port 465. Recipients never need an account, so registration can stay closed to everyone but your own domain.