Self-Hosting Docmost: Notion Alternative with Real-Time Collaboration

If you’ve been looking for a self-hosted replacement for Notion or Confluence that doesn’t feel like it was built in 2010, Docmost is worth your attention. It’s an open-source collaborative wiki and documentation platform with real-time editing, a clean modern UI, and all the features you’d expect from a paid knowledge base tool.

What sets Docmost apart from the crowded field of self-hosted wikis is polish. The editor is fast. Real-time collaboration actually works. And it ships with diagram support (Draw.io, Excalidraw, and Mermaid), nested spaces with granular permissions, comments, page history, embeds, and file attachments — all out of the box.

Why Docmost Over Other Options

The self-hosted wiki space has options: BookStack, Outline, Wiki.js, Silverbullet, and more. Each has tradeoffs.

BookStack is excellent for structured documentation but feels more like a traditional wiki than a modern workspace. Wiki.js has powerful features but a steeper learning curve. Outline is the closest competitor to Docmost — clean, modern, real-time — but requires a more complex setup with authentication providers.

Docmost hits a sweet spot: modern editor with real-time collaboration, simple Docker deployment, built-in auth (no external identity provider required), and workspace-level management with spaces and groups. If you want something that feels like Notion but runs on your hardware, this is it.

Prerequisites

Before starting, you’ll need:

• A Linux server with Docker and Docker Compose installed
• At least 1GB of RAM (2GB recommended for production use)
• A domain name pointed at your server (optional for local use, required for HTTPS)
• Basic familiarity with the command line

Docker Compose Setup

Create a directory for your Docmost instance:

mkdir docmost && cd docmost

Create a docker-compose.yml file:

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "https://docs.example.com"
      APP_SECRET: "${APP_SECRET}"
      DATABASE_URL: "postgresql://docmost:${DB_PASSWORD}@db:5432/docmost"
      REDIS_URL: "redis://redis:6379"
    ports:
      - "3000:3000"
    restart: unless-stopped
    volumes:
      - docmost_data:/app/data/storage

  db:
    image: postgres:18
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: "${DB_PASSWORD}"
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U docmost"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:8
    command: ["redis-server", "--appendonly", "yes", "--maxmemory-policy", "noeviction"]
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  docmost_data:
  db_data:
  redis_data:

Create a .env file with your secrets:

# Generate a secure app secret (minimum 32 characters)
APP_SECRET=$(openssl rand -hex 32)
DB_PASSWORD=$(openssl rand -hex 16)

cat > .env << EOF
APP_SECRET=${APP_SECRET}
DB_PASSWORD=${DB_PASSWORD}
EOF

The APP_URL in the compose file should match the domain where you’ll access Docmost. For local testing, use http://localhost:3000.

Start everything:

docker compose up -d

Once the containers are running, open http://your-server-ip:3000 in your browser. You’ll see the initial setup page where you create your workspace and first admin account.

Reverse Proxy Configuration

For production use, put Docmost behind a reverse proxy with HTTPS. Docmost uses WebSockets for real-time collaboration, so your proxy must support WebSocket upgrades.

Caddy

Caddy handles WebSockets and HTTPS automatically. That’s the entire config.

Nginx

server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate /etc/ssl/certs/docs.example.com.pem;
    ssl_certificate_key /etc/ssl/private/docs.example.com.key;

    client_max_body_size 50M;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The key lines are proxy_set_header Upgrade and Connection "upgrade" — without those, real-time collaboration breaks silently. Cursors won’t show, edits won’t sync, and you’ll think Docmost is buggy when it’s actually your proxy.

Nginx Proxy Manager

If you’re using Nginx Proxy Manager, create a new proxy host pointing to docmost on port 3000. Enable “WebSockets Support” in the settings tab. Add an SSL certificate through the SSL tab.

Configuring Email

Docmost sends emails for user invitations and password resets. Add SMTP settings to your environment:

environment:
  # ... existing variables ...
  MAIL_DRIVER: "smtp"
  MAIL_HOST: "smtp.example.com"
  MAIL_PORT: "587"
  MAIL_USERNAME: "[email protected]"
  MAIL_PASSWORD: "your-smtp-password"
  MAIL_FROM_ADDRESS: "[email protected]"
  MAIL_FROM_NAME: "Docmost"

Without email configured, you can still create users manually from the admin panel — but invitation links won’t work.

Storage Configuration

By default, Docmost stores uploaded files on local disk in the mounted volume. For production deployments or multi-server setups, you can use S3-compatible storage:

environment:
  STORAGE_DRIVER: "s3"
  STORAGE_S3_ENDPOINT: "https://s3.amazonaws.com"
  STORAGE_S3_REGION: "us-east-1"
  STORAGE_S3_BUCKET: "docmost-files"
  STORAGE_S3_ACCESS_KEY: "your-access-key"
  STORAGE_S3_SECRET_KEY: "your-secret-key"

This works with AWS S3, MinIO, Backblaze B2, Cloudflare R2, or any S3-compatible provider.

Organizing with Spaces

Once you’re logged in, Docmost organizes content into Spaces — think of them as separate wikis or team areas within your workspace. Each space has its own page tree, permissions, and members.

Good space structures for a homelab:

• Infrastructure — server configs, network diagrams, hardware inventory
• Services — setup docs for each self-hosted service
• Runbooks — step-by-step procedures for common tasks
• Personal — notes, bookmarks, research

Each space can be public (visible to all workspace members) or private (invite-only). Combine this with groups to create team-based access — your family sees the shared recipes space, but only you see the infrastructure docs.

Working with Diagrams

One of Docmost’s standout features is integrated diagram support. You don’t need external tools or plugins:

• Draw.io — full-featured diagram editor for network diagrams, flowcharts, and architecture drawings
• Excalidraw — hand-drawn style whiteboard diagrams, great for quick sketches
• Mermaid — code-based diagrams that render from text (flowcharts, sequence diagrams, Gantt charts)

Insert any of these from the editor’s slash command menu (/). Diagrams are stored inline with your pages and render in real-time as collaborators edit them.

For homelab documentation, this is powerful. Draw your network topology in Draw.io, embed it in your infrastructure page, and update it right there when you add a new VLAN.

User Management and Permissions

Docmost has a straightforward permissions model:

• Workspace Owner — full control over everything
• Admin — can manage users, groups, and workspace settings
• Member — can create and edit pages in spaces they have access to

Create Groups to manage access at scale. Instead of adding users individually to each space, create groups like “Family”, “Homelab Team”, or “Read Only” and assign them to spaces with appropriate permission levels.

Invite users via email from the workspace settings, or create accounts manually if you haven’t configured SMTP.

Backup Strategy

Your Docmost data lives in three places: the PostgreSQL database, the Redis store, and the file storage volume. Back up all three.

Database backup script:

#!/bin/bash
BACKUP_DIR="/backups/docmost"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

# Dump the database
docker compose exec -T db pg_dump -U docmost docmost | \
  gzip > "$BACKUP_DIR/docmost-db-${TIMESTAMP}.sql.gz"

# Backup file storage
docker run --rm \
  -v docmost_docmost_data:/data:ro \
  -v "$BACKUP_DIR":/backup \
  alpine tar czf "/backup/docmost-files-${TIMESTAMP}.tar.gz" -C /data .

# Keep last 7 days
find "$BACKUP_DIR" -name "docmost-*" -mtime +7 -delete

echo "Backup completed: ${TIMESTAMP}"

Schedule this with cron to run daily:

0 3 * * * /home/user/docmost/backup.sh >> /var/log/docmost-backup.log 2>&1

To restore, import the SQL dump and extract the files volume:

# Restore database
gunzip -c docmost-db-TIMESTAMP.sql.gz | \
  docker compose exec -T db psql -U docmost docmost

# Restore files
docker run --rm \
  -v docmost_docmost_data:/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/docmost-files-TIMESTAMP.tar.gz -C /data

Health Monitoring

Docmost exposes a health endpoint at /api/health. Use this with your monitoring tool of choice:

# For Uptime Kuma or similar
URL: https://docs.example.com/api/health
Method: GET
Expected Status: 200

You can also add Docker healthchecks to the compose file:

docmost:
  # ... existing config ...
  healthcheck:
    test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 30s

Troubleshooting

Docmost won’t start — “APP_SECRET is required” You forgot to replace the default APP_SECRET. Generate one with openssl rand -hex 32 and update your .env or compose file.

Real-time collaboration not working Almost always a reverse proxy issue. Verify WebSocket support is enabled. Check for intermediaries (Cloudflare, load balancers) that might buffer or timeout WebSocket connections. Cloudflare users should ensure WebSockets are enabled in the Network settings.

Database connection refused The db service might not be ready when Docmost starts. The healthcheck in the compose file above handles this, but you can also add depends_on with a condition:

docmost:
  depends_on:
    db:
      condition: service_healthy
    redis:
      condition: service_healthy

File uploads failing Check your client_max_body_size in Nginx (default is 1MB, which is too small). Set it to at least 50M. If using S3 storage, verify your bucket permissions and CORS settings.

Slow performance with many pages Ensure your PostgreSQL has enough shared memory. Add shm_size: 256mb to the db service in your compose file. For large deployments, tune PostgreSQL with custom configs.

Docmost vs the Alternatives

Conclusion

Docmost fills a gap in the self-hosted documentation space. If you’ve been using Notion or Confluence and want something you control — something that doesn’t charge per seat, doesn’t phone home, and keeps your data on your hardware — Docmost delivers a genuinely modern experience.

The setup is straightforward: three Docker containers, a reverse proxy, and you’re running. Real-time collaboration works without fuss, the diagram integrations save you from juggling separate tools, and the permissions model is simple enough to manage without a dedicated IT team.

For homelabbers documenting their setup, small teams collaborating on projects, or anyone who wants a private knowledge base that doesn’t compromise on features, Docmost is one of the best options available today.

Useful links:

• Docmost GitHub
• Official Documentation
• Docmost Cloud (if you’d rather not self-host)