Configuração e segredos

Onde ficam as configurações da API, qual vale mais que qual, e como trocar um segredo sem quebrar nada.

De onde a API lê configuração

O ASP.NET Core junta várias fontes. Quando a mesma chave aparece em mais de uma, a de baixo vence a de cima:

Ordem	Fonte	Onde está	O que tem
1	appsettings.json	/opt/braggo/api/ (vai dentro do build)	valores de desenvolvimento e a estrutura de todas as seções
2	appsettings.Production.json	/opt/braggo/api/	sobrescreve para produção (hoje: a connection string do braggo_db)
3	Variáveis de ambiente	/etc/braggo-api.env, carregado pelo serviço	segredos e valores de produção

Por isso o .env é o lugar certo para segredos: ele não vai no repositório e não é sobrescrito a cada deploy (a pasta /opt/braggo/api é).

Em variável de ambiente, o : do JSON vira __ (dois underscores). Exemplo: Jwt:Key no JSON é Jwt__Key no .env.

O que existe hoje no /etc/braggo-api.env

Veja só os nomes, sem mostrar os valores:

sudo cut -d= -f1 /etc/braggo-api.env

Variável	Para que serve	Efeito de trocar
Resend__ApiKey	chave de envio de e-mail do Resend	e-mails param até a chave nova valer
Resend__From	remetente (Braggo <no-reply@braggo.com.br>)	muda o "de" dos e-mails; o domínio precisa estar verificado no Resend
App__UrlFrontend	endereço base usado nos links de e-mail (https://braggo.com.br)	links de recuperação de senha mudam
Jwt__Key	chave que assina os tokens de login	todo mundo é deslogado e precisa entrar de novo
Setup__Secret	segredo da rota de configuração inicial (confirme no código para que ela serve)	quem usa essa rota precisa do valor novo

O serviço também define ASPNETCORE_ENVIRONMENT=Production direto no arquivo .service (veja com sudo systemctl cat braggo-api).

Outros lugares com configuração

Arquivo	Conteúdo
/opt/braggo/api/appsettings.Production.json	connection string do braggo_db (usuário jhon). Contém a senha do banco em texto: não deixe legível para outros
/etc/systemd/system/braggo-api.service	como a API sobe (usuário, ExecStart, EnvironmentFile)
/etc/nginx/sites-available/braggo	rotas do Nginx
/etc/cron.d/braggo-backup	agendamento do backup
Painel da Cloudflare	token do túnel, DNS, rotas públicas
Painel do Resend	chaves de API, domínio verificado

Como editar o .env com segurança

sudo nano /etc/braggo-api.env
sudo systemctl restart braggo-api
sudo systemctl is-active braggo-api
sudo journalctl -u braggo-api -n 30 --no-pager

A API só lê o arquivo ao iniciar, então toda mudança exige o restart.

Cuidado com tee -a

O comando echo 'X=1' | sudo tee -a arquivo acrescenta uma linha. Se a variável já existir, ficam duas e o systemd usa a última. Para achar duplicadas:

sudo cut -d= -f1 /etc/braggo-api.env | sort | uniq -d

Sem saída = nenhuma duplicada. Para apagar uma linha: sudo sed -i '/^NOME_DA_VARIAVEL=/d' /etc/braggo-api.env.

Permissões esperadas: ls -l /etc/braggo-api.env deve mostrar -rw------- e dono root.

Gerar um segredo forte

openssl rand -base64 48 | tr -d '\n'     # chaves (JWT, Setup)
openssl rand -hex 24                      # senha de banco (só letras e números)

Como trocar cada segredo

Chave do JWT

1. Edite Jwt__Key no .env com um valor novo.
2. sudo systemctl restart braggo-api.
3. Todos os usuários precisam logar de novo. Faça fora de horário de pico.

Chave do Resend

1. No painel do Resend, crie uma chave nova.
2. Troque Resend__ApiKey no .env e reinicie a API.
3. Teste a recuperação de senha. Só então apague a chave antiga no painel.

Senha do banco (dois lugares, os dois precisam bater)

1. sudo -u postgres psql -c "ALTER USER jhon WITH PASSWORD 'NOVA';"
2. Atualize a senha onde a connection string está (appsettings.Production.json ou, melhor, ConnectionStrings__DefaultConnection no .env).
3. sudo systemctl restart braggo-api.

Se só um dos dois for trocado, a API sobe mas falha com password authentication failed.

Token do túnel Cloudflare

No painel (Zero Trust > Networks > Tunnels > braggo), gere um token novo e rode de novo sudo cloudflared service install NOVO_TOKEN.

O que o backup do banco não guarda

O pg_dump guarda só o banco. Se a VM se perder, estes arquivos precisam ter cópia em outro lugar:

• /etc/braggo-api.env
• /opt/braggo/api/appsettings.Production.json
• /etc/systemd/system/braggo-api.service
• /etc/nginx/sites-available/braggo

Para juntar tudo em um arquivo (ele contém segredos: guarde em gerenciador de senhas ou em local criptografado, nunca em repositório):

sudo tar -czf ~/braggo-config-$(date +%F).tar.gz \
  /etc/braggo-api.env \
  /opt/braggo/api/appsettings.Production.json \
  /etc/systemd/system/braggo-api.service \
  /etc/nginx/sites-available/braggo

Depois copie para o seu PC (scp servidor:braggo-config-*.tar.gz .) e apague o arquivo da VM.

Boas práticas

• Segredo nunca em chat, print, repositório ou documentação. Esta documentação guarda nomes, não valores.
• O appsettings.json versionado deve ter só valores de desenvolvimento. Se ele tiver alguma senha de homologação ou chave real, troque essa credencial no serviço de origem e deixe no repositório um valor fictício.
• Para cada segredo, anote onde ele foi criado e quando foi trocado pela última vez.