4.7 KiB

Raw Permalink Blame History

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.

Acesse o servidor via SSH.

Execute o comando para ajuste persistente:

sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" >> /etc/sysctl.conf

Etapa 2: Clonar Repositório e Configurar

Baixe o repositório oficial:

git clone https://github.com/zammad/zammad-docker-compose.git
cd zammad-docker-compose

Defina a versão (Tag) mais recente estável (Evite latest em produção):
```
git checkout 6.2.0-15 # Exemplo, verifique a última no Github
```
Ajuste o arquivo .env:
```
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

Suba os containers:
```
docker compose up -d
```
Aguarde cerca de 5 minutos (Iniciação do Rails e Elasticsearch).
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

Defina o locale para UTF-8 (Crítico para PostgreSQL):

localectl set-locale LANG=en_US.UTF-8
update-locale

Adicione o repositório oficial do Zammad:

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

Instale o Zammad (Isso trará Nginx, Elasticsearch e PostgreSQL automaticamente):
```
apt update
apt install zammad
```
O instalador pedirá configurações básicas. Siga os prompts.

Etapa 3: Configuração do Elasticsearch

Instale o plugin mapper-attachments:

/usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch

Conecte o Zammad ao Elastic:

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)

4.7 KiB Raw Permalink Blame History