How to Deploy Penpot - Open-Source Design and Prototyping Platform

Penpot is an open-source design and prototyping platform for designers, developers, and product teams. It runs in the browser, stores files in open web standards such as SVG, and provides a shared workspace where design and code stay in sync. Teams use Penpot for user interface (UI) design, wireframing, interactive prototyping, building reusable design systems, and collaborative design handoff between designers and developers.

This article explains how to deploy Penpot as a self-hosted, open-source design and prototyping platform on a Linux server using Docker Compose with PostgreSQL for data storage, Valkey for websocket notifications, and Traefik as the reverse proxy for TLS termination. It covers the directory and environment setup, the Docker Compose deployment, initial account creation, and a full design-to-prototype workflow inside your own instance.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server (with at least 4 CPU cores and 8 GB of RAM) as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, penpot.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

Penpot separates its runtime into several containers: a frontend, a backend, an exporter, a PostgreSQL database, and a Valkey cache. PostgreSQL and the uploaded assets require persistent storage, while Valkey holds only transient websocket and notification data and needs no persistent volume. Environment variables control the public URL, the master secret key, database credentials, and the feature flags that enable registration and login.

1. Create the project directory and a subdirectory.

   CONSOLE

   Copy

   $ mkdir -p ~/penpot/letsencrypt

   Explain Code

   Powered by Vultr AgentBeta

   The command creates the project directory and one subdirectory:

   • penpot: The directory that holds your .env and docker-compose.yaml files.
   • letsencrypt: Stores SSL/TLS certificates.

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/penpot

   Explain Code

   Powered by Vultr AgentBeta

3. Generate a random secret key for the application.

   CONSOLE

   Copy

   $ python3 -c "import secrets; print(secrets.token_urlsafe(64))"

   Explain Code

   Powered by Vultr AgentBeta

   Copy the output for use in the environment file in the next step.

4. Create the environment file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following configuration. Replace penpot.example.com with your domain name, admin@example.com with your email address, GENERATED_SECRET_KEY with the value from the previous step, and STRONG_DATABASE_PASSWORD with a secure password.

   INI

   Copy

   # Penpot version
   PENPOT_VERSION=2.17.0
   
   # Domain and TLS
   DOMAIN=penpot.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   # Public URI (must match your domain over HTTPS)
   PENPOT_PUBLIC_URI=https://penpot.example.com
   
   # Feature flags
   PENPOT_FLAGS=enable-registration enable-login-with-password disable-email-verification enable-prepl-server
   
   # Master secret key
   PENPOT_SECRET_KEY=GENERATED_SECRET_KEY
   
   # Request body size limits (350 MiB)
   PENPOT_HTTP_SERVER_MAX_BODY_SIZE=367001600
   PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE=367001600
   
   # PostgreSQL configuration
   POSTGRES_DB=penpot
   POSTGRES_USER=penpot
   POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
   PENPOT_DATABASE_URI=postgresql://penpot-postgres/penpot
   PENPOT_DATABASE_USERNAME=penpot
   PENPOT_DATABASE_PASSWORD=STRONG_DATABASE_PASSWORD
   
   # Valkey (Redis-compatible) for websocket notifications
   PENPOT_REDIS_URI=redis://penpot-valkey/0
   
   # Exporter internal connection
   PENPOT_INTERNAL_URI=http://penpot-frontend:8080
   
   # Asset storage
   PENPOT_OBJECTS_STORAGE_BACKEND=fs
   PENPOT_OBJECTS_STORAGE_FS_DIRECTORY=/opt/data/assets
   
   # SMTP configuration (Optional)
   # PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
   # PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
   # PENPOT_SMTP_HOST=smtp.example.com
   # PENPOT_SMTP_PORT=587
   # PENPOT_SMTP_USERNAME=SMTP_USERNAME
   # PENPOT_SMTP_PASSWORD=SMTP_PASSWORD
   # PENPOT_SMTP_TLS=true
   # PENPOT_SMTP_SSL=false

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   The PENPOT_SECRET_KEY is the master key from which Penpot derives other subsystem keys, such as those for HTTP sessions and invitations. The PENPOT_FLAGS variable controls the platform features: the flags above enable self-service registration and password login, disable email verification so you can create the first account without an external mail server, and enable the PREPL server used for command-line administration. Secure session cookies remain enabled by default, which requires the HTTPS access that Traefik provides.

Deploy with Docker Compose

The deployment stack runs Penpot's frontend, backend, and exporter containers alongside PostgreSQL for data persistence, Valkey for websocket notifications, and Traefik as the reverse proxy that terminates TLS and routes the configured domain to the frontend. This configuration is based on the official Penpot Docker Compose setup.

1. Create the Docker Compose file.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.7.9
       container_name: penpot-traefik
       restart: unless-stopped
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "./letsencrypt:/letsencrypt"
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
       networks:
         - penpot
   
     penpot-frontend:
       image: "penpotapp/frontend:${PENPOT_VERSION:-2.17.0}"
       container_name: penpot-frontend
       restart: unless-stopped
       volumes:
         - penpot_assets:/opt/data/assets
       depends_on:
         - penpot-backend
         - penpot-exporter
       networks:
         - penpot
       env_file: .env
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.penpot.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.penpot.entrypoints=websecure"
         - "traefik.http.routers.penpot.tls.certresolver=letsencrypt"
         - "traefik.http.services.penpot.loadbalancer.server.port=8080"
   
     penpot-backend:
       image: "penpotapp/backend:${PENPOT_VERSION:-2.17.0}"
       container_name: penpot-backend
       restart: unless-stopped
       volumes:
         - penpot_assets:/opt/data/assets
       depends_on:
         penpot-postgres:
           condition: service_healthy
         penpot-valkey:
           condition: service_healthy
       networks:
         - penpot
       env_file: .env
   
     penpot-exporter:
       image: "penpotapp/exporter:${PENPOT_VERSION:-2.17.0}"
       container_name: penpot-exporter
       restart: unless-stopped
       depends_on:
         penpot-valkey:
           condition: service_healthy
       networks:
         - penpot
       env_file: .env
   
     penpot-postgres:
       image: postgres:15
       container_name: penpot-postgres
       restart: unless-stopped
       stop_signal: SIGINT
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
         interval: 2s
         timeout: 10s
         retries: 5
         start_period: 2s
       volumes:
         - penpot_postgres:/var/lib/postgresql/data
       networks:
         - penpot
       environment:
         POSTGRES_INITDB_ARGS: "--data-checksums"
         POSTGRES_DB: ${POSTGRES_DB}
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
   
     penpot-valkey:
       image: valkey/valkey:8.1
       container_name: penpot-valkey
       restart: unless-stopped
       healthcheck:
         test: ["CMD-SHELL", "valkey-cli ping | grep PONG"]
         interval: 1s
         timeout: 3s
         retries: 5
         start_period: 3s
       networks:
         - penpot
   
   networks:
     penpot:
   
   volumes:
     penpot_postgres:
     penpot_assets:

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above manifest:

   • traefik: Serves as the reverse proxy and TLS termination point. It listens on ports 80 and 443, redirects HTTP to HTTPS, and provisions Let's Encrypt certificates using the email address defined in LETSENCRYPT_EMAIL.
   • penpot-frontend: Serves the Penpot web interface and static assets on internal port 8080. The Traefik labels route the DOMAIN host to this port over HTTPS.
   • penpot-backend: Runs the application logic, connects to PostgreSQL and Valkey, and shares the penpot_assets volume with the frontend to store uploaded files.
   • penpot-exporter: Renders boards and design files to PNG, SVG, and PDF, and reaches the frontend over the internal Docker network.
   • penpot-postgres: Runs PostgreSQL 15 as the primary database with data checksums and a health check that gates the backend startup.
   • penpot-valkey: Runs Valkey 8.1, a Redis-compatible in-memory store, for websocket notifications and transient state.

3. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that all containers are running.

   CONSOLE

   Copy

   $ docker compose ps -a

   Explain Code

   Powered by Vultr AgentBeta

   The output lists all six containers as Up, with penpot-postgres and penpot-valkey also showing (healthy).

5. View the backend logs to confirm that Penpot started successfully.

   CONSOLE

   Copy

   $ docker compose logs penpot-backend

   Explain Code

   Powered by Vultr AgentBeta

   The output shows the backend applying database migrations and reporting that the HTTP server is listening. Traefik requests the Let's Encrypt certificate on the first HTTPS access, which can take up to a minute to complete.

Access and Configure Penpot

After deployment, access Penpot through your domain, verify the HTTPS certificate, and create the first account. Because email verification is disabled in this configuration, the first account is active immediately after registration.

1. Replace penpot.example.com with your configured domain and open https://penpot.example.com in a web browser.

2. On the login screen, click Create an account.

   

3. Enter your FULL NAME, WORK EMAIL, and a PASSWORD, then click CREATE AN ACCOUNT.

4. Complete the onboarding questions to reach the Penpot dashboard.

   

5. Review the workspace layout. The left sidebar lists your teams and projects, the Drafts area holds files that are not assigned to a project, and the account menu in the upper-right corner opens profile and password settings.

Demonstrate an End-to-End Design Workflow in Penpot

Penpot organizes work into teams, projects, and files. This section demonstrates a complete workflow: creating a team and project, designing a screen with boards and components, linking screens with a prototype interaction, and sharing the result.

Create a Team and Project

1. In the left sidebar, click Your Penpot at the top. From the dropdown, click Create new team.

2. Enter a team name such as Product Design, then click CREATE NEW TEAM.

3. Inside the new team, click + NEW PROJECT at the top right, enter a name such as Mobile App, and press Enter.

Create a Design File

1. Open the project and click + NEW FILE to open the file in the design workspace.

2. Rename the file by double-clicking its name in the top toolbar and entering Login Flow.

Add Boards, Shapes, Text, and Components

1. Select the Board tool (keyboard shortcut B) and choose a preset size such as a Phone from the Size presets in the right panel and then double-click on the board to create a screen.

2. Use the Rectangle tool (R) and the Ellipse tool (E) to draw UI elements such as buttons and input fields on the board.

3. Select the Text tool (T), click the board, and type a label such as Sign in.

4. Style the selected elements using the Design panel on the right to set fill colors, borders, and corner radius.

   

5. To create a reusable component, select one or more elements, right-click the selection, and choose Create component (K). The component appears in the ASSETS tab for reuse across files.

Create a Prototype Interaction

1. Create a second board to act as the destination screen, for example a Home screen.

2. Switch to the PROTOTYPE tab in the upper-right panel.

3. Select the button on the first board. A connection handle appears on the edge of the selection. Drag it to the second board to create a flow.

4. In the INTERACTION settings, set the trigger to On click and the action to Navigate to the destination board.

   

5. Click the Play icon in the upper-right corner to preview the prototype and test the click interaction between screens.

Share the Design

1. Click the Share button in the upper-right corner, enter the Email addresses of people you would like to add as a member to the team, and assign a role such as Editor, Viewer, or Admin.

2. Click SEND INVITATION to confirm collaboration on the shared team.

Conclusion

You have deployed Penpot on a Linux server using Docker Compose and configured data storage, websocket notifications, and TLS termination. Your self-hosted instance provides a full design and prototyping platform, and you validated it by creating a team, designing a screen with boards and components, building a prototype interaction, and sharing the result while keeping complete control of your data. For more information and advanced configuration, see the official Penpot self-hosting documentation.