Cómo instalar Penpot en un VPS

Requisitos previos

Prepara Ubuntu 22.04 o 24.04 con SSH, IP pública y un dominio como design.example.com. Penpot es una aplicación de varios servicios, así que usa los requisitos actuales en lugar de asumir que un VPS pequeño bastará para un equipo. Reserva disco para assets y crecimiento de la base.

Necesitas Docker Compose, un destino de backup y una política de invitaciones. Si el VPS ya aloja otro stack web, aísla Penpot o verifica que el proxy existente pueda dirigirlo con seguridad.

Paso 1, Conectarte a tu servidor

Actualiza el host y crea una carpeta privada:

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

Permite SSH, HTTP y HTTPS en el firewall. No abras a internet los puertos de base, cache o APIs internas.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y Compose con las instrucciones oficiales para Ubuntu:

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

Comprueba el disco antes de descargar el stack completo. Fija la versión después de probar, en lugar de dejar tags flotantes para siempre.

Paso 3, Ejecutar el despliegue mantenido de Penpot

Penpot publica los archivos Compose oficiales de self-hosting en su documentación y repositorio. Descarga los archivos del release actual en /opt/penpot y lee el ejemplo de entorno antes de editarlo. La versión puede añadir o renombrar servicios, por lo que debes usar el stack completo y no unir un frontend y una base por tu cuenta.

Crea los valores de entorno sustituyendo los placeholders:

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

Conserva los nombres exactos del release descargado. No reutilices secretos de ejemplo ni subas .env. Fija PENPOT_VERSION a un release concreto (ej. 2.4.3) en lugar de flotar en latest.

Valida y arranca el Compose suministrado:

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

Revisa los logs de backend y exporter durante la primera migración. Si los archivos oficiales requieren otro comando de setup, ejecútalo antes de crear proyectos.

Paso 4, Configurar el proxy inverso

Dirige design.example.com al servicio público de Penpot en el puerto privado indicado por el Compose. Termina HTTPS con Caddy o Nginx y conserva las cabeceras reenviadas. Ajusta tamaño de upload y timeouts al tamaño de tus assets.

El proxy inverso debe soportar upgrades WebSocket en dos endpoints: /ws/notifications y /mcp/ws. Sin ellos, la colaboración en tiempo real falla silenciosamente. Añade lo siguiente a tus bloques location de nginx o su equivalente en otros proxies:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

También define client_max_body_size 367001600; en la configuración de nginx — Penpot sube assets de diseño grandes.

Mantén base, exporter y API interna en redes Docker. Prueba websocket o colaboración en tiempo real por HTTPS, porque cargar la página sin actualizaciones realtime no significa que la instalación esté completa.

Paso 5, Primer acceso y configuración inicial

Abre https://design.example.com y crea la primera cuenta u organización. Invita a un usuario de prueba, crea un archivo pequeño y sube un asset. Comprueba colaboración, comentarios, exports y recargas después de reiniciar el stack.

Configura SMTP solo tras leer los ajustes actuales. Usa una identidad de envío dedicada y guarda credenciales en el entorno o un secret manager. Define permisos antes de importar diseños confidenciales.

Mantenimiento

Haz backup de los dos volúmenes Docker — datos de Postgres y assets de usuario. No uses docker cp sobre carpetas de volúmenes — usa docker run --rm -v penpot-postgres:/v alpine tar czf /backup/penpot-pg.tar.gz /v en su lugar. Prueba una restauración en otro host y confirma que los proyectos abren sus archivos. Actualiza el stack oficial en una ventana de mantenimiento después de leer las migraciones. Si actualizas de Penpot 1.x a 2.x, necesitas un paso de migración manual — consulta la guía oficial de migración.

Monitoriza disco, conexiones, fallos del exporter, memoria y errores del proxy. Si falla la colaboración, revisa primero websockets y logs de backend antes de tocar la base.