Este documento estabelece o padrão operacional, diretrizes de segurança, rotinas de deploy contínuo, backup, restore e troubleshooting para o ambiente de produção do sistema institucional UniFAP Estoque & Multimídia.
| Serviço | Porta Interna | Exposição no Host | Finalidade |
| :— | :— | :— | :— |
| PostgreSQL + pgvector | 5432 | 127.0.0.1:5432 (Loopback) | Banco de dados relacional e vetorial |
| Biometric API (FastAPI) | 8000 | 127.0.0.1:8000 (Loopback) | Extração e inferência facial dlib |
| App Web (Next.js) | 3000 | 127.0.0.1:3000 (Loopback) | Aplicação web principal |
| Cloudflared Tunnel | — | Saída HTTPS 443 | Túnel seguro para tráfego externo |
[!IMPORTANT] Nenhuma porta dos containers deve ser exposta diretamente para
0.0.0.0. Todo o tráfego de entrada público passa obrigatoriamente pela rede protegida da Cloudflare via Cloudflare Tunnel.
As variáveis de produção devem ser injetadas exclusivamente através do gerenciador de variáveis do Coolify ou arquivo .env protegido com permissão chmod 600 .env no servidor. Nunca versione credenciais reais no Git.
| Variável | Exemplo / Descrição | Obrigatório |
|---|---|---|
NODE_ENV |
production |
Sim |
DATABASE_URL |
postgresql://postgres:<SENHA_SEGURA>@postgres:5432/estoque_multimidia |
Sim |
POSTGRES_USER |
postgres |
Sim |
POSTGRES_PASSWORD |
<HASH_ALFANUMERICO_32_CHARS> |
Sim |
POSTGRES_DB |
estoque_multimidia |
Sim |
NEXTAUTH_URL |
https://estoque.unifapce.edu.br |
Sim |
NEXTAUTH_SECRET |
<CHAVE_BASE64_64_BYTES> (gerada via openssl rand -base64 64) |
Sim |
BIOMETRIC_INTERNAL_TOKEN |
<CHAVE_BASE64_32_BYTES> para autenticação mútua interna |
Sim |
CLOUDFLARE_TUNNEL_TOKEN |
Token do Cloudflare Zero Trust Tunnel | Sim |
FACE_DISTANCE_THRESHOLD |
0.60 (limiar de distância euclidiana da biometria) |
Não (default: 0.60) |
MIN_CONFIDENCE_THRESHOLD |
0.80 (confiança mínima de reconhecimento) |
Não (default: 0.80) |
O Coolify funciona como o seu próprio “Vercel / Heroku” auto-hospedado no PC do trabalho (24/7), automatizando compilações e deploys a cada git push.
Execute no terminal da máquina:
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
wsl --install -d Ubuntu
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
(O Coolify iniciará seus containers e abrirá o painel web em http://localhost:8000 ou http://<IP-DO-SERVIDOR>:8000).
http://localhost:8000 e cadastre suas credenciais de Administrador.RivaldoMascarenhas/EstoqueMultimidia e o branch main..env (ex: POSTGRES_PASSWORD, NEXTAUTH_SECRET, BIOMETRIC_INTERNAL_TOKEN, CLOUDFLARE_TUNNEL_TOKEN, NEXTAUTH_URL=https://multimidia.rivaldo.uk).main.1. Você programa no computador de desenvolvimento (casa)
2. git add . && git commit -m "feat: nova funcionalidade" && git push origin main
3. GitHub aciona o Webhook do Coolify no PC do trabalho
4. Coolify faz git pull, compila as imagens Docker e roda o init-db
5. O Cloudflare Tunnel roteia o tráfego com zero downtime para https://multimidia.rivaldo.uk
Em caso de necessidade de reversão imediata:
# Checkout para o commit anterior desejado
git checkout <COMMIT_HASH_ANTERIOR>
# Rebuild e reinício dos containers
docker compose down
docker compose up -d --build
O script scripts/backup.sh executa o dump comprimido do PostgreSQL com pgvector e gerencia a retenção automática de 14 dias.
# Adicionar no crontab do host (crontab -e)
0 3 * * * /bin/bash /opt/unifap-estoque/scripts/backup.sh >> /var/log/unifap_backup.log 2>&1
Para restaurar um backup existente em caso de falha ou desastre:
# 1. Localizar o arquivo de backup desejado
ls -lh /backups/unifap_estoque_backup_*.sql.gz
# 2. Descompactar e restaurar no container PostgreSQL
gunzip -c /backups/unifap_estoque_backup_YYYYMMDD_HHMMSS.sql.gz | \
docker exec -i unifap-postgres psql -U postgres -d estoque_multimidia
# 3. Validar a integridade das tabelas e índices
docker exec -i unifap-postgres psql -U postgres -d estoque_multimidia -c "SELECT count(*) FROM \"User\";"
docker exec -i unifap-postgres psql -U postgres -d estoque_multimidia -c "SELECT count(*) FROM \"Event\";"
O sistema possui rotas de monitoramento de saúde ativas:
GET /api/v1/health/live
HTTP 200 confirmando que o processo Node.js está ativo e respondendo a requisições.GET /api/v1/health/ready
SELECT 1) e a saúde do serviço biométrico.Comandos úteis para monitoramento em tempo real:
# Visualizar logs da aplicação web
docker logs -f unifap-web-app --tail 100
# Visualizar logs da API biométrica
docker logs -f unifap-biometric-api --tail 100
# Visualizar logs do banco de dados
docker logs -f unifap-postgres --tail 100
# Visualizar consumo de CPU e Memória
docker stats
O container cloudflared estabelece uma conexão criptografada de saída para a rede Anycast da Cloudflare.
one.dash.cloudflare.com):
unifap-estoque-prod.CLOUDFLARE_TUNNEL_TOKEN no Coolify.estoqueunifapce.edu.brHTTP para app:3000 (ou http://127.0.0.1:3000).Definidos em docker-compose.yml:
app (Next.js): 2.0 CPUs, 2.0 GB RAM.biometric-api (FastAPI + dlib): 2.0 CPUs, 2.0 GB RAM.postgres (pgvector): 2.0 CPUs, 1.5 GB RAM.cloudflared: 0.5 CPUs, 256 MB RAM.Durante o processo de inicialização de uma nova versão em produção, execute as migrações automáticas:
docker exec -it unifap-web-app npx prisma migrate deploy
Ao rotacionar credenciais:
NEXTAUTH_SECRET:
openssl rand -base64 64app (docker compose restart app). As sessões ativas serão invalidadas e exigirão novo login.BIOMETRIC_INTERNAL_TOKEN:
app e no container biometric-api.docker ps -a | grep postgres.docker exec -it unifap-postgres pg_isready -U postgres.docker logs unifap-postgres.curl http://127.0.0.1:8000/api/v1/health/live.BIOMETRIC_INTERNAL_TOKEN é idêntico no app e biometric-api.SELECT count(*) FROM "FaceEmbedding" WHERE active = true;.docker exec -it unifap-web-app rm -rf .next/cache.docker compose restart app.