How to install Penpot on a VPS

Prerequisites

Prepare Ubuntu 22.04 or 24.04 with SSH, a public IP and a domain such as design.example.com. Penpot is a multi-service application, so use the current official resource guidance rather than assuming that a tiny VPS will be enough for a team. Reserve disk for uploaded assets and database growth.

You need Docker Compose, a backup destination and a plan for user invitations. If the VPS already runs another web stack, isolate Penpot or confirm that the existing proxy can route it safely.

Step 1, Connecting to your server

Update the host and create a private working directory:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/penpot
cd /opt/penpot
chmod 750 /opt/penpot

Allow SSH, HTTP and HTTPS in the provider firewall. Do not open database, cache or internal API ports to the public network.

Step 2, Installing Docker and Docker Compose

Install Docker Engine and the Compose plugin from Docker's official Ubuntu instructions:

docker --version
docker compose version
systemctl enable --now docker

Check the available disk before pulling the full Penpot stack. Pin the deployment version after testing instead of using floating tags forever.

Step 3, Running the maintained Penpot deployment

Penpot publishes the official self-hosted Compose files in its documentation and source repository. Download the files for the current release into /opt/penpot, then read the supplied environment example before editing it. The release can add or rename services, so use its complete stack rather than composing an ad hoc frontend and database.

Create the environment values with placeholders replaced:

PENPOT_VERSION=2.4.3
PENPOT_PUBLIC_URI=https://design.example.com
PENPOT_SECRET_KEY=REPLACE_WITH_A_LONG_RANDOM_VALUE
PENPOT_DATABASE_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE
PENPOT_STORAGE_SECRET=REPLACE_WITH_A_RANDOM_VALUE

Keep the exact variable names required by the downloaded release. Do not reuse sample secrets or commit .env. Pin PENPOT_VERSION to a specific release (e.g., 2.4.3) instead of floating on latest.

Validate and start the supplied Compose project:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Watch the backend and exporter logs during the first migration. If the official files require a separate setup command, run that command before creating projects.

Step 4, Configuring the reverse proxy

Route design.example.com to the public Penpot service's private port from the supplied Compose file. Let Caddy or Nginx terminate HTTPS and preserve forwarded headers. Configure upload size and request timeouts according to the file and the size of design assets.

The reverse proxy must support WebSocket upgrades for two endpoints: /ws/notifications and /mcp/ws. Without these, real-time collaboration silently breaks. Add the following to your nginx location blocks or their equivalent in other proxies:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

Also set client_max_body_size 367001600; in the nginx config — Penpot uploads large design assets.

Keep the database, exporter and internal API ports on Docker networks. Test the websocket or live collaboration connection through HTTPS, because a page that loads without realtime updates is not a complete installation.

Step 5, First access and initial setup

Open https://design.example.com and create the first account or organization. Invite a test user, create a small file and upload an asset. Verify that collaboration, comments, exports and page reloads work after restarting the stack.

Configure SMTP only after reading the current settings. Use a dedicated sender identity and keep the credentials in the environment or secret manager. Set user permissions before importing confidential designs.

Maintenance

Back up both Docker volumes — Postgres data and user assets. Do not use docker cp on volume folders — use docker run --rm -v penpot-postgres:/v alpine tar czf /backup/penpot-pg.tar.gz /v instead. Test a restore on a separate host and verify that a project opens with its assets. Update the official stack in a maintenance window after checking migration notes. If upgrading from Penpot 1.x to 2.x, a manual migration step is required — consult the official migration guide.

Monitor disk, database connections, exporter failures, memory and proxy errors. If collaboration breaks, inspect proxy websocket handling and backend logs before changing the database.