Using Docker for Local Development

Complete guide to Docker-based development workflow for Documenso

Overview

Documenso provides Docker Compose configurations to simplify local development. The Docker setup includes all necessary services: PostgreSQL database, Inbucket mail server, and MinIO S3 storage.

Docker Compose Configuration

The development Docker Compose file is located at docker/development/compose.yml and defines three services:

Services

Database (PostgreSQL 15)

• Container name: database
• Port: 54320 (mapped to 5432 inside container)
• Credentials:
  • User: documenso
  • Password: password
  • Database: documenso
• Volume: documenso_database (persisted data)
• Health check: Runs pg_isready every 10 seconds

Inbucket (Mail Server)

• Container name: mailserver
• Purpose: Captures all outgoing emails for testing
• Ports:
  • 9000: Web UI (view emails)
  • 2500: SMTP server
  • 1100: POP3 server

MinIO (S3-Compatible Storage)

• Container name: minio
• Purpose: Local S3-compatible object storage
• Ports:
  • 9001: Web console
  • 9002: API endpoint
• Credentials:
  • User: documenso
  • Password: password
• Bucket: documenso (automatically created)
• Volume: minio (persisted data)

Quick Start

The fastest way to start all Docker services:

1. Start all services and set up the database

   npm run dx
   

   This command:

   • Installs dependencies (npm ci)
   • Starts Docker Compose services
   • Runs database migrations
   • Seeds the database with test data
2. Start the development server

   npm run dev
   

Managing Docker Services

Start Services

Full Setup

# Install dependencies, start services, migrate, and seed
npm run dx

Stop Services

npm Script

# Stop all services
npm run dx:down

View Service Status

# List running containers
docker ps

# View logs from all services
docker compose -f docker/development/compose.yml logs

# View logs from a specific service
docker compose -f docker/development/compose.yml logs database
docker compose -f docker/development/compose.yml logs mailserver
docker compose -f docker/development/compose.yml logs minio

# Follow logs in real-time
docker compose -f docker/development/compose.yml logs -f

Accessing Services

Once Docker services are running:

Web Interfaces

Service	URL	Purpose
Inbucket Mail	http://localhost:9000	View all outgoing emails
MinIO Console	http://localhost:9001	Manage S3 buckets and files

Connection Strings

Database

# Connection string for application
postgres://documenso:password@127.0.0.1:54320/documenso

# Connect with psql
psql postgres://documenso:password@127.0.0.1:54320/documenso

# Connect with docker exec
docker exec -it database psql -U documenso -d documenso

MinIO S3

Endpoint: http://127.0.0.1:9002
Access Key: documenso
Secret Key: password
Bucket: documenso
Region: unknown

SMTP (Inbucket)

Host: 127.0.0.1
Port: 2500
No authentication required

Environment Variables for Docker Services

When using the Docker Compose setup, configure these variables in your .env file:

# Database
NEXT_PRIVATE_DATABASE_URL="postgres://documenso:password@127.0.0.1:54320/documenso"
NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://documenso:password@127.0.0.1:54320/documenso"

# Mail Server (Inbucket)
NEXT_PRIVATE_SMTP_TRANSPORT="smtp-auth"
NEXT_PRIVATE_SMTP_HOST="127.0.0.1"
NEXT_PRIVATE_SMTP_PORT=2500
NEXT_PRIVATE_SMTP_USERNAME="documenso"
NEXT_PRIVATE_SMTP_PASSWORD="password"
NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"

# S3 Storage (MinIO)
NEXT_PUBLIC_UPLOAD_TRANSPORT="s3"  # or "database" to store in PostgreSQL
NEXT_PRIVATE_UPLOAD_ENDPOINT="http://127.0.0.1:9002"
NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLE="false"
NEXT_PRIVATE_UPLOAD_REGION="unknown"
NEXT_PRIVATE_UPLOAD_BUCKET="documenso"
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID="documenso"
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY="password"

Using Inbucket for Email Testing

Inbucket captures all outgoing emails during development:

1. Access the web interface

   Navigate to http://localhost:9000 in your browser

2. View emails

   All emails sent by the application will appear in the Inbucket inbox. Click on any email to view its contents, including HTML and plain text versions.

3. Test email flows

   Trigger email-sending actions in Documenso:

   • User registration
   • Password reset
   • Document signing invitations
   • Document completion notifications

   All emails will be captured and visible in Inbucket.

Using MinIO for S3 Storage

MinIO provides S3-compatible object storage for document files:

1. Access the console

   Navigate to http://localhost:9001 and log in:

   • Username: documenso
   • Password: password
2. View uploaded documents

   Browse the documenso bucket to see uploaded PDF files and other assets.

3. Switch between storage modes

   Documenso supports two storage modes:

   Database storage (default):

   NEXT_PUBLIC_UPLOAD_TRANSPORT="database"
   

   S3 storage (using MinIO):

   NEXT_PUBLIC_UPLOAD_TRANSPORT="s3"
   

   Update the .env file and restart the dev server to switch modes.

Production Docker Setup

For self-hosting Documenso in production, use the production Docker Compose configuration:

Production Compose File

Located at docker/production/compose.yml, this setup includes:

• PostgreSQL database with persistent storage
• Documenso application container (from DockerHub or GitHub Container Registry)

Pulling the Docker Image

Documenso provides official Docker images:

# From DockerHub
docker pull documenso/documenso:latest

# From GitHub Container Registry
docker pull ghcr.io/documenso/documenso:latest

Running with Docker Compose

1. Create environment file

   Create a .env file with your production configuration:

   # Required variables
   POSTGRES_USER=documenso
   POSTGRES_PASSWORD=your-secure-password
   POSTGRES_DB=documenso
   
   NEXTAUTH_SECRET=your-random-secret
   NEXT_PRIVATE_ENCRYPTION_KEY=your-32-char-key
   NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=your-32-char-secondary-key
   
   NEXT_PUBLIC_WEBAPP_URL=https://your-domain.com
   NEXT_PRIVATE_DATABASE_URL=postgres://documenso:your-secure-password@database:5432/documenso
   
   NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
   NEXT_PRIVATE_SMTP_FROM_NAME=Documenso
   NEXT_PRIVATE_SMTP_FROM_ADDRESS=[e-mail]
   # ... additional SMTP configuration
   
2. Start the services

   docker compose -f docker/production/compose.yml up -d
   
3. Run migrations

   docker exec -it <container-name> npm run prisma:migrate-deploy
   

For detailed production deployment instructions, see the Docker README.

Building Custom Docker Images

To build your own Docker image:

# Build the image
docker build -f docker/Dockerfile -t documenso:custom .

# Run the container
docker run -p 3000:3000 \
  --env-file .env \
  documenso:custom

IPv6 Support

If deploying to an IPv6-only cluster, use a custom start command:

Local Docker Run

docker run -it documenso:latest npm run start -- -H ::

Kubernetes or Docker Compose

containers:
  - name: documenso
    image: documenso:latest
    command:
      - npm
    args:
      - run
      - start
      - --
      - -H
      - '::'

Troubleshooting

Services Not Starting

Check service logs:

docker compose -f docker/development/compose.yml logs

Database Connection Refused

1. Ensure the database container is healthy:

   docker ps
   

   Look for “healthy” status in the database container.

2. Check the health check logs:

   docker inspect database | grep -A 10 Health
   

3. Verify the database is accepting connections:

   docker exec database pg_isready -U documenso
   

Port Conflicts

If ports are already in use, you can modify the port mappings in the compose file or stop the conflicting services:

# Find what's using a port
lsof -i :54320
lsof -i :9000
lsof -i :9001

Resetting Data

To start fresh with clean data:

# Stop services and remove volumes
npm run dx:down
docker compose -f docker/development/compose.yml down -v

# Start services again
npm run dx

Container Disk Space

Clean up unused Docker resources:

# Remove unused containers, networks, and images
docker system prune

# Remove all unused volumes (WARNING: deletes data)
docker volume prune

Next Steps

• Database Setup and Migrations
• Running Tests
• Local Development Setup