145 lines
3.8 KiB
Markdown
145 lines
3.8 KiB
Markdown
# 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]/
|
|
```
|