136 lines
4.7 KiB
Markdown
136 lines
4.7 KiB
Markdown
# MANUAL TÉCNICO - INSTALAÇÃO E DEPLOY ZAMMAD - DOCKER/LXC
|
|
|
|
**Código:** ITGINF 0001/26 | **Classificação:** INTERNO
|
|
**Responsável:** João Pedro Toledo Gonçalves | **Data:** {{DATA_ATUAL}}
|
|
|
|
## 1. HISTÓRICO DE REVISÃO
|
|
|
|
| Data | Versão | Descrição | Autor |
|
|
| :--- | :--- | :--- | :--- |
|
|
| {{DATA_ATUAL}} | 1.0 | Criação Inicial | João Pedro Toledo Gonçalves |
|
|
|
|
## 2. OBJETIVO
|
|
Documentar os dois métodos homologados de instalação do Zammad: Container (Docker) e Sistema Operacional (LXC/VM debian).
|
|
|
|
## 3. PRÉ-REQUISITOS
|
|
* [ ] Servidor Linux (Debian 11/12 ou Ubuntu 22.04).
|
|
* [ ] Mínimo 4GB RAM (Recomendado 8GB).
|
|
* [ ] Acesso Root/Sudo.
|
|
* [ ] DNS configurado para o domínio do helpdesk (ex: `suporte.itguys.com`).
|
|
|
|
## 4. PASSO A PASSO (EXECUÇÃO)
|
|
|
|
### Opção A: Docker Compose (Recomendado)
|
|
A instalação via Docker é a mais limpa e fácil de manter.
|
|
|
|
**Etapa 1: Preparação do Host**
|
|
O Elasticsearch exige uma configuração específica de memória virtual.
|
|
|
|
1. Acesse o servidor via SSH.
|
|
2. Execute o comando para ajuste persistente:
|
|
```bash
|
|
sysctl -w vm.max_map_count=262144
|
|
echo "vm.max_map_count=262144" >> /etc/sysctl.conf
|
|
```
|
|
|
|
**Etapa 2: Clonar Repositório e Configurar**
|
|
1. Baixe o repositório oficial:
|
|
```bash
|
|
git clone https://github.com/zammad/zammad-docker-compose.git
|
|
cd zammad-docker-compose
|
|
```
|
|
2. Defina a versão (Tag) mais recente estável (Evite `latest` em produção):
|
|
```bash
|
|
git checkout 6.2.0-15 # Exemplo, verifique a última no Github
|
|
```
|
|
3. Ajuste o arquivo `.env`:
|
|
```bash
|
|
cp .env.dist .env
|
|
nano .env
|
|
```
|
|
* Altere `ELASTICSEARCH_MEMORY` para `2G` se tiver pouca RAM.
|
|
* Altere passwords do Postgres se necessário.
|
|
|
|
**Etapa 3: Iniciar Stack**
|
|
1. Suba os containers:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
2. Aguarde cerca de 5 minutos (Iniciação do Rails e Elasticsearch).
|
|
3. Acesse `http://SEU_IP:8080`.
|
|
|
|
|
|
|
|
---
|
|
|
|
### Opção B: Instalação em LXC/VM (Pacote .deb)
|
|
Ideal para Proxmox containers (LXC) onde Docker não é desejado.
|
|
|
|
**Etapa 1: Dependências e Locales**
|
|
1. Defina o locale para UTF-8 (Crítico para PostgreSQL):
|
|
```bash
|
|
localectl set-locale LANG=en_US.UTF-8
|
|
update-locale
|
|
```
|
|
2. Adicione o repositório oficial do Zammad:
|
|
```bash
|
|
curl -fsSL https://dl.packager.io/srv/zammad/zammad/key | gpg --dearmor | tee /etc/apt/trusted.gpg.d/pkgr-zammad.gpg > /dev/null
|
|
echo "deb https://dl.packager.io/srv/zammad/zammad/stable/debian 12 main" | tee /etc/apt/sources.list.d/zammad.list
|
|
```
|
|
|
|
**Etapa 2: Instalação do Pacote**
|
|
1. Instale o Zammad (Isso trará Nginx, Elasticsearch e PostgreSQL automaticamente):
|
|
```bash
|
|
apt update
|
|
apt install zammad
|
|
```
|
|
2. O instalador pedirá configurações básicas. Siga os prompts.
|
|
|
|
**Etapa 3: Configuração do Elasticsearch**
|
|
1. Instale o plugin mapper-attachments:
|
|
```bash
|
|
/usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
|
|
systemctl restart elasticsearch
|
|
```
|
|
2. Conecte o Zammad ao Elastic:
|
|
```bash
|
|
zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"
|
|
zammad run rake searchindex:rebuild
|
|
```
|
|
|
|
## 5. SOLUÇÃO DE PROBLEMAS (TROUBLESHOOTING)
|
|
|
|
!!! warning "Pânico: Instalação Falhou"
|
|
Erros comuns durante o deploy inicial.
|
|
|
|
**Problema 1: Elasticsearch morre após segundos (Docker)**
|
|
* **Erro:** Logs mostram `max virtual memory areas vm.max_map_count [65530] is too low`.
|
|
* **Causa:** Esqueceu a Etapa 1 do Docker.
|
|
* **Solução:** Rode `sysctl -w vm.max_map_count=262144` no **HOST** (não no container) e reinicie a stack.
|
|
|
|
**Problema 2: Erro 502 Bad Gateway no Nginx**
|
|
* **Causa:** O container `zammad-railsserver` ainda está iniciando ou falhou.
|
|
* **Solução:**
|
|
1. Verifique logs: `docker compose logs -f zammad-railsserver`.
|
|
2. Se estiver "Booting...", aguarde. Pode levar 5-10 min na primeira vez.
|
|
|
|
**Problema 3: Instalação via Pacote falha no PostgreSQL**
|
|
* **Causa:** Locale incorreto (não UTF-8).
|
|
* **Solução:**
|
|
1. Rode `localectl` e garanta que está tudo UTF-8.
|
|
2. Se falhar, purgue o pgsql: `apt remove --purge postgresql*` e tente de novo.
|
|
|
|
## 6. DADOS TÉCNICOS
|
|
|
|
| Serviço | Porta Interna | Porta Externa (Padrão) |
|
|
| :--- | :--- | :--- |
|
|
| **Nginx** | 8080 | 8080 (Docker) / 80 (Pkg) |
|
|
| **PostgreSQL** | 5432 | Não exposta |
|
|
| **Elasticsearch**| 9200 | Não exposta |
|
|
| **Memcached** | 11211 | Não exposta |
|
|
|
|
## 7. VALIDAÇÃO FINAL
|
|
- [ ] A interface web carrega sem erros?
|
|
- [ ] O comando `zammad run rails r "p Setting.get('es_url')"` retorna a URL correta?
|
|
- [ ] O ElasticSearch está com status verde/amarelo? (`curl localhost:9200/_cluster/health`)
|