Codakey
Play
← Back to docmost

How to Deploy & Use docmost

Docmost Deployment and Usage Guide

1. Prerequisites

Before installing Docmost, ensure you have the following installed on your system:

Runtime & Database:

  • Node.js 18+ (TypeScript project)
  • PostgreSQL 14+ (primary database)
  • Redis (for queues and caching)
  • MinIO or AWS S3-compatible storage (for file attachments)

Development Tools:

  • Git
  • pnpm (preferred package manager)
  • Docker and Docker Compose (optional, for containerized deployment)

External Service Accounts (Optional but Recommended):

  • Algolia account for full-text search
  • Email service (SMTP) for notifications
  • Object storage service (AWS S3, MinIO, etc.)

2. Installation

Clone the repository and install dependencies:

# Clone the repository
git clone https://github.com/docmost/docmost.git
cd docmost

# Install dependencies using pnpm
pnpm install

# Set up environment file
cp .env.example .env

Project Structure:

  • apps/server/ - Backend NestJS application
  • apps/client/ - Frontend React application
  • packages/ - Shared TypeScript packages
  • packages/ee/ - Enterprise Edition features (requires license)

3. Configuration

Edit the .env file with your configuration:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/docmost

# Redis
REDIS_URL=redis://localhost:6379

# Storage (S3-compatible)
STORAGE_ENDPOINT=localhost:9000
STORAGE_BUCKET=docmost
STORAGE_ACCESS_KEY=minioadmin
STORAGE_SECRET_KEY=minioadmin
STORAGE_REGION=us-east-1
STORAGE_PROVIDER=minio  # or 's3', 'r2', 'gcs'

# Application
NODE_ENV=production
PORT=3000
CLIENT_URL=http://localhost:3001
SERVER_URL=http://localhost:3000
JWT_SECRET=your-secret-key-here-change-this
ENCRYPTION_KEY=your-encryption-key-here-change-this

# Email (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@docmost.com

# Search (optional - Algolia)
ALGOLIA_APP_ID=your-algolia-app-id
ALGOLIA_API_KEY=your-algolia-api-key
ALGOLIA_INDEX_NAME=docmost_pages

# External Integrations
GOOGLE_CLIENT_ID=  # for Google OAuth
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=  # for GitHub OAuth
GITHUB_CLIENT_SECRET=

Database Setup:

# Create PostgreSQL database
createdb docmost

# Run migrations
pnpm db:migrate

4. Build & Run

Development Mode:

# Start both frontend and backend in development
pnpm dev

# Or start separately:
pnpm dev:server  # Backend on http://localhost:3000
pnpm dev:client  # Frontend on http://localhost:3001

Production Build:

# Build both applications
pnpm build

# Start production server
pnpm start:server

# The client build will be served from the server in production

Using Docker Compose (Quick Start):

# Start all services (PostgreSQL, Redis, MinIO, Docmost)
docker-compose up -d

# View logs
docker-compose logs -f

Database Operations:

# Run migrations
pnpm db:migrate

# Generate new migration
pnpm db:migrate:create migration_name

# Rollback migration
pnpm db:migrate:down

5. Deployment

Docmost can be deployed on various platforms:

Traditional VPS (DigitalOcean, AWS EC2, Linode):

# 1. Set up server with Node.js, PostgreSQL, Redis
# 2. Clone repository and build
# 3. Use PM2 or systemd to run as service
pm2 start pnpm --name "docmost" -- start:server

Docker Deployment:

# Use official Docker image or build your own
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  -e REDIS_URL=redis://... \
  --name docmost \
  docmost/docmost:latest

Platform-as-a-Service Options:

  • Railway.app - One-click deployment with PostgreSQL and Redis add-ons
  • Render.com - Supports Docker and native Node.js deployments
  • Fly.io - Global deployment with persistent volumes
  • Kubernetes - For scalable enterprise deployments

Recommended Production Architecture:

Load Balancer → Docmost Server (multiple instances)
                    ↓
              PostgreSQL (Primary)
                    ↓
              Redis (Cache/Queue)
                    ↓
              S3/MinIO (Storage)

Environment Variables for Production:

  • Set NODE_ENV=production
  • Use strong JWT_SECRET and ENCRYPTION_KEY
  • Configure proper CLIENT_URL and SERVER_URL
  • Set up SSL/TLS certificates (or use a reverse proxy like Nginx)

6. Troubleshooting

Common Issues and Solutions:

  1. Database Connection Errors:

    # Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U postgres -h localhost -d docmost

  2. Migration Failures:

    # Reset database (development only)
pnpm db:migrate:reset

# Check migration status
pnpm db:migrate:status

  3. Storage Issues:

    • Ensure MinIO/S3 bucket exists and is accessible
    • Check storage credentials and permissions
    • Verify STORAGE_PROVIDER is set correctly

  4. Build Errors:

    # Clear node_modules and reinstall
rm -rf node_modules
pnpm install

# Clear build cache
pnpm clean
pnpm build

  5. Memory Issues:

    • Increase Node.js memory limit: NODE_OPTIONS="--max-old-space-size=4096"
    • Configure Redis memory policy in production

  6. Import/Export Issues:

    • Check file permissions for import directories
    • Ensure sufficient disk space for file processing
    • Verify supported formats: Markdown, HTML, Confluence XML

  7. Real-time Collaboration Not Working:

    • Verify WebSocket connections are not blocked
    • Check Redis is running for session storage
    • Ensure proper CORS configuration

Logs and Debugging:

# View application logs
pnpm logs  # or check Docker logs

# Enable debug logging
DEBUG=docmost:* pnpm dev:server

# Check queue workers
redis-cli monitor  # View Redis queue activity

Getting Help:

  • Check the official documentation
  • Review source code in apps/server/src/core/ for core functionality
  • Examine integration services in apps/server/src/integrations/
  • For enterprise features, contact Docmost for licensing

Note: Docmost core is licensed under AGPL 3.0. Enterprise features in packages/ee/ require a separate license.

← Project overviewView alternatives to docmost →