DPTCloud
Back to articles
Technology Insight

Self-Hosting HedgeDoc on a VPS: Real-Time Collaborative Markdown Editing for Teams

May 30, 2026

Introduction: The Need for Modern, Collaborative Documentation

In the fast-paced landscape of modern business operations, efficient documentation and real-time collaboration are paramount. Teams require agility, transparency, and instant feedback loops when drafting technical specifications, meeting minutes, or project roadmaps. While proprietary solutions like Google Docs or Notion have long dominated the market, they introduce significant long-term licensing overhead and raise pressing questions regarding data privacy and sovereign control over proprietary intellectual property.

For enterprise environments, software engineering teams, and privacy-conscious organizations, a powerful alternative exists: HedgeDoc. Formerly known as CodiMD, HedgeDoc is an open-source, web-based, real-time collaborative Markdown editor. By self-hosting HedgeDoc on a Virtual Private Server (VPS), your organization can combine the elegant simplicity of Markdown formatting with the collaborative efficiency of live, multi-user editing, all while maintaining absolute control over your data lifecycle.

---

Why HedgeDoc? The Enterprise Business Case

Before diving into the technical deployment process, it is essential to understand why HedgeDoc stands out as an enterprise-grade utility. Unlike traditional rich-text editors that generate bloated HTML or proprietary XML schemas, HedgeDoc relies entirely on Markdown. This ensures that all documentation remains lightweight, infinitely portable, and natively compatible with modern documentation workflows, such as Git-based Static Site Generators (SSGs) like Docusaurus, Hugo, or MkDocs.

Key business advantages of self-hosting HedgeDoc include:

  • Real-Time Collaborative Synchronization: Multiple team members can simultaneously edit the same document with zero latency, viewing cursor positions and textual changes instantly.
  • Absolute Data Privacy: Because the application resides entirely on your private VPS, sensitive corporate strategies, API keys, and internal workflows never pass through third-party servers.
  • Extensive Presentation Capabilities: HedgeDoc handles standard Markdown, but also natively renders complex diagrams via Mermaid.js, mathematical formulas via MathJax, and can even transform Markdown files into interactive slide decks using Reveal.js.
  • Granular Permission Control: Document creators can easily toggle access permissions, restricting notes to private, read-only, guest-writable, or fully open states.
---

Prerequisites and System Architecture

To ensure optimal performance, low latency, and high availability for your team, your target infrastructure should meet specific baselines. HedgeDoc itself is remarkably lightweight, but provisioning an appropriate environment guarantees scaling capability.

Recommended VPS Specifications

  • Operating System: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS (highly recommended for stability and community support).
  • Processor: Minimum 1 vCPU (2 vCPUs preferred for active teams exceeding 15 concurrent users).
  • Memory: 2 GB RAM minimum to comfortably accommodate the application node and the underlying database instance.
  • Storage: 20 GB of SSD/NVMe storage, scaling upward based on the volume of embedded media and images your team uploads.

Network and Security Requirements

A successful production deployment requires a fully qualified domain name (FQDN), such as notes.yourcompany.com, pointed via an A Record to your VPS's static IPv4 address. Additionally, ports 80 (HTTP) and 443 (HTTPS) must be open on your firewall to facilitate secure web traffic and Automated Let's Encrypt SSL certificate issuance.

---

Step-by-Step Deployment Guide via Docker Compose

The most robust, reproducible, and maintainable method to deploy HedgeDoc is using Docker and Docker Compose. This containerized architecture isolates the application layer from the database layer, drastically simplifying future updates, backups, and migrations.

Step 1: System Update and Docker Installation

Connect to your VPS via SSH and begin by updating the system packages to their latest versions. Run the following command sequence:

sudo apt update && sudo apt upgrade -y

Next, install Docker and the Docker Compose plugin if they are not already present on the system:

sudo apt install docker.io docker-compose-plugin -y

Verify that the Docker service is active and set to launch automatically upon system boot:

sudo systemctl enable --now docker

Step 2: Structuring the Project Directory

Maintain clean organization on your server by isolating application configurations. Create a dedicated directory for HedgeDoc and navigate into it:

mkdir -p /opt/hedgedoc && cd /opt/hedgedoc

Step 3: Configuring the Environment Variables

HedgeDoc utilizes environment variables to manage database credentials, domain bindings, and security hashes securely. Create a .env file within your directory:

nano .env

Populate the file with the following production configuration, making sure to replace placeholder values with your specific details:

HD_DB_USER=hedgedoc_admin
HD_DB_PASSWORD=YOUR_STRONG_DATABASE_PASSWORD
HD_DB_NAME=hedgedoc_prod
HD_DOMAIN=notes.yourcompany.com
HD_PORT=3000
HD_SESSION_SECRET=YOUR_COMPLEX_RANDOM_SESSION_SECRET

Step 4: Crafting the docker-compose.yml File

Now, define the multi-container architecture using a docker-compose.yml file. This configuration links a PostgreSQL database container with the primary HedgeDoc application node:

nano docker-compose.yml

Insert the following structured YAML content:

version: '3.8'

services:
  database:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=${HD_DB_USER}
      - POSTGRES_PASSWORD=${HD_DB_PASSWORD}
      - POSTGRES_DB=${HD_DB_NAME}
    volumes:
      - database_data:/var/lib/postgresql/data
    restart: always

  app:
    image: lscr.io/linuxserver/hedgedoc:latest
    environment:
      - PID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - CMD_DB_URL=postgres://${HD_DB_USER}:${HD_DB_PASSWORD}@database:5432/${HD_DB_NAME}
      - CMD_DOMAIN=${HD_DOMAIN}
      - CMD_PROTOCOL_USESSL=true
      - CMD_PORT=${HD_PORT}
      - CMD_SESSION_SECRET=${HD_SESSION_SECRET}
    volumes:
      - /opt/hedgedoc/config:/config
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      - database
    restart: always

volumes:
  database_data:

Save and exit the file. Notice that the application port 3000 is bound explicitly to 127.0.0.1. This keeps the application server inaccessible directly from the public internet, routing all public traffic securely through a reverse proxy.

---

Securing Traffic with Nginx and Let's Encrypt SSL

Operating a collaborative platform without encryption exposes sensitive corporate communications to interception. To prevent this, implement Nginx as a reverse proxy coupled with Certbot to handle automated SSL certificates.

Step 1: Install Nginx

Install the web server utilizing the native package manager:

sudo apt install nginx -y

Step 2: Configure the Nginx Virtual Host

Create a dedicated configuration block for your HedgeDoc subdomain:

sudo nano /etc/nginx/sites-available/hedgedoc

Insert the reverse proxy directive mapping incoming public traffic to your local Docker container:

server {
    listen 80;
    server_name notes.yourcompany.com;

    location / {
        proxy_pass [http://127.0.0.1:3000](http://127.0.0.1:3000);
        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;

        # Websocket support for real-time collaboration updates
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

Enable the site configuration by establishing a symbolic link to the active directory, then restart Nginx:

sudo ln -s /etc/nginx/sites-available/hedgedoc /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Step 3: Obtain a Free SSL Certificate

Leverage Certbot to provision an institutional-grade, automated SSL certificate from Let's Encrypt:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d notes.yourcompany.com

Follow the interactive prompt to automatically update the Nginx configuration, ensuring all plain HTTP traffic redirects seamlessly to encrypted HTTPS.

---

Launching and Initializing the Platform

With configurations finalized, return to your primary deployment directory to bring your infrastructure online:

cd /opt/hedgedoc && sudo docker compose up -d

The system will systematically pull the optimized PostgreSQL and HedgeDoc images, build internal private networks, and initialize database tables. You can monitor the system logs using the following command to guarantee a flawless boot sequence:

sudo docker compose logs -f app

Open a modern web browser and navigate to [https://notes.yourcompany.com](https://notes.yourcompany.com). You will be greeted by the minimal, ultra-responsive HedgeDoc landing interface, ready for instantaneous collaborative workspace creation.

---

Enterprise Integration: Authentication Options

Allowing anonymous user registration might introduce security vulnerabilities within an enterprise network. To mitigate this risk, HedgeDoc supports robust enterprise authentication backends out of the box. By modifying your environment profile or the internal config.json mapping file, systems administrators can integrate the platform with:

  • OAuth2 / OpenID Connect (OIDC): Connect directly to identity management systems such as Keycloak, Okta, Authentik, or Google Workspace.
  • LDAP / Active Directory: Sync user profiles seamlessly with internal corporate directories, mapping corporate access control parameters directly to HedgeDoc workspace privileges.
  • GitHub / GitLab OAuth: Ideal for technology teams, allowing engineers to sign in immediately using their existing developer credentials.
---

Conclusion: Sovereign Collaboration Realized

Deploying HedgeDoc on a private VPS successfully bridges the gap between collaborative efficiency and data sovereignty. Your team gains an uncompromised, zero-latency Markdown editing platform that runs independently of third-party platforms, protecting your intellectual asset portfolio. With low resource requirements, built-in structural portability, and native rendering of sophisticated developer components like Mermaid.js diagrams, self-hosted HedgeDoc stands out as an indispensable component of a modern, open-source enterprise tech stack.

Self-Hosting HedgeDoc on a VPS: Real-Time Collaborative Markdown Editing for Teams | DPTCloud