Diagrama
Arquitetura
Da aplicação ao deployment em Kubernetes
A plataforma transforma um repositório privado com Dockerfile e workflow de deploy numa aplicação publicada no domínio institucional, com imagem Docker em GHCR, Helm chart central, secrets, PostgreSQL, migrations e backups automáticos.
Fluxo técnico
Como os componentes trabalham em conjunto
O objetivo da arquitetura é retirar complexidade dos repositórios das aplicações. Cada app mantém apenas a configuração mínima de deploy, enquanto o comportamento comum fica concentrado no workflow reutilizável e no chart Helm do platform-orchestrator.
Repositório da aplicação
O aluno ou professor mantém o código num repositório privado da organização, com Dockerfile, workflow de deploy e, quando necessário, secrets no GitHub.
Workflow central de deploy
O GitHub Actions chama o workflow reutilizável do platform-orchestrator, prepara APP_NAME e APP_HOST, constrói a imagem Docker e configura o acesso ao cluster.
Registo de imagens e chart
A imagem é publicada no GitHub Container Registry e o Helm chart central é usado como ponto único para criar ou atualizar os recursos Kubernetes da aplicação.
Cluster Kubernetes
No namespace apps são criados Deployment, Service, Ingress, secrets, PVC opcional e jobs de migrations. O namespace databases centraliza o PostgreSQL da plataforma.
Base de dados e backups
Quando a app precisa de base de dados, o workflow cria credenciais próprias e associa a aplicação ao PostgreSQL. Um CronJob executa backups periódicos para Cloudflare R2.
Consumo e acesso
A aplicação fica disponível através de uma URL pública no domínio institucional. O acesso técnico à base de dados é mantido separado e usado apenas quando necessário.
Separação de responsabilidades
O que cada camada resolve
- Aplicação: contém o código, Dockerfile e workflow simples.
- platform-orchestrator: concentra o workflow reutilizável e o Helm chart.
- Cluster K3s: executa aplicações, serviços, ingresses, jobs e secrets.
- PostgreSQL: fornece bases de dados isoladas por aplicação quando necessário.
- Cloudflare R2: recebe backups automáticos produzidos pelo CronJob.
Decisão de desenho
Automação sem intervenção manual na VM
A VM mantém o cluster e os componentes base, mas o deploy normal de novas aplicações acontece por GitHub Actions e Helm. Esta abordagem torna o processo repetível, reduz erros manuais e permite que novas aplicações sejam publicadas com a mesma estrutura técnica.