Cómo elegir Penpot autohospedado: Docker, colaboración y entrega a desarrollo en una herramienta de diseño open source

Penpot es una plataforma de código abierto diseñada para el diseño de productos y la colaboración de código. El autoalojado no es una herramienta de dibujo de contenedor único: el Compose oficial ejecuta simultáneamente frontend, backend, Exporter, MCP, Postgres, Valkey y otros servicios, y almacena la base de datos y los materiales subidos en volúmenes persistentes. Por lo tanto, tras el despliegue, la salud del contenedor, el acceso a HTTP, las políticas de registro, los volúmenes persistentes y los procesos de recuperación deben verificarse simultáneamente.

Dirección del proyecto:

https://github.com/penpot/penpot

Página web oficial:

https://penpot.app

Conclusión rápida

Las pruebas personales pueden acceder directamente al SaaS de Penpot; El autoalojamiento es necesario para el control de datos, el despliegue de la intranet o los límites de cumplimiento.
El método oficial con Docker requiere Compose V2 y escucha en http://localhost:9001 de forma predeterminada.
El Compose de muestra descargado es para prueba local y debe ser reemplazado antes del despliegue público en redPENPOT_SECRET_KEY, URI pública, correo electrónico y configuración de cookies de seguridad.
Las copias de seguridad no pueden guardarse solasdocker-compose.yaml, y también cubren Postgres conpenpot_assetsTirada de resistencia.

Descarga el Compose oficial y verifica primero

1
2
3
4
5
6
7


docker --version
docker compose version
mkdir penpot-selfhost
cd penpot-selfhost
curl -o docker-compose.yaml https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml
docker compose -p penpot -f docker-compose.yaml config --services
docker compose -p penpot -f docker-compose.yaml config --volumes

config debe terminar con código cero. La lista debe incluir frontend, backend, base de datos y servicios auxiliares; los volúmenes deben incluir los datos de Postgres y los recursos. Si falla el análisis YAML, no continúes con up -d.

Conserva el archivo original antes de modificarlo para facilitar la recuperación:

1

cp docker-compose.yaml docker-compose.yaml.original

Modifica la configuración de seguridad antes de publicar

El ejemplo oficial advierte que un despliegue público no debe conservar disable-secure-session-cookies ni disable-email-verification. Sustituye también estos valores provisionales:

PENPOT_PUBLIC_URI: Cambiar al dominio HTTPS final.
PENPOT_SECRET_KEY: no dejes el valor change-this-insecure-key.
PENPOT_FLAGS: Decidir si permitir el registro, verificar los correos electrónicos y activar MCP.
SMTP: En entornos formales, no trates Mailcatch como un servicio de correo electrónico real.

Genera secretos aleatorios usando Python:

1

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

Corre otra vezdocker compose ... config, confirma que la variable aún puede analizarse tras el reemplazo. No envíes archivos Compose que contienen Secret a repositorios públicos.

Inicia y valida cada servicio

1
2
3
4


docker compose -p penpot -f docker-compose.yaml up -d
docker compose -p penpot -f docker-compose.yaml ps
docker compose -p penpot -f docker-compose.yaml logs --tail 100 penpot-backend
curl -I http://localhost:9001

La aceptación no puede basarse únicamente en el retorno inicial 200.docker compose psNo debe haber servicios que se reinicien o salgan continuamente, y los registros del backend no deben mostrar repetidamente la conexión a la base de datos, migración o errores secretos.

Si la página no puede abrirse, comprueba en orden:

1
2
3
4


docker compose -p penpot -f docker-compose.yaml ps -a
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-frontend
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-backend
docker compose -p penpot -f docker-compose.yaml logs --tail 100 penpot-postgres

Si el frontend es normal pero falla iniciar sesión o guardar, normalmente deberías seguir revisando el backend y Postgres, en lugar de reiniciar el navegador.

Crear la primera cuenta controlada

No se recomienda que las instancias de redes públicas mantengan abierta la inscripción anónima durante mucho tiempo. Tras cerrar el registro, puedes usar el comando de gestión de backend para crear una cuenta. Primero, encuentra el nombre real del contenedor:

1
2


docker compose -p penpot -f docker-compose.yaml ps
docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile

Distintas versiones de Compose pueden usar guiones o guiones bajos en los nombres. Si no se encuentra el contenedor, usa el nombre mostrado por docker compose ps. El comando de gestión también requiere prepl-server en el backend.

Valida el proxy inverso HTTPS

El URI público de Penpot, el nombre de dominio realmente accedido por el navegador y el dominio TLS proxy inverso deben ser consistentes. Después de desplegar el proxy, comprueba desde la red externa:

1

curl -I https://design.example.com

Cuando ocurre un bucle de redirección, primero compruebaPENPOT_PUBLIC_URILas cabeceras del protocolo pasaban con el proxy; Si te desconectas inmediatamente después de iniciar sesión, céntrate en comprobar si hay cookies seguras y HTTPS. No vuelvas a abrir cookies inseguras solo para uso temporal.

Validar la entrega del diseño con un proyecto mínimo

Tras completar el despliegue básico, crea un nuevo equipo de pruebas y documentación para al menos verificar:

Dos cuentas pueden unirse al mismo equipo y ver cambios en tiempo real.
Crear un componente, una variante y al menos un Token de Diseño.
Las cuentas de desarrollo pueden leer información SVG, CSS o de diseño en Modo Inspección.
Exportar uno.penpoty luego importado al espacio de prueba.
Después de subir una imagen, actualiza la página, pero el material permanece accesible.

Estas operaciones cubren simultáneamente colaboración, bases de datos y volúmenes de material. Simplemente crear archivos en blanco no es suficiente para demostrar la disponibilidad de un enlace de datos autoalojado.

Haz copia de la base de datos y del volumen de recursos

El Compose predeterminado usa dos volúmenes clave: los datos de Postgres y penpot_assets. Primero, consulta sus nombres reales:

1
2


docker compose -p penpot -f docker-compose.yaml config --volumes
docker volume ls --filter label=com.docker.compose.project=penpot

Pausando la versión de escritura y grabación antes de hacer la copia de seguridad:

1
2


docker compose -p penpot -f docker-compose.yaml images
docker compose -p penpot -f docker-compose.yaml stop

Luego, sigue el proceso oficial de copia de seguridad de volúmenes Docker para archivar el volumen de la base de datos y el volumen de material por separado. Los archivos de copia de seguridad deben almacenarse en el servidor anfitrión o remoto, no en el contenedor. Tras completar, reinicia y vuelve a comprobar:

1
2
3


docker compose -p penpot -f docker-compose.yaml start
docker compose -p penpot -f docker-compose.yaml ps
curl -I http://localhost:9001

Solo los archivos que realmente han sido restaurados en el entorno aislado se consideran copias de seguridad utilizables. La aceptación de restauración debe abrir el archivo de prueba original, comprobar los componentes y confirmar que la imagen subida sigue existiendo.

Prepara un punto de reversión antes de actualizar

No sobrescribas el archivo Compose y ejecutes pull inmediatamente. Conserva antes la configuración, la información de imágenes y las copias de los volúmenes:

1
2
3
4
5


cp docker-compose.yaml docker-compose.yaml.before-upgrade
docker compose -p penpot -f docker-compose.yaml images
docker compose -p penpot -f docker-compose.yaml pull
docker compose -p penpot -f docker-compose.yaml up -d
docker compose -p penpot -f docker-compose.yaml logs --tail 200 penpot-backend

Las migraciones de versiones principales pueden seguir ejecutándose tras el inicio. En este punto, una página temporalmente inaccesible no significa que debas reiniciar repetidamente; Primero, revisa los registros de migración. Si la nueva versión sigue fallando, el servicio debe detenerse, restaurarse las versiones antiguas de Compose e imagen correspondiente, y luego debe restaurarse la copia de seguridad del volumen previa a la actualización. Después de que la base de datos haya sido migrada, simplemente revertir a la imagen antigua puede no ser seguro.

Colaboración a largo plazo en diseño y desarrollo

Los equipos pueden implementar el proceso de la siguiente manera:

Los diseñadores crean un Sistema de Diseño, con nombres de componentes lo más parecidos posible a la biblioteca de componentes del frontend.
Utiliza Fichas de Diseño para color, tamaño de fuente y espacio, en lugar de valores dispersos rellenos a mano.
Desarrollar información SVG, CSS y de diseño mediante el Modo Inspección.
Utilizar archivos de prueba para validar plugins, APIs o MCPs para evitar operar directamente con activos formales de diseño.
Antes de las actualizaciones de versiones principales, exportar archivos clave y hacer copias de seguridad de los volúmenes persistentes del lado del servidor.

Tabla de diagnóstico de fallos

Fenómeno	Examen clave	Recuperación del movimiento
`localhost:9001`Sin respuesta	Puerto frontal, estado del contenedor, firewall del host	Recrea el contenedor tras restaurar el Compose original
La página puede abrirse pero no puede iniciar sesión	Registros de backend, Secreto, Cookie, URI público	Restauración de la coherencia de la configuración de nombres de dominio y cookies de seguridad
Correos de invitación no recibidos	Indicadores de verificación SMTP y correo electrónico	Arreglar SMTP, no desactivar la autenticación para evitar a largo plazo
Se pueden abrir archivos, pero faltan imágenes	`penpot_assets`Almacenamiento de volumen u objetos	Restaurar una copia de seguridad de materiales en el mismo momento que la base de datos
El backend se reinicia repetidamente tras la actualización	Migración de base de datos y versión de la imagen	Deja de escribir y usa el conjunto completo de copia de seguridad y recuperación antes de la actualización

Los criterios de finalización autoalojada de Penpot son: disponibilidad de dominio HTTPS, límites claros de registro, dos usuarios de prueba colaborando, Modo Inspección entregando estilos, importación y exportación exitosas, y tanto bases de datos como materiales que hayan completado los ejercicios de recuperación. Si falta alguno de estos, no deberías migrar directamente a los únicos archivos formales de diseño del equipo.