Self-Hosting Excalidraw for Collaborative Diagrams

In this article, we'll walk through the complete process of working with excalidraw in a server environment. Understanding diagrams is essential for maintaining a reliable and performant infrastructure.

Prerequisites

• Basic familiarity with the Linux command line
• A reverse proxy configured (Nginx or Traefik)
• Docker and Docker Compose installed
• Root or sudo access to the server

Docker Compose Setup

The default configuration works well for development environments, but production servers require additional tuning. Pay particular attention to connection limits, timeout values, and logging settings.

# docker-compose.yml
version: '3.8'
services:
  excalidraw:
    image: excalidraw/excalidraw:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - excalidraw_data:/data
      - excalidraw_config:/config
    environment:
      - TZ=UTC
      - PUID=1000
      - PGID=1000
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=excalidraw
      - POSTGRES_USER=excalidraw
      - POSTGRES_PASSWORD=changeme

volumes:
  excalidraw_data:
  excalidraw_config:
  db_data:

The configuration above sets the recommended values for a VPS with 2-4GB of RAM. Adjust the memory-related settings proportionally if your server has different specifications.

Initial Configuration

When scaling this setup, consider vertical scaling (adding more RAM/CPU) first, as it's simpler to implement. Horizontal scaling adds complexity but may be necessary for high-traffic applications.

# Reverse proxy configuration
server {
    listen 443 ssl http2;
    server_name excalidraw.example.com;

    ssl_certificate /etc/letsencrypt/live/excalidraw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/excalidraw.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
        proxy_buffering off;
        client_max_body_size 0;
    }
}

Make sure to restart the service after applying these changes. Some settings require a full restart rather than a reload to take effect.

Reverse Proxy Integration

It's recommended to test this configuration in a staging environment before deploying to production. This helps identify potential compatibility issues and allows you to benchmark performance differences.

# docker-compose.yml
version: '3.8'
services:
  excalidraw:
    image: excalidraw/excalidraw:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - excalidraw_data:/data
      - excalidraw_config:/config
    environment:
      - TZ=UTC
      - PUID=1000
      - PGID=1000
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=excalidraw
      - POSTGRES_USER=excalidraw
      - POSTGRES_PASSWORD=changeme

volumes:
  excalidraw_data:
  excalidraw_config:
  db_data:

Make sure to restart the service after applying these changes. Some settings require a full restart rather than a reload to take effect.

Data Persistence

Before making changes to the configuration, always create a backup of the existing files. This ensures you can quickly roll back if something goes wrong during the setup process.

# Reverse proxy configuration
server {
    listen 443 ssl http2;
    server_name excalidraw.example.com;

    ssl_certificate /etc/letsencrypt/live/excalidraw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/excalidraw.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
        proxy_buffering off;
        client_max_body_size 0;
    }
}

The output should show the service running without errors. If you see any warning messages, address them before proceeding to the next step.

Security Implications

For production deployments, consider implementing high availability by running multiple instances behind a load balancer. This approach provides both redundancy and improved performance under heavy load.

Common Issues and Solutions

• Connection timeout: Verify your firewall rules allow traffic on the required ports. Use ss -tlnp to confirm the service is listening on the expected port.
• High memory usage: Review the configuration for memory-related settings. Reduce worker counts or buffer sizes if running on a low-RAM VPS.
• Slow performance: Check for disk I/O bottlenecks with iostat -x 1 and network issues with mtr. Review application logs for slow queries or requests.

Wrapping Up

Following this guide, your excalidraw setup should be production-ready. Keep an eye on resource usage as your traffic grows and don't forget to test your backup and recovery procedures periodically.