---
title: Tips & Common Pitfalls
description: Practical advice for running Documenso in production.
---
import { Callout } from 'fumadocs-ui/components/callout';
## Always Configure a Signing Certificate
This is the single most common issue when self-hosting Documenso. Without a signing certificate,
the application starts normally but document signing fails.
Documenso does **not** bundle a [signing certificate](/docs/self-hosting/configuration/signing-certificate) in the Docker image. You must provide one yourself using one of two methods:
### Volume Mount (Recommended)
Mount your `.p12` certificate file into the container at the default path:
```bash
docker run -d \
-v /path/to/your/cert.p12:/opt/documenso/cert.p12:ro \
-e NEXT_PRIVATE_SIGNING_PASSPHRASE="your-certificate-password" \
documenso/documenso:latest
```
The default certificate path inside the container is `/opt/documenso/cert.p12`. You can change this with `NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH`.
### Base64 Environment Variable
For platforms that don't support volume mounts (Railway, Render, etc.), encode the certificate and pass it as an environment variable:
```bash
# Encode the certificate (no line breaks)
base64 -w 0 certificate.p12 # Linux
base64 -i certificate.p12 # macOS
```
Then set:
```bash
NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS=
NEXT_PRIVATE_SIGNING_PASSPHRASE=your-certificate-password
```
`NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` takes precedence over
`NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH` if both are set.
### Verify Your Certificate
After starting Documenso, check the certificate status endpoint:
```bash
curl http://localhost:3000/api/certificate-status
```
The startup script also checks for the certificate and prints a warning if it's missing.
---
## Certificate Password is Required
Certificates without a password cause signing to fail with:
```
Error: Failed to get private key bags
```
Always set a password when creating your `.p12` certificate. When using OpenSSL, set the password during the export step and provide it to Documenso via `NEXT_PRIVATE_SIGNING_PASSPHRASE`.
---
## Use the Health Check Endpoints
Documenso exposes two endpoints for monitoring:
| Endpoint | Purpose |
| ------------------------- | ------------------------------------ |
| `/api/health` | Returns 200 if the application is up |
| `/api/certificate-status` | Detailed signing certificate status |
Use `/api/health` for container orchestration health checks (Docker, Kubernetes). Use `/api/certificate-status` to debug signing issues. It reports whether a certificate is configured, its type, and any errors.
---
## Pin Your Docker Image Version
Use a specific version tag in production:
```bash
# Good — predictable, reproducible
docker pull documenso/documenso:
# Risky — may pull breaking changes
docker pull documenso/documenso:latest
```
Check the [GitHub releases](https://github.com/documenso/documenso/releases) page for available versions.
---
## Migrations Run Automatically on Startup
The Docker container runs `prisma migrate deploy` every time it starts. This means:
- **Upgrades are simple**: pull the new image, restart the container, and migrations apply automatically.
- **Always back up your database before upgrading**: if a migration fails, you need a way to restore.
- **First startup takes longer**: the initial migration creates all tables.
---
## Set Internal Webapp URL for Background Jobs
Background jobs work by Documenso sending HTTP requests to itself. If your reverse proxy or network setup causes issues with the app reaching its own public URL, set the internal URL:
```bash
NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://localhost:3000
```
This tells the job system to use the internal address instead of `NEXT_PUBLIC_WEBAPP_URL` for self-requests.
---
## Database Storage vs S3
Documents are stored in PostgreSQL by default (`NEXT_PUBLIC_UPLOAD_TRANSPORT=database`). This works well for small-to-medium deployments and keeps your infrastructure simple.
For high-volume deployments, switch to S3-compatible storage to keep your database lean:
```bash
NEXT_PUBLIC_UPLOAD_TRANSPORT=s3
NEXT_PRIVATE_UPLOAD_BUCKET=documenso-documents
NEXT_PRIVATE_UPLOAD_REGION=us-east-1
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID=your-key
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY=your-secret
```
Any S3-compatible provider works: AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces.
See [Storage Configuration](/docs/self-hosting/configuration/storage) for full setup details.
---
## Background Jobs
Documenso uses a PostgreSQL-based job queue by default (`local` provider). No Redis or external message broker is required for basic deployments.
For production workloads, consider switching to **Inngest** (managed) or **BullMQ** (self-hosted with Redis) for better reliability and throughput.
See [Background Jobs Configuration](/docs/self-hosting/configuration/background-jobs) for setup instructions and provider comparison.
---
## IPv6-Only Deployments
If you are deploying to an environment that uses only IPv6, set the `HOST` environment variable to `::` so the application binds to all IPv6 addresses:
**Docker:**
```bash
docker run -it -e HOST=:: documenso/documenso:latest npm run start
```
**Kubernetes or Docker Compose:**
```yaml
containers:
- name: documenso
image: documenso/documenso:latest
command:
- npm
args:
- run
- start
env:
- name: HOST
value: '::'
```
---
## Docker File Permissions
The Documenso container runs as a non-root user (UID 1001). If you mount files into the container (certificates, configuration), ensure they're readable:
```bash
# On the host, before mounting
chmod 644 cert.p12
chown 1001:1001 cert.p12
```
If you see `EACCES: permission denied` errors, this is almost always the cause.
---
## See Also
- [Requirements](/docs/self-hosting/getting-started/requirements) - What you need before deploying
- [Quick Start](/docs/self-hosting/getting-started/quick-start) - Get running in 5 minutes
- [Signing Certificate](/docs/self-hosting/configuration/signing-certificate) - Full certificate setup guide
- [Troubleshooting](/docs/self-hosting/maintenance/troubleshooting) - Detailed error resolution