Braggo: documentação de deploy¶

Esta documentação descreve como o Braggo roda em produção: uma VM com Ubuntu Server (VMware) no PC de casa, com API .NET 10, frontend Angular e PostgreSQL, publicado na internet por um túnel Cloudflare.

Como as peças se encaixam¶

Internet
   │  https://braggo.com.br
   ▼
Cloudflare (DNS + HTTPS)
   │  túnel (conexão de SAÍDA aberta pela VM, sem abrir portas no roteador)
   ▼
┌────────────────── VM Ubuntu Server (VMware) ───────────────────┐
│                                                                 │
│  cloudflared ──► Nginx :80 ──┬─ /      → /var/www/braggo        │
│                              │          (arquivos do Angular)   │
│                              └─ /api/  → 127.0.0.1:5000         │
│                                          (API .NET, systemd)    │
│                                              │                  │
│                                   PostgreSQL :5432 (só local)   │
└─────────────────────────────────────────────────────────────────┘

Pontos importantes dessa arquitetura:

A internet de casa está atrás de CGNAT, então não dá para abrir portas no roteador. O túnel resolve isso: é a própria VM que liga para a Cloudflare.
O Nginx é a única porta de entrada. Ele entrega o Angular e repassa /api/ para a API.
A API escuta só em 127.0.0.1, e o PostgreSQL também. Nenhum dos dois fica acessível de fora da VM.
O front e a API respondem no mesmo domínio, então não há problema de CORS.

Valores usados na documentação¶

Todos os comandos usam os nomes abaixo. Os marcados com ajustar são suposições: confira com o seu projeto e troque se for diferente.

Item	Valor
Hostname da VM	`servidor`
Usuário Linux	`jhon`
Alias SSH no seu PC	`servidor`	configurado em Servidor base
Pasta da API	`/opt/braggo/api`
Pasta do frontend	`/var/www/braggo`
Serviço da API (systemd)	`braggo-api`
Usuário do serviço	`braggo`	usuário de sistema, sem login
Banco	`braggo_db`
Usuário do banco	`jhon`	nesta instalação (o plano original usava `braggo_user`)
Arquivo de segredos	`/etc/braggo-api.env`	nesta instalação (o plano original usava `/etc/braggo/api.env`)
Porta interna da API	`5000`	ajustar
DLL principal da API	`Braggo.Api.dll`	ajustar (nome gerado pelo `dotnet publish`)
Nome da connection string	`DefaultConnection`	ajustar
Prefixo das rotas da API	`/api`	ajustar
Pasta do build Angular	`dist/NOME/browser`	ajustar (`NOME` é o do `angular.json`)
Domínio	`braggo.com.br`

Confira sempre o que realmente roda

Onde esta documentação e a VM divergirem, vale a VM. Para ver a configuração real do serviço: sudo systemctl cat braggo-api.

Onde está cada coisa na VM¶

O quê	Onde
API publicada	`/opt/braggo/api`
Scripts de deploy	`/opt/braggo/scripts`
Arquivos do Angular	`/var/www/braggo`
Segredos da API	`/etc/braggo-api.env`
Serviço da API	`/etc/systemd/system/braggo-api.service`
Site no Nginx	`/etc/nginx/sites-available/braggo`
Script de backup	`/usr/local/bin/backup-braggo.sh`
Agendamento do backup	`/etc/cron.d/braggo-backup`
Backups	`/var/backups/braggo`
Log do backup	`/var/log/braggo-backup.log`
Logs da API	`sudo journalctl -u braggo-api`
Logs do Nginx	`/var/log/nginx/`

Ordem do primeiro deploy¶

Siga nesta ordem, porque cada etapa depende da anterior:

Servidor base: rede, SSH, firewall, pastas e usuário do serviço.
Banco de dados: PostgreSQL, usuário, banco e migrations.
Deploy da API: runtime .NET, variáveis, serviço systemd.
Frontend e Nginx: build do Angular, arquivos e proxy reverso.
Acesso externo: domínio na Cloudflare e túnel.

Depois que tudo estiver no ar, o dia a dia fica em Rotina de atualização, e quando algo quebrar, em Problemas comuns.

Páginas de operação e referência¶

Página	Para quê
Backup do banco	como o backup roda, como restaurar e testar
Configuração e segredos	onde fica cada variável e como trocar um segredo
E-mail (Resend)	domínio, DNS e remetente dos e-mails
Acesso administrativo	Hangfire, Swagger e banco por túnel SSH
Linux no dia a dia	comandos explicados, para estudar
Estado e histórico	o que falta fazer, decisões e incidentes

Convenções desta documentação¶

Comandos em bash rodam na VM (via SSH).
Comandos em powershell rodam no seu PC Windows.
sudo aparece sempre que o comando precisa de privilégio de administrador. Ele pede a senha do usuário jhon.