Scaling Engineering Knowledge: Implementing HedgeDoc on VPS for Real-Time Markdown Collaboration

Introduction: The Documentation Dilemma in Software Engineering

In modern software development, documentation is as critical as the code itself. Engineering teams require agile, precise, and friction-free methods to document architectures, API contracts, system designs, and post-mortems. While traditional rich-text editors often introduce formatting inconsistencies and slow down workflows, Markdown has emerged as the gold standard for developer-centric documentation. It integrates seamlessly with version control systems and allows engineers to remain within their text-based comfort zones.

However, standard Markdown files lack a critical capability native to platforms like Google Docs: real-time collaboration. When multiple engineers need to brainstorm system architecture during a live outage or collaboratively draft technical specifications, asynchronous Git commits fall short. This is where HedgeDoc bridges the gap. By hosting HedgeDoc on a private Virtual Private Server (VPS), enterprises can establish a secure, lightning-fast, and open-source collaborative editing platform tailored specifically for engineering teams.

Why HedgeDoc? The Strategic Advantage for Engineering Teams

HedgeDoc (formerly known as CodiMD) is an open-source, web-based, real-time collaborative Markdown editor. For software engineering organizations, deploying HedgeDoc offers several distinct strategic advantages over generic corporate wikis or proprietary SaaS solutions:

• Native Developer Tooling: HedgeDoc natively supports advanced formatting essential for developers, including syntax highlighting for dozens of programming languages, Mermaid.js diagrams, Graphviz, and LaTeX mathematical expressions.
• Data Sovereignty and Security: By hosting the platform on your own VPS, your organization retains absolute ownership of its intellectual property, architectural vulnerabilities, and internal credentials, completely mitigating third-party SaaS data leak risks.
• Zero-Friction Collaboration: Multiple engineers can edit the same document simultaneously with near-zero latency, visualizing the rendered output side-by-side with the raw Markdown syntax.
• Granular Permission Control: Documents can be configured as freely editable, locked for editing but open for viewing, or restricted entirely to authenticated team members.

Prerequisites for VPS Deployment

Before initiating the deployment process, ensure your infrastructure meets the following baseline requirements:

1. A Dedicated VPS: A minimum configuration of 1 vCPU, 2GB RAM, and 20GB SSD storage running a clean installation of a Linux distribution such as Ubuntu 22.04 LTS or Ubuntu 24.04 LTS.
2. Domain Name: A fully qualified domain name (FQDN), for example, docs.yourcompany.com, with an A record pointing to your VPS public IP address.
3. Docker and Docker Compose: The recommended method for deploying HedgeDoc to guarantee environment isolation, easy updates, and reproducible builds.

Step-by-Step Architecture Deployment Guide

To ensure optimal security, performance, and maintainability, this guide utilizes a production-ready architecture featuring Docker Compose, a PostgreSQL database, and an Nginx Reverse Proxy secured with an automated Let's Encrypt SSL/TLS certificate.

Step 1: System Preparation and Docker Installation

First, access your VPS via SSH and update the system package repository to ensure all security patches are current:

sudo apt update && sudo apt upgrade -y

Next, install the Docker engine and the Docker Compose plugin, which will manage our multi-container application stack:

sudo apt install docker.io docker-compose-v2 -y
sudo systemctl enable --now docker

Step 2: Configuring the Docker Compose Environment

Create a dedicated directory for your HedgeDoc deployment to keep configuration files organized:

mkdir -p ~/hedgedoc && cd ~/hedgedoc

Create a docker-compose.yml file using your preferred text editor. This file defines the HedgeDoc application container and its dependent PostgreSQL database container:

version: '3.8'

services:
  database:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=YourSecurePasswordHere
      - POSTGRES_DB=hedgedoc
    volumes:
      - database_data:/var/lib/postgresql/data
    restart: always

  app:
    image: hedgedoc/hedgedoc:1.9.9
    environment:
      - CMD_DB_URL=postgres://hedgedoc:YourSecurePasswordHere@database:5432/hedgedoc
      - CMD_DOMAIN=docs.yourcompany.com
      - CMD_PROTOCOL_USESSL=true
      - CMD_PORT=3000
      - CMD_ALLOW_GRAVATAR=true
      - CMD_URL_ADAPTER=v2
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      - database
    restart: always

volumes:
  database_data:

Note: Replace YourSecurePasswordHere with a strong, randomly generated alphanumeric string, and update docs.yourcompany.com with your actual domain.

Step 3: Launching the Containers

With the configuration file defined, pull the official images and initialize the services in detached mode:

sudo docker compose up -d

Verify that both containers are operating successfully by checking their statuses:

sudo docker compose ps

Step 4: Securing the Infrastructure with Nginx and SSL

To expose HedgeDoc safely to your engineering team over the public internet, establish Nginx as a reverse proxy and configure SSL encryption.

Install Nginx and Certbot (the Let's Encrypt client):

sudo apt install nginx certbot python3-certbot-nginx -y

Create a new Nginx server block configuration at /etc/nginx/sites-available/hedgedoc:

server {
    listen 80;
    server_name docs.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 required for real-time collaborative editing
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

Activate the configuration by creating a symbolic link to the enabled sites directory and restarting Nginx:

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

Finally, obtain and install a complimentary Let's Encrypt SSL certificate to enforce HTTPS encryption across all sessions:

sudo certbot --nginx -d docs.yourcompany.com

Follow the interactive on-screen prompts to automatically redirect all HTTP traffic to secure HTTPS connections.

Optimizing HedgeDoc for Enterprise Engineering Workflows

Once deployment is finalized, navigating to your domain greets you with a clean, operational HedgeDoc interface. To fully optimize this asset for engineering teams, consider integrating the following enterprise configurations via environment variables within your docker-compose.yml:

• Authentication Integration (OAuth2/OIDC): Avoid creating isolated silos of user credentials. HedgeDoc supports standard identity providers including GitHub, GitLab, Keycloak, and Google Workspace. Enabling GitHub OAuth allows engineers to log in instantly using their existing enterprise developer profiles.
• Automated Backups: Technical documentation represents critical corporate knowledge. Implement a daily cron job on your VPS to execute pg_dump within the PostgreSQL container, compressing and uploading the database snapshots to an off-site, encrypted cloud storage bucket.
• Persistent Storage for Images: Documents frequently incorporate screenshots, architectural wireframes, and sequence diagrams. Configure HedgeDoc to store uploaded image assets directly on a local directory mapping or integrate an S3-compatible object storage backend.

Conclusion: Cultivating a High-Performance Documentation Culture

Implementing a self-hosted HedgeDoc instance on a VPS addresses the critical operational balance between development velocity and data security. By removing the friction from formatting, offering robust developer-centric rendering, and providing an instantaneous collaborative writing space, teams can significantly improve knowledge retention and onboarding speeds.

Transitioning to a markdown-first, real-time ecosystem ensures that system architectures, onboarding playbooks, and structural engineering paradigms evolve in tandem with the codebases they support—ultimately driving higher code quality and team alignment.