Como instalar o Penpot em uma VPS

Pré-requisitos

Prepare uma instalação Ubuntu 22.04 ou 24.04 com SSH, IP público e um domínio como design.example.com. O Penpot é um aplicativo com vários serviços, então consulte as recomendações oficiais atuais de recursos em vez de presumir que uma VPS minúscula será suficiente para uma equipe. Reserve espaço em disco para os arquivos enviados e o crescimento do banco de dados.

Você precisa do Docker Compose, de um destino para backups e de um plano para os convites de usuários. Se a VPS já executar outra estrutura web, isole o Penpot ou confirme que o proxy existente consegue encaminhar as solicitações com segurança.

Etapa 1, conectando-se ao servidor

Atualize o servidor e crie um diretório de trabalho privado:

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

Permita SSH, HTTP e HTTPS no firewall do provedor. Não abra as portas do banco de dados, do cache ou da API interna para a rede pública.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu:

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

Confira o espaço em disco disponível antes de baixar todo o conjunto de serviços do Penpot. Fixe a versão da implantação depois de testá-la, em vez de usar tags flutuantes indefinidamente.

Etapa 3, executando a implantação do Penpot mantida oficialmente

O Penpot publica os arquivos Compose oficiais para auto-hospedagem na documentação e no repositório de código-fonte. Baixe os arquivos da versão atual para /opt/penpot e leia o exemplo de ambiente fornecido antes de editá-lo. A versão pode adicionar ou renomear serviços, então use o conjunto completo fornecido em vez de montar uma interface e um banco de dados improvisados.

Defina os valores do ambiente substituindo os marcadores de posição:

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

Mantenha os nomes exatos das variáveis exigidas pela versão baixada. Não reutilize os segredos de exemplo nem envie .env para o controle de versão. Fixe PENPOT_VERSION em uma versão específica (por exemplo, 2.4.3) em vez de usar sempre latest.

Valide e inicie o projeto Compose fornecido:

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

Acompanhe os logs do serviço de back-end e do exportador durante a primeira migração. Se os arquivos oficiais exigirem um comando de configuração separado, execute-o antes de criar projetos.

Etapa 4, configurando o proxy reverso

Encaminhe design.example.com para a porta privada do serviço público do Penpot indicada no arquivo Compose fornecido. Deixe o Caddy ou o Nginx encerrar o HTTPS e preservar os cabeçalhos encaminhados. Configure o limite de tamanho dos uploads e os tempos limite das solicitações de acordo com os arquivos e o tamanho dos recursos de design.

O proxy reverso precisa oferecer suporte a atualizações WebSocket para dois endpoints: /ws/notifications e /mcp/ws. Sem isso, a colaboração em tempo real deixa de funcionar sem aviso. Adicione o seguinte aos blocos de localização do Nginx ou o equivalente em outros proxies:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

Defina também client_max_body_size 367001600; na configuração do Nginx, pois o Penpot recebe arquivos de design grandes.

Mantenha as portas do banco de dados, do exportador e da API interna nas redes do Docker. Teste a conexão WebSocket ou a colaboração ao vivo por HTTPS, pois uma página que carrega sem atualizações em tempo real não representa uma instalação completa.

Etapa 5, primeiro acesso e configuração inicial

Acesse https://design.example.com e crie a primeira conta ou organização. Convide uma pessoa de teste, crie um arquivo pequeno e envie um recurso. Confirme que a colaboração, os comentários, as exportações e o recarregamento das páginas funcionam após reiniciar o conjunto de serviços.

Configure o SMTP somente depois de consultar as configurações atuais. Use uma identidade de remetente dedicada e mantenha as credenciais no ambiente ou em um gerenciador de segredos. Defina as permissões dos usuários antes de importar designs confidenciais.

Manutenção

Faça backup dos dois volumes Docker, dos dados do Postgres e dos arquivos dos usuários. Não use docker cp nas pastas dos volumes. Em vez disso, use docker run --rm -v penpot-postgres:/v alpine tar czf /backup/penpot-pg.tar.gz /v. Teste a restauração em outro servidor e confirme que um projeto abre com seus arquivos. Atualize o conjunto oficial de serviços em uma janela de manutenção após consultar as notas de migração. Se estiver atualizando do Penpot 1.x para o 2.x, é necessária uma etapa manual de migração, consulte o guia oficial de migração.

Monitore o disco, as conexões do banco de dados, as falhas do exportador, a memória e os erros do proxy. Se a colaboração parar de funcionar, confira o tratamento de WebSocket no proxy e os logs do serviço de back-end antes de alterar o banco de dados.