1. Ideia geral
A plataforma permite colocar uma aplicação online a partir de um repositório GitHub privado.
O utilizador prepara o código, o Dockerfile e um workflow. Depois do push para main,
a pipeline central trata do build, publicação da imagem e deployment no cluster.
2. O que é preciso preparar
A aplicação pode ser backend, frontend, API, monolito ou site estático. A regra principal é: tem de correr dentro de um container Docker e escutar na porta indicada no workflow.
3. Criar o ficheiro de deploy
No repositório da aplicação, cria o ficheiro .github/workflows/deploy.yml.
Para uma aplicação simples, sem base de dados, usa:
4. Escolher a porta correta
O valor de app_port tem de corresponder à porta onde a aplicação escuta dentro
do container. A porta costuma aparecer no Dockerfile ou no comando de arranque.
| Tecnologia | Porta comum | Observação |
|---|---|---|
| Django / Python | 8000 | Depende do gunicorn, uvicorn ou comando usado. |
| Flask | 5000 ou 8000 | Pode mudar se a app definir outra porta. |
| FastAPI | 8000 | Normalmente com uvicorn. |
| Node.js / Express | 3000 | Porta comum em apps Node. |
| React / Vite | 3000 ou 80 | 80 quando servido por Nginx. |
| Spring Boot | 8080 | Porta padrão em muitos projetos Java. |
5. Variáveis de ambiente e secrets
Passwords, tokens, chaves e configurações sensíveis não devem ficar no código. Coloca esses
valores num GitHub Secret chamado APP_RUNTIME_ENV, em formato .env.
6. Aplicações com base de dados PostgreSQL
Se a aplicação precisar de PostgreSQL, adiciona database_enabled: true.
A plataforma cria automaticamente database, user, password e Kubernetes Secret.
7. Como a aplicação usa a base de dados
A aplicação deve ler as credenciais a partir das variáveis de ambiente injetadas no pod.
A opção mais simples para muitas frameworks é usar DATABASE_URL.
8. Migrations da base de dados
Se a aplicação precisa de criar ou atualizar tabelas, define migrations_command.
O comando é executado num Kubernetes Job temporário.
9. Exemplos completos de workflows
Para uma app simples, basta indicar a porta. Para uma app com base de dados, adiciona
database_enabled. Para Django, normalmente também se adiciona migrations_command.
10. Persistência de ficheiros
A plataforma privilegia containers stateless e PostgreSQL para dados persistentes. Se uma app precisar de guardar ficheiros, deve usar a persistência opcional prevista no chart ou um serviço externo adequado.
11. Fazer deploy e acompanhar nas Actions
Depois de criar o Dockerfile e o workflow, faz commit e push para main.
No GitHub, abre Actions e confirma se o workflow Deploy fica verde.
12. Problemas comuns
- Porta errada em
app_port. - A aplicação escuta em
localhostem vez de0.0.0.0. - Dockerfile não arranca a aplicação.
- Secrets colocados no código em vez de GitHub Secrets.
- Migrations não configuradas quando a app precisa de base de dados.
13. Checklist final
- O repositório está na organização deisi-org.
- O repositório está definido como privado.
- A branch principal chama-se
main. - Existe um Dockerfile funcional.
- A aplicação escuta em
0.0.0.0e na porta correta. - Existe o ficheiro
.github/workflows/deploy.yml. - Secrets foram colocados em
APP_RUNTIME_ENV, quando necessário. - Se houver PostgreSQL, foi usado
database_enabled: true. - Se forem necessárias migrations, foi definido
migrations_command. - A Action Deploy ficou verde.
- O URL final abriu no browser.