# 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`.

![Terminal Install Docker](assets/zammad_install_docker.png)

---

### 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`)