Guia de Deploy

Como publicar uma aplicação na infraestrutura

Guia prático para preparar o repositório, criar a imagem Docker e publicar uma aplicação através de GitHub Actions, GHCR, Kubernetes, Helm, secrets, PostgreSQL e migrations.

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.

GitHub → GitHub Actions → Docker build → GHCR → Helm → Kubernetes → URL pública

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.

1Repositório privado na deisi-org
2Branch principal main
3Dockerfile funcional
4Porta interna conhecida
minha-app/ |-- .github/workflows/deploy.yml |-- Dockerfile `-- codigo-da-aplicacao/

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:

name: Deploy on: push: branches: [main] permissions: contents: read packages: write jobs: deploy: uses: deisi-org/platform-orchestrator/.github/workflows/deploy.yml@main with: app_port: "3000" secrets: inherit

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 / Python8000Depende do gunicorn, uvicorn ou comando usado.
Flask5000 ou 8000Pode mudar se a app definir outra porta.
FastAPI8000Normalmente com uvicorn.
Node.js / Express3000Porta comum em apps Node.
React / Vite3000 ou 8080 quando servido por Nginx.
Spring Boot8080Porta 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.

SECRET_KEY=valor-secreto DEBUG=false API_TOKEN=token-privado

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.

with: app_port: "8000" database_enabled: true

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.

DATABASE_URL DB_HOST DB_PORT DB_NAME DB_USER DB_PASSWORD

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.

with: app_port: "8000" database_enabled: true migrations_command: "python manage.py migrate --noinput"

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.

# App simples with: app_port: "3000" # App com BD e migrations with: app_port: "8000" database_enabled: true migrations_command: "python manage.py migrate --noinput"

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.

git add . git commit -m "Add deploy workflow" git push

12. Problemas comuns

  • Porta errada em app_port.
  • A aplicação escuta em localhost em vez de 0.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.0 e 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.
Resumo: preparar repositório, Dockerfile e workflow; configurar porta, secrets, base de dados e migrations quando necessário; fazer push; validar a Action; abrir o URL público.