Local Development Setup

Complete guide to setting up Documenso for local development

Overview

This guide will walk you through setting up Documenso on your local machine for development. Documenso is a full-stack document signing platform built with React Router (Remix), TypeScript, Prisma, and PostgreSQL.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js v22.0.0 or higher
• npm v10.7.0 or higher
• PostgreSQL database (or Docker to run one)
• Git for version control
• Docker and Docker Compose (optional, but recommended)

Quick Start (Recommended)

The fastest way to get started is using the developer quickstart, which uses Docker Compose to set up all dependencies.

1. Fork and clone the repository

   First, fork the Documenso repository to your GitHub account.

   Then clone your fork:

   git clone https://github.com/<your-username>/documenso
   cd documenso
   
2. Set up environment variables

   Copy the example environment file:

   cp .env.example .env
   

   The default values in .env.example are configured to work with the Docker Compose setup out of the box.

3. Run the developer quickstart

   The quickest way to get everything running:

   npm run d
   

   This single command:

   • Installs all dependencies
   • Starts PostgreSQL, MinIO (S3), and Inbucket (email) in Docker
   • Runs database migrations
   • Seeds the database with test data
   • Compiles translations
   • Starts the development server

   Alternatively, you can run these steps individually:

   # Install dependencies and start Docker services
   npm run dx
   
   # Start the development server
   npm run dev
   
4. Access the application

   Once everything is running, you can access:

   • Application: http://localhost:3000
   • Email Inbox (Inbucket): http://localhost:9000
   • S3 Dashboard (MinIO): http://localhost:9001
   • Database: localhost:54320 (postgres://documenso:password@localhost:54320/documenso)
5. Create your account

   Navigate to http://localhost:3000/signup and register a new user account to get started.

Manual Setup

If you prefer to set up services manually without Docker:

1. Fork and clone the repository

   git clone https://github.com/<your-username>/documenso
   cd documenso
   
2. Install dependencies

   npm install
   
3. Configure environment variables

   Create a .env file from the example:

   cp .env.example .env
   

   Update the following required variables:

   # Authentication
   NEXTAUTH_SECRET="your-random-secret-here"
   
   # Application URLs
   NEXT_PUBLIC_WEBAPP_URL="http://localhost:3000"
   
   # Database (adjust for your PostgreSQL setup)
   NEXT_PRIVATE_DATABASE_URL="postgres://user:password@localhost:5432/documenso"
   NEXT_PRIVATE_DIRECT_DATABASE_URL="postgres://user:password@localhost:5432/documenso"
   
   # SMTP (for local development, use a service like Inbucket or MailHog)
   NEXT_PRIVATE_SMTP_FROM_NAME="Documenso"
   NEXT_PRIVATE_SMTP_FROM_ADDRESS="[e-mail]"
   NEXT_PRIVATE_SMTP_HOST="localhost"
   NEXT_PRIVATE_SMTP_PORT=2500
   
   # Encryption keys (generate random strings)
   NEXT_PRIVATE_ENCRYPTION_KEY="your-32-char-encryption-key"
   NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY="your-32-char-secondary-key"
   
4. Set up the database

   Run Prisma migrations to create the database schema:

   npm run prisma:migrate-dev
   

   See the Database Setup guide for more details.

5. Compile translations

   npm run translate:compile
   
6. Start the development server

   npm run dev
   

   The application will be available at http://localhost:3000

7. Seed the database (optional)

   Create test data including a test user and sample document:

   npm run prisma:seed
   

Development Workflow

Available Scripts

The following npm scripts are available for development:

Development

# Start the main development server (Remix app)
npm run dev

# Start the documentation site
npm run dev:docs

# Start the OpenPage API
npm run dev:openpage-api

Project Structure

Documenso is organized as a monorepo:

documenso/
├── apps/
│   └── remix/              # Main application (React Router)
├── packages/
│   ├── api/               # API routes and endpoints
│   ├── app-tests/         # E2E tests (Playwright)
│   ├── auth/              # Authentication logic
│   ├── email/             # Email templates (react-email)
│   ├── lib/               # Shared utilities and helpers
│   ├── prisma/            # Database schema and migrations
│   ├── trpc/              # tRPC API definitions
│   └── ui/                # Shared UI components (shadcn/ui)
├── docker/
│   ├── development/       # Docker Compose for local dev
│   ├── production/        # Production Docker setup
│   └── Dockerfile
└── .env.example          # Environment variables template

Environment Variables

Key environment variables you’ll work with:

Required Variables

Variable	Description	Example
NEXTAUTH_SECRET	Secret for NextAuth.js session encryption	your-random-secret
NEXT_PUBLIC_WEBAPP_URL	Public URL of your application	http://localhost:3000
NEXT_PRIVATE_DATABASE_URL	PostgreSQL connection string	postgres://user:pass@localhost:5432/db
NEXT_PRIVATE_DIRECT_DATABASE_URL	Direct database connection (non-pooled)	Same as above for local dev
NEXT_PRIVATE_SMTP_FROM_NAME	Email sender name	Documenso
NEXT_PRIVATE_SMTP_FROM_ADDRESS	Email sender address	[e-mail]
NEXT_PRIVATE_ENCRYPTION_KEY	32+ character encryption key	Random string
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY	32+ character secondary key	Random string

Development Services (with Docker Compose)

Variable	Default	Description
NEXT_PRIVATE_SMTP_HOST	127.0.0.1	SMTP server (Inbucket)
NEXT_PRIVATE_SMTP_PORT	2500	SMTP port
NEXT_PRIVATE_UPLOAD_ENDPOINT	http://127.0.0.1:9002	MinIO S3 endpoint
NEXT_PRIVATE_UPLOAD_BUCKET	documenso	S3 bucket name
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID	documenso	MinIO access key
NEXT_PRIVATE_UPLOAD_SECRET_ACCESS_KEY	password	MinIO secret key

Optional Features

Variable	Description
NEXT_PRIVATE_GOOGLE_CLIENT_ID	Google OAuth client ID
NEXT_PRIVATE_GOOGLE_CLIENT_SECRET	Google OAuth client secret
NEXT_PRIVATE_MICROSOFT_CLIENT_ID	Microsoft OAuth client ID
NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET	Microsoft OAuth client secret
NEXT_PRIVATE_STRIPE_API_KEY	Stripe API key for billing
GOOGLE_VERTEX_API_KEY	Google Vertex AI API key for AI features

See the .env.example file for a complete list of environment variables.

Using Environment Variables in Scripts

If you need to run a script with environment variables loaded, use the with:env wrapper:

npm run with:env -- <your-command>

This loads environment variables from both .env and .env.local files.

Common Issues

Not Receiving Emails

When using the Docker quickstart, emails are captured by Inbucket instead of being sent. Access the web UI at http://localhost:9000 to view all outgoing emails.

Environment Variables Not Loading

If you’re running package scripts directly, wrap them with with:env:

npm run with:env -- npx prisma studio

Port Already in Use

If port 3000 is already in use, you can change it by setting the PORT environment variable:

PORT=3001 npm run dev

Or update it in your .env file:

PORT=3001

Database Connection Issues

If you’re having trouble connecting to the database:

1. Ensure PostgreSQL is running (check Docker with docker ps if using Docker Compose)
2. Verify the connection string in NEXT_PRIVATE_DATABASE_URL
3. Check that the database exists
4. Ensure the database port (default 54320 for Docker) is not blocked

Next Steps

• Using Docker for Development - Detailed Docker setup guide
• Database Setup and Migrations - Learn about Prisma and migrations
• Running Tests - Test strategy and execution
• Contributing Guide - Guidelines for contributors

Video Tutorial

Prefer a video walkthrough? Check out this setup guide:

Alternative Development Environments

Gitpod

Launch a ready-to-use development environment in your browser:

DevContainer (VS Code)

Open the project in a VS Code DevContainer:

Open in DevContainer