Como Instalar o eDirectory Usando o Instalador Ansible

Introdução

O Instalador Ansible do eDirectory é uma ferramenta técnica criada para automatizar a configuração de um ambiente self-hosted novo do eDirectory.

Esse instalador ajuda a configurar automaticamente os principais requisitos de servidor necessários para executar o eDirectory, incluindo Apache, PHP, MySQL/MariaDB, Elasticsearch, download do pacote do eDirectory e configuração inicial do sistema.

O Instalador Ansible é indicado para usuários técnicos, administradores de sistema e clientes com licença Source que desejam instalar uma nova instância do eDirectory em seu próprio servidor.

Nota Importante: Este processo é destinado a uma instalação nova do eDirectory. Ele não deve ser utilizado como processo de migração de um site existente com conteúdo, arquivos, mídias, usuários, anúncios e registros de banco de dados.

Instalação Nova vs. Migração de Site

Antes de utilizar o Instalador Ansible, é importante entender a diferença entre uma instalação nova e uma migração.

Uma instalação nova cria um novo ambiente do eDirectory em um servidor limpo, com uma nova estrutura de banco de dados. Esse processo é indicado quando o objetivo é instalar o software do zero.

Uma migração transfere um site eDirectory existente de um ambiente de hospedagem para outro. Nesse caso, é necessário mover tanto os arquivos da aplicação quanto o conteúdo do banco de dados do site atual.

O Instalador Ansible foi criado para instalações novas. Caso o objetivo seja mover um site eDirectory existente para um novo servidor, entre em contato com nossa equipe de suporte para que o processo de migração seja analisado corretamente.

O Que o Instalador Ansible Faz

O Instalador Ansible automatiza a instalação e configuração dos principais serviços exigidos pelo eDirectory.

O playbook instala e configura:

Apache
PHP e extensões necessárias
MySQL/MariaDB
Credenciais de banco de dados
Elasticsearch
Download do pacote do eDirectory
Configuração da aplicação
Configuração inicial do banco de dados
Ambiente necessário do sistema
Instalação inicial do eDirectory

O objetivo do instalador é reduzir a necessidade de configuração manual do servidor e evitar inconsistências que podem ocorrer ao instalar cada dependência separadamente.

Requisitos

Antes de iniciar, certifique-se de que você possui:

Um servidor Linux limpo
Ubuntu 22.04 ou Ubuntu 24.04
Acesso root ou sudo
Ansible instalado na máquina que executará o playbook
Uma versão válida do pacote do eDirectory
A senha de download necessária para obter o pacote do eDirectory
Um domínio ou subdomínio que será utilizado na instalação

O domínio deve estar apontado para o IP do servidor antes de testar o site no navegador.

Nota Importante: Não execute o instalador em um servidor que já hospeda outros sites, aplicações, bancos de dados personalizados ou configurações conflitantes, a menos que você compreenda completamente o impacto das alterações aplicadas.

Instalando o Ansible

Em distribuições baseadas em Ubuntu/Debian, instale o Ansible com os comandos abaixo:

apt update
apt install -y ansible

Depois da instalação, confirme se o Ansible está disponível executando:

ansible --version

Baixando o Instalador

O pacote do Instalador Ansible do eDirectory será fornecido pela equipe de suporte ou infraestrutura do eDirectory quando aplicável.

Após receber o pacote, acesse o servidor e faça o download/extração no diretório recomendado.

Exemplo:

cd /root
wget [installer-download-url]
tar -zxvf edirectory-ansible-installer.tar.gz
cd edirectory-ansible-installer

Substitua [installer-download-url] pelo link de download fornecido pela equipe do eDirectory.

Por motivos de segurança, não compartilhe publicamente credenciais do instalador, senhas de pacote ou URLs de download.

Configurando o Arquivo vars.yml

Antes de executar o playbook, edite o arquivo vars.yml e preencha as variáveis obrigatórias.

Exemplo:

domain: domain.com
mysql_root_pass: mysqlrootpassword
db_prefix: prefix
db_pass: edirectorydatabasepassword
language: en
locale: en_us
edirectory_version: 14.1.00
download_pass: downloadpassword

Descrição das Variáveis

Variável	Descrição
`domain`	Domínio usado na instalação do eDirectory. Não inclua `http://` ou `https://` .
`mysql_root_pass`	Senha root que será configurada para o serviço de banco de dados.
`db_prefix`	Prefixo usado nos nomes dos bancos de dados do eDirectory. Use apenas letras e números.
`db_pass`	Senha usada pelo usuário de banco de dados do eDirectory.
`language`	Idioma padrão do sistema.
`locale`	Localidade padrão do sistema.
`edirectory_version`	Versão do pacote do eDirectory que será baixada e instalada.
`download_pass`	Senha utilizada para baixar o pacote do eDirectory.

Regras Importantes de Configuração

Ao editar o arquivo vars.yml , revise cuidadosamente as regras abaixo:

O valor de domain não deve incluir http:// ou https:// .
O domínio deve ser um domínio ou subdomínio válido.
O db_prefix deve conter apenas letras e números.
Os valores de language e locale devem corresponder às opções suportadas pelo instalador.
O valor de edirectory_version deve corresponder à versão do pacote fornecida pelo eDirectory.
O valor de download_pass deve ser válido para a versão selecionada do pacote.

Se alguma variável obrigatória estiver ausente ou preenchida incorretamente, o instalador poderá interromper o processo durante a validação.

Executando o Playbook

Após configurar o arquivo vars.yml , execute:

ansible-playbook playbook.yml

O processo de instalação será iniciado.

Durante a execução, o playbook instalará os pacotes necessários, configurará os serviços, baixará o pacote do eDirectory, configurará o ambiente e concluirá a instalação inicial.

Requisito de Domínio e DNS

Após a conclusão do playbook, você poderá testar o site no navegador. No entanto, o domínio precisa estar apontado para o IP do servidor.

Antes de testar o site, confirme que:

O domínio ou subdomínio possui um registro A apontando para o IP do servidor.
A propagação de DNS foi concluída.
O domínio no DNS é o mesmo domínio configurado no arquivo vars.yml .
Não existem registros DNS conflitantes ou redirecionamentos incorretos.
O firewall do servidor permite tráfego web.

Se o domínio ainda não estiver apontando corretamente, a instalação pode ter sido concluída com sucesso, mas o site não carregará pela URL esperada.

Acessando o Site Manager

Após a instalação, a área administrativa do eDirectory estará disponível em:

http://domain.com/sitemgr

Substitua domain.com pelo domínio configurado no arquivo vars.yml .

Checklist Recomendado Após a Instalação

Depois de concluir a instalação, recomendamos verificar os seguintes pontos:

Confirmar se a página inicial do site carrega corretamente.
Confirmar se /sitemgr carrega corretamente.
Fazer login usando as credenciais administrativas padrão.
Alterar a senha padrão do administrador.
Confirmar se o domínio aponta para o servidor correto.
Confirmar se o Apache está em execução.
Confirmar se o serviço de banco de dados está em execução.
Confirmar se o Elasticsearch está em execução.
Confirmar se os cron jobs foram criados.
Revisar as configurações iniciais do site dentro do Site Manager.

Comandos Básicos de Verificação

Você pode utilizar os comandos abaixo para verificar os principais serviços.

Verificar o Apache:

systemctl status apache2

Verificar o serviço de banco de dados:

systemctl status mariadb

Verificar o Elasticsearch:

systemctl status elasticsearch

Verificar se o Elasticsearch responde localmente:

curl http://localhost:9200

Verificar os cron jobs criados para o usuário do servidor web:

crontab -u www-data -l

Solução de Problemas

O playbook falha durante a validação

Revise os valores inseridos no arquivo vars.yml .

Causas comuns incluem:

Variável obrigatória ausente
Domínio preenchido com http:// ou https://
Formato inválido de domínio
Prefixo do banco de dados com caracteres especiais
Valor inválido de idioma
Valor inválido de localidade
Versão incorreta do pacote
Senha de download incorreta

O pacote não pode ser baixado

Confirme que:

O servidor possui acesso à internet.
O valor de edirectory_version está correto.
O valor de download_pass está correto.
O link de download ainda está válido.
Não há restrições de firewall bloqueando a requisição.

O site não carrega após a instalação

Verifique se o domínio está apontado para o IP correto do servidor.

Também confirme se o Apache está em execução:

systemctl status apache2

Se o DNS ainda estiver em propagação, a instalação pode estar concluída mesmo que o domínio ainda não carregue no navegador.

A área Site Manager não carrega

Confirme se você está acessando a URL correta:

http://domain.com/sitemgr

Também verifique se o domínio acessado no navegador é o mesmo domínio configurado no arquivo vars.yml .

O Elasticsearch não está funcionando

Verifique o serviço do Elasticsearch:

systemctl status elasticsearch

Se necessário, reinicie o serviço:

systemctl restart elasticsearch

Depois, teste novamente:

curl http://localhost:9200

Os cron jobs não foram criados

Verifique a lista de cron jobs do usuário do servidor web:

crontab -u www-data -l

Se os cron jobs não estiverem listados, o playbook pode não ter sido concluído corretamente.

O domínio aponta para o local errado

Revise a configuração DNS do domínio e confirme se o registro A aponta para o IP correto do servidor.

Caso esteja utilizando proxy DNS ou CDN, desativar temporariamente o proxy pode ajudar a confirmar se o servidor está respondendo corretamente.

Observações Sobre Ambientes Não Suportados

O Instalador Ansible foi desenvolvido para instalações self-hosted padrão em servidores Ubuntu suportados.

Os cenários abaixo não são cobertos por este instalador:

Migração de um site existente em produção
Instalação do eDirectory em um servidor com aplicações já existentes
Instalação do eDirectory em Docker ou ambientes containerizados
Uso de PostgreSQL em vez de MySQL/MariaDB
Separação da aplicação, banco de dados e arquivos de mídia em múltiplos servidores
Instalação com versões não suportadas de PHP, banco de dados ou Elasticsearch
Substituição da arquitetura padrão por uma infraestrutura personalizada

Cenários de infraestrutura personalizada podem exigir planejamento adicional fora do escopo padrão de suporte.

Recomendações de Segurança

Após a instalação, recomendamos:

Alterar imediatamente a senha padrão do Site Manager.
Armazenar senhas de banco de dados com segurança.
Não compartilhar publicamente credenciais de download do pacote.
Restringir o acesso SSH apenas a usuários autorizados.
Revisar as regras de firewall.
Ativar HTTPS/SSL antes de utilizar o site em produção.
Manter as credenciais de acesso ao servidor em segurança.
Evitar permissões de arquivo excessivamente abertas.

Conclusão

O Instalador Ansible do eDirectory oferece uma forma mais simples e confiável de realizar uma instalação nova do eDirectory em ambiente self-hosted. Ele automatiza a configuração dos principais requisitos do servidor, incluindo Apache, PHP, MySQL/MariaDB, Elasticsearch, pacote do eDirectory e configuração inicial do sistema.

Antes de executar o instalador, certifique-se de utilizar um servidor Ubuntu limpo e suportado, preencher corretamente todas as variáveis no arquivo vars.yml e apontar o domínio para o IP do servidor.

Para sites existentes em produção, o Instalador Ansible não deve ser tratado como uma ferramenta de migração. Caso você precise mover um site eDirectory existente para outro servidor, entre em contato com o suporte do eDirectory para que o processo seja analisado corretamente.