# Guia de Deploy e Manutenção - NC1

Este guia descreve o processo completo para implantar, atualizar e manter serviços na VPS NC1 utilizando Podman e Quadlet.

## 🚀 Adicionando um Novo Serviço

O **Quadlet** permite declarar containers como serviços `systemd`. Siga estes passos para criar um novo.

### 1. Preparação
Escolha onde o arquivo ficará:
- **Global (Root)**: `/etc/containers/systemd/` (Recomendado para infraestrutura core).
- **Usuário**: `~/.config/containers/systemd/` (Recomendado para aplicações).

### 2. Criar o Arquivo `.container`

Crie um arquivo com sufixo `.container`, por exemplo, `meu-app.container`.

```ini
[Unit]
Description=Meu App Exemplo
After=network-online.target

[Container]
# 1. Imagem Docker
Image=docker.io/minha-empresa/meu-app:latest
AutoUpdate=registry

# 2. Variáveis de Ambiente
Environment=PORT=3000
Environment=DB_HOST=postgres-main

# 3. Persistência (opcional)
Volume=/mnt/data/meu-app:/app:Z
# Explicação:
# - /mnt/data/meu-app : Pasta no Host (Servidor)
# - /app              : Pasta dentro do Container
# - :Z                : Configura permissão SELinux (Essencial no AlmaLinux)

# 4. Rede e Exposição (Traefik)
Network=web_proxy
Label=traefik.enable=true

# Roteamento de Host (URL)
Label=traefik.http.routers.meu-app.rule=Host(`app.rede5.com.br`)
Label=traefik.http.routers.meu-app.entrypoints=websecure
Label=traefik.http.routers.meu-app.tls.certresolver=myresolver

# Porta Interna do Container (Load Balancer)
Label=traefik.http.services.meu-app.loadbalancer.server.port=3000

# Middleware (Ex: Redirect HTTP->HTTPS) - Opcional se entrypoints já for websecure
# Label=traefik.http.middlewares.https-redirect.redirectscheme.scheme=https

[Install]
WantedBy=multi-user.target
```

### 3. Aplicar as Alterações

O systemd precisa ler o novo arquivo e gerar o serviço correspondente.

```bash
# Se criado como Root
sudo systemctl daemon-reload
sudo systemctl start meu-app

# Se criado como Usuário
systemctl --user daemon-reload
systemctl --user start meu-app
```

---

## 🔄 Atualizando um Serviço

Se a imagem estiver configurada com `AutoUpdate=registry`, o Podman pode atualizar automaticamente. Para fazer manual:

1.  **Baixar nova imagem**: `podman pull docker.io/minha-empresa/meu-app:latest`
2.  **Reiniciar serviço**: `systemctl restart meu-app`

---

## 🛠️ Troubleshooting

### Verificar Status do Serviço
```bash
systemctl status meu-app
```

### Ver Logs da Aplicação
```bash
# Follow logs em tempo real
journalctl -f -u meu-app

# Ver logs anteriores
journalctl -u meu-app -n 100
```

### O Container não sobe?
1.  Verifique erros de sintaxe no arquivo `.container`:
    ```bash
    /usr/libexec/podman/quadlet -dryrun
    ```
2.  Verifique se a porta está em uso.
3.  Verifique se a imagem existe e foi baixada.

### O domínio não responde (Erro 404/502)?
1.  Verifique se o container está na rede `web_proxy`.
2.  Confira se a `port` no Label do Traefik bate com a porta que a aplicação escuta internamente.
3.  Veja os logs do Traefik: `journalctl -f -u traefik`

---

## e 💡 Boas Práticas (Patterns)

### Resiliência (Restart Policy)
Para garantir que o serviço suba automaticamente após falhas ou reboots:
```ini
[Service]
Restart=always
```

### Timeouts para Imagens Grandes
Se a imagem for grande (ex: Invoice Ninja, AI Models) e a rede lenta, aumente o timeout de inicialização para evitar que o systemd mate o processo durante o pull:
```ini
[Service]
TimeoutStartSec=900
```

---

## 📂 Estrutura de Diretórios Recomendada

Mantenha os volumes organizados em `/mnt/data/`:

```text
/mnt/data/
├── postgres/          # Dados do Banco
├── redis/             # Dados do Cache
├── saveinmed/
│   ├── backend/
│   └── uploads/
└── [nome-do-projeto]/
    └── [tipo-de-dado]/
```