# Documenso

> Open source document signing platform.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: documenso, postgres
- Tags: documenso, documents, signing, esignature
- Source: https://docker.recipes/productivity/documenso

## Overview

Documenso is an open-source electronic signature platform that serves as a privacy-focused alternative to DocuSign and other proprietary document signing solutions. Built with modern web technologies, it provides legally binding electronic signatures while maintaining full control over your document workflow and data. The platform emphasizes transparency, security, and user privacy, making it an ideal choice for organizations that need compliant e-signature capabilities without vendor lock-in.

This deployment configuration establishes a complete document signing infrastructure using two specialized services: the main Documenso application container running the Next.js-based web interface and API, paired with a PostgreSQL database for persistent storage of documents, signatures, and user data. The setup uses PostgreSQL 15 Alpine for optimal performance and reliability, with the Documenso service configured to handle document uploads, signature field placement, and email-based signing workflows.

This stack is particularly valuable for businesses, legal firms, HR departments, and any organization requiring secure document signing workflows with full data ownership. Unlike cloud-based alternatives, this self-hosted approach ensures sensitive documents never leave your infrastructure while providing the same professional e-signature experience that clients and partners expect.

## Features

- PDF document upload and signature field positioning with drag-and-drop interface
- Email-based signing workflows with automatic notifications to multiple signers
- Legally compliant electronic signatures with audit trails and timestamping
- Multi-party document signing with sequential or parallel signing order support
- Document status tracking and completion notifications for all parties
- PostgreSQL-backed document storage with full ACID compliance for signature integrity
- NextAuth.js authentication system supporting multiple identity providers
- Mobile-responsive signing interface for signatures on any device

## Use cases

- Legal firms processing contracts, NDAs, and client agreements with secure signature workflows
- HR departments handling employment contracts, onboarding documents, and policy acknowledgments
- Real estate agencies managing purchase agreements, lease contracts, and disclosure documents
- Small to medium businesses replacing DocuSign to reduce subscription costs and maintain data control
- Healthcare organizations requiring HIPAA-compliant document signing for patient forms and consent documents
- Educational institutions processing enrollment forms, permission slips, and administrative documents
- Financial services firms handling loan documents, account openings, and compliance paperwork

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for optimal performance
- Port 3000 available on the host system for web interface access
- Environment file (.env) configured with secure NEXTAUTH_SECRET and DB_PASSWORD values
- OpenSSL available for generating cryptographically secure authentication secrets
- Basic understanding of document signing workflows and legal requirements for electronic signatures
- Email server configuration or SMTP credentials for sending signing invitations to document recipients

## docker-compose.yml

```yaml
services:
  documenso:
    image: documenso/documenso:latest
    container_name: documenso
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NEXTAUTH_URL: http://localhost:3000
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXT_PRIVATE_DATABASE_URL: postgresql://documenso:${DB_PASSWORD}@db:5432/documenso
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: documenso-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: documenso
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: documenso
    volumes:
      - documenso_db:/var/lib/postgresql/data

volumes:
  documenso_db:
```

## .env

```bash
DB_PASSWORD=changeme
NEXTAUTH_SECRET=generate-32-char-secret
```

## Usage notes

- Docs: https://documenso.com/docs
- Access at http://localhost:3000 - DocuSign alternative
- Upload PDF documents and add signature fields
- Email signers with signing request links
- Generate secret: openssl rand -hex 32
- Legally binding electronic signatures

## Troubleshooting

- Database connection failed errors: Verify DB_PASSWORD matches between documenso and db services in environment configuration
- NextAuth authentication loops or session errors: Regenerate NEXTAUTH_SECRET using 'openssl rand -hex 32' and restart containers
- Document upload failures or 500 errors: Check container logs with 'docker logs documenso' and ensure adequate disk space for document storage
- Email invitations not sending: Configure SMTP settings in Documenso admin panel or check email server connectivity from container
- PDF signature fields not positioning correctly: Clear browser cache and ensure PDF documents are not password-protected or have form restrictions
- Port 3000 already in use: Change host port mapping to '3001:3000' or stop conflicting services using the port

