Skip to content
Klutch.sh Docs

Deploying a Docmost App

Introduction

Docmost is an open-source collaborative documentation and wiki platform designed for modern teams. Built with real-time collaboration features, rich text editing, version control, and powerful organization capabilities, Docmost provides a self-hosted alternative to proprietary documentation tools. It combines the flexibility of wikis with the polish of modern content management systems, making it ideal for technical documentation, knowledge bases, project wikis, and team collaboration.

Key features of Docmost include:

  • Real-time collaborative editing with conflict resolution
  • Rich text editor with markdown support
  • Hierarchical page organization and nested structures
  • Version history and rollback capabilities
  • Advanced search with full-text indexing
  • Role-based access control and permissions
  • File attachments and media management
  • API access for automation and integrations
  • Custom domains and branding options

This comprehensive guide walks you through deploying Docmost on Klutch.sh using a Dockerfile, configuring PostgreSQL database and Redis cache, setting up persistent storage, managing environment variables, and implementing production best practices for security, performance, and reliability.

Prerequisites

Before deploying Docmost on Klutch.sh, ensure you have:

  • A Klutch.sh account with access to the dashboard
  • A GitHub repository for your Docmost deployment (or create a new repository)
  • Basic familiarity with Docker, PostgreSQL, and environment variables
  • (Recommended) A PostgreSQL database instance (can be provisioned on Klutch.sh or external provider)
  • (Optional but recommended) A Redis instance for caching and session management
  • Understanding of web application deployment concepts and networking

Project Structure

A typical Docmost deployment repository contains the following files:

docmost-deploy/
├── Dockerfile
├── docker-entrypoint.sh
├── .dockerignore
├── .env.example
└── README.md

This minimal structure keeps the deployment configuration separate from application code. Docmost itself will be pulled from the official Docker image or built from source within the container.

Sample Dockerfile

Docmost provides an official Docker image that simplifies deployment. Here’s a production-ready Dockerfile that uses the official image as a base and adds customization options:

FROM docmost/docmost:latest


# Set working directory
WORKDIR /app


# Environment defaults (override these in Klutch.sh)
ENV NODE_ENV=production
ENV APP_URL=https://example-app.klutch.sh
ENV APP_SECRET=change-this-secret-key
ENV DATABASE_URL=postgresql://user:password@postgres:5432/docmost
ENV REDIS_URL=redis://redis:6379


# Expose the application port
EXPOSE 3000


# Install curl for health checks
RUN apk add --no-cache curl


# Health check to ensure the application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:3000/api/health || exit 1


# Start the application
CMD ["node", "dist/main.js"]

Alternative: Custom Build Dockerfile

If you need to customize the Docmost application or build from source, use this extended Dockerfile:

FROM node:20-alpine AS builder


WORKDIR /app


# Install build dependencies
RUN apk add --no-cache python3 make g++ git


# Clone Docmost (or copy from your repository)
RUN git clone https://github.com/docmost/docmost.git .


# Install dependencies
RUN npm ci --production=false


# Build the application
RUN npm run build


# Production stage
FROM node:20-alpine


WORKDIR /app


# Install runtime dependencies
RUN apk add --no-cache curl tini


# Copy built application from builder
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json


# Create uploads directory for persistent storage
RUN mkdir -p /app/uploads && chown -R node:node /app


# Switch to non-root user
USER node


# Environment defaults
ENV NODE_ENV=production
ENV PORT=3000


# Expose application port
EXPOSE 3000


# Use tini for proper signal handling
ENTRYPOINT ["/sbin/tini", "--"]


# Start the application
CMD ["node", "dist/main.js"]

Database Setup: PostgreSQL

Docmost requires PostgreSQL 12 or newer for data persistence. You have several options for database setup:

Option 1: Provision PostgreSQL on Klutch.sh

Follow the PostgreSQL deployment guide to create a database instance on Klutch.sh. Once deployed, note the connection details for configuration.

Option 2: Use External PostgreSQL

Use a managed PostgreSQL service from providers like AWS RDS, DigitalOcean, or Supabase. Ensure the database is accessible from Klutch.sh’s network.

Database Configuration

Create a dedicated database and user for Docmost:

CREATE DATABASE docmost;
CREATE USER docmost_user WITH ENCRYPTED PASSWORD 'secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE docmost TO docmost_user;
\c docmost
GRANT ALL ON SCHEMA public TO docmost_user;

The connection string format for Docmost is:

postgresql://docmost_user:secure_password_here@postgres-host:5432/docmost

Redis significantly improves Docmost’s performance by caching frequently accessed data and managing session state. While optional for small deployments, it’s essential for production use.

Option 1: Provision Redis on Klutch.sh

Deploy a Redis instance on Klutch.sh following the Redis deployment guide.

Option 2: Use External Redis

Use a managed Redis service or deploy Redis alongside Docmost. The Redis connection string format is:

redis://redis-host:6379

For Redis with authentication:

redis://username:password@redis-host:6379

Environment Variables

Docmost is configured entirely through environment variables. Set these in the Klutch.sh dashboard under your app’s Environment Variables section:

Core Application Settings

Terminal window
# Application URL (must match your deployment URL)
APP_URL=https://example-app.klutch.sh


# Secret key for encryption and sessions (generate a random 32+ character string)
APP_SECRET=your-very-secure-random-secret-key-change-this


# Node environment
NODE_ENV=production


# Application port (Docmost default is 3000)
PORT=3000

Database Configuration

Terminal window
# PostgreSQL connection string
DATABASE_URL=postgresql://docmost_user:secure_password@postgres-host:5432/docmost


# Optional: Database connection pool settings
DB_POOL_MIN=2
DB_POOL_MAX=10

Redis Configuration (Optional)

Terminal window
# Redis connection string for caching and sessions
REDIS_URL=redis://redis-host:6379


# Optional: Redis key prefix
REDIS_PREFIX=docmost:

File Storage Configuration

Terminal window
# Storage driver: 'local' or 's3'
STORAGE_DRIVER=local


# For local storage (default)
STORAGE_LOCAL_PATH=/app/uploads


# For S3-compatible storage (optional)
STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
STORAGE_S3_BUCKET=docmost-uploads
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ACCESS_KEY=your-access-key
STORAGE_S3_SECRET_KEY=your-secret-key

Email Configuration (Optional)

Terminal window
# SMTP settings for notifications and user invitations
MAIL_DRIVER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME=Docmost

Security Settings

Terminal window
# Enable HTTPS enforcement
FORCE_HTTPS=true


# CORS origins (if needed for API access)
CORS_ORIGINS=https://example.com,https://app.example.com


# Rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=900000

Persistent Storage Configuration

Docmost stores uploaded files, attachments, and media locally by default. To prevent data loss during deployments or container restarts, attach a persistent volume.

    1. Create a Persistent Volume

      In the Klutch.sh dashboard, navigate to your app settings and create a new volume:

      • Mount Path: /app/uploads
      • Size: Start with 10GB and increase based on usage

      This ensures all uploaded files persist across deployments.

    2. Configure Storage in Environment Variables

      Set the storage path to match your volume mount:

      Terminal window
      STORAGE_DRIVER=local
      STORAGE_LOCAL_PATH=/app/uploads

    3. Verify Permissions

      Ensure the container has write permissions to the mounted volume. The Dockerfile should create the directory with proper ownership:

      RUN mkdir -p /app/uploads && chown -R node:node /app

    4. (Optional) Use S3-Compatible Storage

      For larger deployments or distributed systems, configure S3-compatible object storage:

      Terminal window
      STORAGE_DRIVER=s3
      STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
      STORAGE_S3_BUCKET=docmost-uploads
      STORAGE_S3_REGION=us-east-1
      STORAGE_S3_ACCESS_KEY=your-access-key
      STORAGE_S3_SECRET_KEY=your-secret-key

Deploying to Klutch.sh

Follow these steps to deploy Docmost on Klutch.sh:

    1. Prepare Your Repository

      Create a new GitHub repository or use an existing one. Add your Dockerfile to the repository root. If Klutch.sh detects a Dockerfile in the root directory, it automatically uses Docker for deployment.

      Terminal window
      git init
      git add Dockerfile .dockerignore README.md
      git commit -m "Initial Docmost deployment configuration"
      git remote add origin https://github.com/yourusername/docmost-deploy.git
      git push -u origin main

    2. Create a New App in Klutch.sh

      • Log in to the Klutch.sh dashboard
      • Click “Create New App”
      • Connect your GitHub repository
      • Klutch.sh will automatically detect the Dockerfile

    3. Configure Environment Variables

      In the app settings, add all required environment variables from the section above:

      • APP_URL - Set to your Klutch.sh app URL (e.g., https://docmost-app.klutch.sh)
      • APP_SECRET - Generate a secure random string
      • DATABASE_URL - Your PostgreSQL connection string
      • REDIS_URL - Your Redis connection string (if using)
      • Additional configuration as needed

      Mark sensitive variables (passwords, secrets) as secret to prevent them from appearing in logs.

    4. Set Application Port

      Configure the internal port that Docmost listens on:

      • Set the internal port to 3000 (Docmost’s default)
      • Klutch.sh automatically routes HTTP traffic to this port

    5. Attach Persistent Volume

      • Navigate to the Volumes section in your app settings
      • Create or attach a volume with mount path /app/uploads
      • Set an appropriate size (start with 10GB)

    6. Configure Traffic Type

      In the Klutch.sh UI, select HTTP as the traffic type since Docmost is a web application.

    7. Deploy the Application

      Click “Deploy” to start the build and deployment process. Klutch.sh will:

      • Build the Docker image from your Dockerfile
      • Start the container with your environment variables
      • Mount the persistent volume
      • Route traffic to your application

      Monitor the build logs to ensure everything completes successfully.

    8. Initial Setup

      Once deployed, visit your Docmost URL (https://your-app.klutch.sh):

      • The first time you access Docmost, you’ll be prompted to create an admin account
      • Set up your organization name and admin credentials
      • Configure additional settings through the admin panel

Custom Domain Configuration

To use your own domain with Docmost:

    1. Add Custom Domain in Klutch.sh

      Navigate to your app settings and add your custom domain (e.g., docs.example.com). See the custom domains guide for detailed instructions.

    2. Configure DNS Records

      Point your domain to Klutch.sh by creating DNS records as instructed in the dashboard. Klutch.sh automatically provisions and manages TLS certificates for HTTPS.

    3. Update APP_URL Environment Variable

      Update the APP_URL environment variable to match your custom domain:

      Terminal window
      APP_URL=https://docs.example.com

      Redeploy the application for the changes to take effect.

    4. Verify HTTPS

      Once DNS propagates, access your Docmost instance via your custom domain. Klutch.sh automatically enforces HTTPS for secure connections.

Database Migrations and Updates

When updating Docmost to a new version, database migrations may be required:

Manual Migration Process

If you need to run migrations manually, you can do so through the Klutch.sh dashboard or by connecting to your container:

Terminal window
# Find your container name in the Klutch.sh dashboard under "Container Info"
# Or use: docker ps | grep docmost


# Connect to your Klutch.sh app container
docker exec -it your-container-name /bin/sh


# Run migrations
npm run migration:run


# Restart the application
exit

Note: Container access methods vary by deployment platform. Use the Klutch.sh dashboard for the recommended approach to execute commands or view container information.

Automatic Migrations

Configure Docmost to run migrations automatically on startup by modifying your Dockerfile’s CMD:

CMD ["sh", "-c", "npm run migration:run && node dist/main.js"]

Note: This approach may cause brief downtime during deployment. For zero-downtime updates, run migrations separately before deploying the new version.

Backup and Recovery

Regular backups are essential for data protection:

Database Backup

Backup your PostgreSQL database regularly:

Terminal window
# Manual backup
pg_dump -h postgres-host -U docmost_user -d docmost > docmost-backup-$(date +%Y%m%d).sql


# Restore from backup
psql -h postgres-host -U docmost_user -d docmost < docmost-backup-20240101.sql

For automated backups:

  • Use your PostgreSQL provider’s backup features
  • Schedule regular backups using cron jobs or Klutch.sh scheduled tasks
  • Store backups in object storage (S3, Google Cloud Storage, etc.)

File Storage Backup

If using local file storage:

Terminal window
# Backup uploaded files
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz /app/uploads


# Restore uploaded files
tar -xzf uploads-backup-20240101.tar.gz -C /app/

For S3 storage, use your cloud provider’s backup and versioning features.

Monitoring and Performance

Application Monitoring

Monitor key metrics to ensure optimal performance:

  • CPU Usage: Should remain below 70% under normal load
  • Memory Usage: Docmost typically uses 512MB-2GB depending on traffic
  • Response Times: API endpoints should respond within 200-500ms
  • Database Connections: Monitor connection pool usage and query performance

Health Checks

Docmost exposes a health check endpoint at /api/health. Configure Klutch.sh to use this endpoint for automated health monitoring.

Log Management

The best way to access application logs is through the Klutch.sh dashboard, which provides a web interface for viewing and searching logs. For local development or troubleshooting, you can also use Docker commands:

Terminal window
# View real-time logs (for local development)
docker logs -f your-container-name


# Search logs for errors (for local development)
docker logs your-container-name | grep ERROR

Recommended: Always use the Klutch.sh dashboard for production log access, as it provides better search, filtering, and persistence capabilities.

Performance Optimization

Optimize Docmost performance with these settings:

Terminal window
# Database connection pooling
DB_POOL_MIN=5
DB_POOL_MAX=20


# Redis caching
REDIS_URL=redis://redis-host:6379
CACHE_TTL=3600


# Enable compression
COMPRESSION_ENABLED=true

Security Best Practices

Implement these security measures for production deployments:

    1. Use Strong Secrets

      Generate cryptographically secure random strings for APP_SECRET:

      Terminal window
      openssl rand -base64 32

    2. Enable HTTPS

      Always use HTTPS for production. Klutch.sh automatically provides TLS certificates. Set:

      Terminal window
      FORCE_HTTPS=true

    3. Database Security

      • Use strong database passwords (32+ characters)
      • Limit database user permissions to only required operations
      • Use SSL/TLS for database connections when possible
      • Keep PostgreSQL updated with security patches

    4. Environment Variable Security

      • Mark all sensitive variables (passwords, API keys) as secrets in Klutch.sh
      • Never commit secrets to your Git repository
      • Rotate secrets regularly (every 90 days recommended)

    5. Network Security

      • Use private networking for database and Redis connections when available
      • Configure firewall rules to restrict access
      • Enable rate limiting to prevent abuse

    6. Update Regularly

      • Keep Docmost updated to the latest version
      • Monitor security advisories for dependencies
      • Update PostgreSQL and Redis regularly

    7. Access Control

      • Configure role-based access control (RBAC) in Docmost
      • Enable two-factor authentication (2FA) for admin accounts
      • Regularly audit user permissions and remove unused accounts

    8. CORS Configuration

      If exposing APIs, configure CORS appropriately:

      Terminal window
      CORS_ORIGINS=https://example.com,https://app.example.com

Scaling Considerations

As your Docmost usage grows, consider these scaling strategies:

Vertical Scaling

Increase resources for a single instance:

  • Upgrade to a larger instance size in Klutch.sh
  • Increase database connection pool size
  • Add more Redis memory for caching

Horizontal Scaling

For high-availability deployments:

  • Deploy multiple Docmost instances behind a load balancer
  • Use external PostgreSQL with connection pooling (PgBouncer)
  • Use external Redis for shared session state
  • Store files in S3-compatible object storage (required for multi-instance deployments)

Database Optimization

  • Enable PostgreSQL query caching
  • Create appropriate indexes for frequently accessed data
  • Use read replicas for read-heavy workloads
  • Implement connection pooling with PgBouncer

Troubleshooting

Common Issues and Solutions

Problem: Application fails to start with database connection errors

Solution:

  • Verify DATABASE_URL is correct and accessible
  • Check database credentials and permissions
  • Ensure PostgreSQL is running and accepting connections
  • Test connectivity: psql $DATABASE_URL

Problem: Uploads fail or files are lost after redeployment

Solution:

  • Ensure persistent volume is attached to /app/uploads
  • Verify volume permissions (container user must have write access)
  • Check STORAGE_LOCAL_PATH environment variable matches mount path
  • Consider using S3 storage for production

Problem: Slow performance or timeouts

Solution:

  • Enable Redis caching with REDIS_URL
  • Increase database connection pool: DB_POOL_MAX=20
  • Optimize PostgreSQL configuration
  • Monitor and increase instance resources if needed

Problem: Authentication or session issues

Solution:

  • Verify APP_SECRET is set and hasn’t changed
  • Ensure APP_URL matches your actual URL
  • Check Redis is accessible if using for sessions
  • Clear browser cache and cookies

Problem: HTTPS/SSL errors

Solution:

  • Ensure custom domain is properly configured
  • Wait for DNS propagation (can take up to 48 hours)
  • Verify Klutch.sh has provisioned TLS certificate
  • Set FORCE_HTTPS=true in environment variables

Example: Complete Quickstart

Here’s a complete example to get Docmost running quickly:

1. Create Dockerfile

FROM docmost/docmost:latest
WORKDIR /app
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", "dist/main.js"]

2. Create .env.example

Terminal window
APP_URL=https://your-app.klutch.sh
APP_SECRET=generate-32-char-random-string
DATABASE_URL=postgresql://user:pass@host:5432/docmost
REDIS_URL=redis://redis-host:6379
STORAGE_DRIVER=local
STORAGE_LOCAL_PATH=/app/uploads

3. Deploy to Klutch.sh

  • Push code to GitHub
  • Create app in Klutch.sh dashboard
  • Add environment variables
  • Attach volume to /app/uploads
  • Set internal port to 3000
  • Deploy and access your Docmost instance

Advanced Configuration

Custom Branding

Customize Docmost’s appearance:

Terminal window
APP_NAME=Your Company Docs
APP_LOGO_URL=https://example.com/logo.png

SSO Integration

Configure single sign-on (SSO) for enterprise authentication:

Terminal window
OAUTH_ENABLED=true
OAUTH_PROVIDER=google
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

Security Note: Always mark OAUTH_CLIENT_SECRET and other sensitive OAuth credentials as secret in the Klutch.sh environment variables configuration to prevent exposure in logs and build outputs.

Webhook Notifications

Enable webhooks for integrations:

Terminal window
WEBHOOK_ENABLED=true
WEBHOOK_URL=https://hooks.example.com/docmost

Getting Started with Docmost

After successful deployment:

  1. Create Your First Space

    • Log in to your Docmost instance
    • Click “Create Space” to create a documentation space
    • Set permissions and invite team members

  2. Create Documentation

    • Click “New Page” to create your first document
    • Use the rich text editor or markdown mode
    • Organize pages in a hierarchical structure

  3. Collaborate in Real-Time

    • Share pages with team members
    • Edit documents simultaneously with real-time updates
    • Use comments and suggestions for collaboration

  4. Organize Content

    • Create nested pages and subpages
    • Use tags for categorization
    • Set up navigation menus and sidebars

  5. Configure Permissions

    • Set up role-based access control
    • Define page-level permissions
    • Manage team member access

Migration from Other Platforms

Migrating from Notion

Export your Notion workspace as Markdown, then import into Docmost through the admin panel.

Migrating from Confluence

Use Confluence’s export feature to generate XML, then convert to Markdown using tools like pandoc before importing.

Migrating from GitBook

GitBook content is already in Markdown format. Import directly or use the Docmost API for bulk imports.

Resources and Support

Conclusion

Deploying Docmost on Klutch.sh provides a powerful, self-hosted documentation platform with enterprise-grade features. With proper configuration of PostgreSQL, Redis, persistent storage, and security measures, you can create a reliable documentation system that scales with your organization’s needs. Follow this guide to deploy Docmost successfully and customize it for your specific requirements.

For additional help or advanced configurations, consult the Docmost documentation or reach out to the Klutch.sh support team.