Self-Hosting Penpot on Docker VPS: A Secure, Collaborative Architecture and Database Design Solution for Enterprises

Introduction: The Shift Toward Self-Hosted Design Infrastructure

In the modern software development lifecycle, seamless collaboration between system architects, database administrators, and UI/UX designers is paramount. Traditionally, teams have relied on proprietary, cloud-hosted design platforms. However, for enterprise environments managing sensitive infrastructure blueprints, proprietary cloud solutions present significant bottlenecks regarding data sovereignty, compliance, and recurring licensing costs.

Enter Penpot, the pioneering open-source, web-based design and prototyping platform. Built natively on web standards like SVG and Clojure/ClojureScript, Penpot has evolved far beyond a mere UI/UX tool. Today, it serves as an exceptional engine for rendering complex software architecture diagrams, system topologies, and entity-relationship diagrams (ERDs). By deploying Penpot completely on-premises or on a private Virtual Private Server (VPS) via Docker, organizations can unlock desktop-class performance, ensure absolute data privacy, and maintain complete control over their intellectual property.

Why Choose Penpot for Architecture and Database Diagramming?

While dedicated diagramming tools exist, Penpot bridges the gap between raw technical visualization and professional design fidelity. Deploying it locally offers distinct advantages for engineering teams:

Absolute Data Privacy: Your architectural diagrams—which essentially map the vulnerabilities and structure of your entire software ecosystem—never leave your private network.
Figma-like Collaboration, Zero Licensing Friction: Enjoy real-time, multi-user multiplayer editing without worrying about per-seat enterprise subscription fees.
SVG as a First-Class Citizen: Because Penpot renders natively in SVG, your diagrams remain infinitely scalable, lightweight, and easily exportable for technical documentation (e.g., inside internal wikis or Git repositories).
Component Reusability: Create reusable UI components for database tables, microservice nodes, and cloud infrastructure icons (AWS, Azure, GCP) to standardize diagramming across the organization.

---

System Architecture Overview

Before executing the deployment, it is critical to understand how Penpot operates under the hood. A standard self-hosted Penpot stack consists of several microservices orchestrated via Docker Compose:

Penpot Frontend (Nginx): Serves static assets and acts as the initial reverse proxy for client connections.
Penpot Backend (Clojure): Handles core business logic, workspace management, and data processing.
Penpot Exporter: A specialized Node.js service running a headless browser instance responsible for rendering and exporting shapes to PDF, PNG, or SVG.
PostgreSQL Database: The persistent relational storage engine handling users, projects, and canvas states.
Redis Cache: Manages real-time WebSocket sessions, background queues, and pub/sub mechanisms required for live collaboration.

System Requirement Note: For an optimal production environment supporting 10 to 50 concurrent collaborators, we recommend a VPS with at least 4 vCPUs, 8GB of RAM, and fast NVMe SSD storage to handle intense WebSocket traffic and real-time canvas calculations.

---

Step-by-Step Deployment Guide on a Docker VPS

Step 1: Preparing the VPS Environment

Connect to your clean Linux VPS (preferably Ubuntu 24.04 LTS or equivalent) via SSH and update the system package index to guarantee all core dependencies are secure and up to date:

sudo apt update && sudo apt upgrade -y

Next, ensure that the Docker Engine and the Docker Compose plugin are installed on your host system. Verify your installation by checking the respective versions:

docker --version
docker compose version

Step 2: Fetching the Official Penpot Orchestration Configuration

Create a dedicated directory to isolate your Penpot deployment configuration. We will download the official, production-ready Docker Compose manifest directly from Penpot's repository:

mkdir -p /opt/penpot && cd /opt/penpot
curl -o docker-compose.yaml [https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml](https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml)

Step 3: Configuring the Environment Variables

Penpot utilizes environment variables to securely manage secrets, service flags, and SMTP email configurations. Create an .env file in the same directory:

nano .env

Populate the file with the following production-grade configuration blocks, making sure to replace the placeholder strings with securely generated keys:

# Secret keys for session signing (Generate using 'openssl rand -hex 32')
PENPOT_SECRET_KEY=secure_random_hex_string_here

# Database Credentials
PENPOT_DATABASE_URI=postgresql://penpot_db_user:strong_password_here@penpot-postgres/penpot
PENPOT_DATABASE_USERNAME=penpot_db_user
PENPOT_DATABASE_PASSWORD=strong_password_here

# Redis Cache Configuration
PENPOT_REDIS_URI=redis://penpot-redis:6379/0

# Public URI (Replace with your actual domain or VPS static IP)
PENPOT_PUBLIC_URI=[https://penpot.yourcompany.com](https://penpot.yourcompany.com)

# Registration & Security Policies
PENPOT_FLAGS="enable-registration enable-login enable-email-verification"

# SMTP Configuration for User Invitations and Notifications
[email protected]
PENPOT_SMTP_HOST=smtp.mailgun.org
PENPOT_SMTP_PORT=587
PENPOT_SMTP_USERNAME=smtp_username
PENPOT_SMTP_PASSWORD=smtp_password
PENPOT_SMTP_TLS=true

Step 4: Launching the Penpot Microservices

With the environment file properly populated, initialize and pull the official pre-built Docker images from Docker Hub. Run the containers in detached mode:

docker compose up -d

To monitor the initialization process and verify that the database migrations have successfully completed without throwing exceptions, stream the container logs:

docker compose logs -f backend

---

Securing the Deployment via Reverse Proxy and SSL

Exposing raw HTTP ports directly to the public internet introduces significant security vulnerabilities. To safeguard enterprise architectural assets, we must wrap our Penpot installation behind a secure reverse proxy using Nginx and provision an SSL certificate via Let's Encrypt Certbot.

1. Install Nginx and Certbot

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

2. Configure the Nginx Server Block

Create a virtual host configuration file at /etc/nginx/sites-available/penpot:

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

    location / {
        proxy_pass http://localhost:9001;
        proxy_http_version 1.1;
        
        # Critical headers for real-time WebSocket multi-user collaboration
        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;

        # Increase timeouts for large architectural design files upload
        client_max_body_size 100M;
        proxy_read_timeout 600s;
    
    }
}

3. Enable the Configuration and Force SSL

Link the configuration file to the active directory, test the syntax for errors, restart Nginx, and invoke Certbot to handle automatic SSL redirection:

sudo ln -s /etc/nginx/sites-available/penpot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d penpot.yourcompany.com

---

Optimizing Penpot for Technical Diagramming Workflows

Once you navigate to your domain and complete the initial administrator registration, tailor your local workspace specifically for system design workloads:

Import Enterprise Icon Sets: Download official SVG icon packs for AWS, Google Cloud, Azure, and Kubernetes. Import them directly into Penpot's asset library to serve as shared, standardized components.
Establish the Grid System: When mapping out database structures or network layouts, enforce a strict 8px or 16px layout grid in the right-hand panel. This ensures consistent line alignment and clean paths for connections.
Leverage Shared Libraries: Group database schemas into a dedicated team project, publish it as a shared library, and allow multiple cross-functional teams to instantiate existing structural components instantly.

Conclusion: Full Ownership of Your Design Workflow

By hosting Penpot completely local on a Docker VPS, your organization effectively eliminates external dependencies, minimizes data privacy concerns, and cuts down subscription expenses. You gain an elastic, highly collaborative workbench explicitly optimized for designing architecture topologies and relational database layouts. With standard Docker infrastructure underneath, scaling the deployment, running localized backups, and integration into existing enterprise single sign-on (SSO) setups becomes fully manageable by your internal engineering team.