Instalação Avançada do OTOBO com Docker Compose

Esta seção fornece mais detalhes técnicos sobre o que acontece por baixo dos panos.

::: version Lista de contêineres Docker; 10+ Contêiner otobo_web_1 : Servidor web OTOBO na porta interna 5000.

Contêiner otobo_daemon_1 : Daemon OTOBO. O daemon OTOBO é iniciado e verificado periodicamente.

Contêiner otobo_db_1 : Executa o banco de dados MariaDB na porta interna 3306.

Contêiner otobo_elastic_1 : Elasticsearch nas portas internas 9200 e 9300.

Contêiner otobo_redis_1 : Executa o Redis como serviço de cache.

Contêiner opcional otobo_nginx_1 : Executa nginx como proxy reverso para fornecer suporte HTTPS. :::

::: version Lista de contêineres Docker; 11 Contêiner otobo-web-1 : Servidor web OTOBO na porta interna 5000.

Contêiner otobo-daemon-1 : Daemon OTOBO. O daemon OTOBO é iniciado e verificado periodicamente.

Contêiner otobo-db-1 : Executa o banco de dados MariaDB na porta interna 3306.

Contêiner otobo-elastic-1 : Elasticsearch nas portas internas 9200 e 9300.

Contêiner otobo-redis-1 : Executa o Redis como serviço de cache.

Contêiner opcional otobo-nginx-1 : Executa nginx como proxy reverso para fornecer suporte HTTPS. :::

Visão Geral dos Volumes Docker

Os volumes Docker são criados no host para armazenamento persistente de dados. Isso permite iniciar e parar os serviços sem perda de dados. Observe que os contêineres são temporários e apenas os dados nos volumes são permanentes.

otobo_opt_otobo : contém /opt/otobo nos contêineres web e daemon.

otobo_mariadb_data : contém /var/lib/mysql no contêiner db.

otobo_elasticsearch_data : contém /usr/share/elasticsearch/data no contêiner elastic.

otobo_redis_data : contém dados para o contêiner redis.

otobo_nginx_ssl : contém os arquivos TLS, certificado e chave privada; deve ser inicializado manualmente.

Variáveis de Ambiente Docker

Nas instruções, realizamos apenas uma configuração mínima. Porém, o arquivo .env permite definir mais variáveis. Abaixo segue uma breve lista das principais variáveis de ambiente. Observe que as imagens base suportam mais variáveis de ambiente.

Configurações do MariaDB

OTOBO_DB_ROOT_PASSWORD : A senha root para o MariaDB. Esta configuração é necessária para operar o serviço db.

Configurações do Elasticsearch

O Elasticsearch exige algumas configurações para ambientes de produção. Leia por favor https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites para obter informações detalhadas.

OTOBO_Elasticsearch_ES_JAVA_OPTS : Exemplo de configuração: OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m. Ajuste este valor para ambientes de produção até 4g.

Configurações do Servidor Web

OTOBO_WEB_HTTP_PORT : Defina este valor se a porta HTTP diferir da porta padrão 80. Quando o HTTPS está ativado, a porta HTTP será redirecionada para HTTPS.

Configurações do proxy web Nginx : Essas configurações são usadas quando o HTTPS está ativado.

OTOBO_WEB_HTTP_PORT : Defina este valor se a porta HTTP diferir da porta padrão 80. Será redirecionada para HTTPS.

OTOBO_WEB_HTTPS_PORT : Defina este valor se a porta HTTPS diferir da porta padrão 443.

OTOBO_NGINX_SSL_CERTIFICATE : Certificado SSL para o proxy web Nginx. Exemplo: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Chave SSL para o proxy web Nginx. Exemplo: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Configurações do Nginx para Kerberos : Essas configurações são usadas pelo Nginx quando o Kerberos é utilizado para Single Sign-On.

OTOBO_NGINX_KERBEROS_KEYTAB : Arquivo keytab do Kerberos. O padrão é /etc/krb5.keytab.

OTOBO_NGINX_KERBEROS_CONFIG : Arquivo de configuração do Kerberos. O padrão é /etc/krb5.conf, normalmente gerado a partir de krb5.conf.template.

OTOBO_NGINX_KERBEROS_SERVICE_NAME : Nome do serviço Kerberos. Não está claro onde essa configuração é realmente usada.

OTOBO_NGINX_KERBEROS_REALM : Realm Kerberos. Usado em /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_KDC : KDC Kerberos / Controlador AD. Usado em /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_ADMIN_SERVER : Servidor administrativo Kerberos. Usado em /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN : Domínio padrão Kerberos. Usado em /etc/krb5.conf.

NGINX_ENVSUBST_TEMPLATE_DIR : Fornece um diretório personalizado de modelos de configuração do Nginx. Oferece flexibilidade adicional.

Configurações do Docker Compose : Essas configurações são usadas diretamente pelo Docker Compose.

COMPOSE_PROJECT_NAME : O nome do projeto é usado como prefixo para volumes e contêineres. Por padrão, este prefixo é definido como otobo, resultando em nomes de contêineres como otobo_web_1 e otobo_db_1. Altere este nome se desejar executar mais de uma instância do OTOBO no mesmo servidor.

COMPOSE_PATH_SEPARATOR : Separador para o valor de COMPOSE_FILE.

COMPOSE_FILE : Use docker-compose/otobo-base.yml como base e adicione os arquivos de extensão desejados. Por exemplo, docker-compose/otobo-override-http.yml ou docker-compose/otobo-override-https.yml.

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, \... : Usado para especificar imagens Docker alternativas. Útil para testar builds locais ou usar versões atualizadas das imagens.

Configuração Personalizada do Proxy Web Nginx

O contêiner otobo_nginx_1 fornece suporte HTTPS executando o Nginx como proxy reverso. A imagem Docker em execução consiste na imagem oficial do Nginx, https://hub.docker.com/_/nginx, combinada com uma configuração específica do OTOBO. A configuração padrão específica do OTOBO encontra-se dentro da imagem Docker em /etc/nginx/template/otobo_nginx.conf.template. Na verdade, trata-se apenas de um modelo para a configuração final. Existe um processo fornecido pela imagem base do Nginx que substitui os macros no modelo pelas variáveis de ambiente correspondentes. Esse processo é executado ao iniciar o contêiner. No arquivo modelo padrão, os seguintes macros são usados:

OTOBO_NGINX_SSL_CERTIFICATE : Para configuração SSL.

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Para configuração SSL.

OTOBO_NGINX_WEB_HOST : O host HTTP interno usado.

OTOBO_NGINX_WEB_PORT : A porta HTTP interna usada.

Consulte a etapa [4.] para usar essa opção de configuração na instalação do certificado SSL.

Se os macros padrão não forem suficientes, é possível realizar personalizações adicionais. Isso pode ser feito substituindo o modelo de configuração padrão por uma versão personalizada. É uma prática recomendada não alterar a configuração diretamente no contêiner em execução. Nos comandos de exemplo abaixo, usamos o modelo existente como ponto de partida.

cd /opt/otobo-docker
mkdir nginx
docker cp otobo_nginx_1:/etc/nginx/conf.d/otobo_nginx.conf /opt/otobo-docker/nginx/otobo_nginx.conf
docker exec otobo_nginx_1 rm /etc/nginx/conf.d/otobo_nginx.conf

Adicione a seguinte linha ao arquivo docker-compose/otobo-override-https.yml:

volumes:
  - /opt/otobo-docker/nginx/otobo_nginx.conf:/opt/otobo-docker/nginx/otobo_nginx.conf

Você pode usar seu editor de texto favorito com Putty ou WinSCP.

nano docker-compose/otobo-override-https.yml

Agora você pode editar o arquivo /opt/otobo-docker/nginx/otobo_nginx.conf. Para aplicar as alterações, os contêineres devem ser reiniciados:

docker-compose up -d --build

Single Sign-On com Suporte a Kerberos no Nginx

Para ativar a autenticação Kerberos, baseie seu arquivo .env no arquivo de exemplo .docker_compose_env_https_kerberos. Isso ativa a configuração especial em docker-compose/otobo-override-https-kerberos.yml. Este arquivo de configuração Docker Compose seleciona uma imagem Nginx que suporta Kerberos e também passa algumas configurações específicas do Kerberos como variáveis de ambiente para o contêiner Nginx em execução. Essas configurações estão listadas acima. Como de costume, os valores para essas configurações podem ser especificados no arquivo .env. A maioria dessas configurações é usada como valores substitutos no modelo https://github.com/RotherOSS/otobo/blob/rel-10_1/scripts/nginx/kerberos/templates/krb5.conf.template. A substituição ocorre durante a inicialização do contêiner. No contêiner em execução, a configuração adaptada estará disponível em /etc/krb5.conf. Ainda é possível fornecer um arquivo /etc/krb5.conf personalizado, o que pode ser feito montando um volume que substitua /etc/krb5.conf no contêiner. Isso pode ser alcançado definindo OTOBO_NGINX_KERBEROS_CONFIG no arquivo .env e ativando a diretiva de montagem em docker-compose/otobo-override-https-kerberos.yml. O arquivo /etc/krb5.keytab é sempre específico da instalação e, portanto, deve ser sempre montado a partir do sistema host.
Instruções de instalação do SSO Kerberos
sso-kerberos

Uso de Portas Não Padrão

Por padrão, as portas 443 e 80 atendem HTTPS e HTTP, respectivamente. Pode haver casos em que uma ou ambas essas portas já estão sendo usadas por outros serviços. Nessas situações, as portas padrão podem ser substituídas especificando OTOBO_WEB_HTTP_PORT e OTOBO_WEB_HTTPS_PORT no arquivo .env.

Pular a Inicialização de Serviços Específicos

A configuração atual do Docker Compose inicia cinco serviços, seis se o HTTPS estiver ativado. No entanto, existem casos válidos em que um ou mais desses serviços não são necessários. O principal exemplo é quando o banco de dados deve ser executado não como um serviço Docker, mas como um banco de dados externo.

docker-compose up -d web nginx daemon redis elastic

Claro, o mesmo objetivo pode ser alcançado editando o arquivo docker-compose/otobo-base.yml e removendo as definições de serviço relevantes.

Personalização do OTOBO Docker Compose

Em vez de editar os arquivos em docker-compose/ e correr o risco de sobrescrever suas próprias opções na próxima atualização da pasta otobo-docker, é recomendável criar um arquivo YAML extra para substituir serviços específicos com opções adicionais. Um exemplo comum seria tornar o contêiner do banco de dados acessível externamente pela porta 3306. Para isso, você poderia criar um arquivo Docker Compose extra com o seguinte conteúdo:

cat custom_db.yml
services:
  db:
    ports:
      - "0.0.0.0:3306:3306"

Agora precisamos informar ao docker-compose para incluir nosso novo arquivo. Para isso, adicione seu arquivo YAML à variável COMPOSE_FILE no arquivo .env, por exemplo:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-http.yml:custom_db.yml

Agora podemos usar o docker-compose para recriar nossos contêineres:

docker-compose stop
docker-compose up -d

Com este procedimento, você pode personalizar qualquer serviço ou volume.

Personalização da Imagem Docker do OTOBO

Muitas personalizações podem ser feitas no volume externo otobo_opt_otobo, que corresponde ao diretório /opt/otobo na imagem Docker. Isso funciona, por exemplo, para módulos Perl locais que podem ser instalados em /opt/otobo/local. Aqui está um exemplo que instala o módulo CPAN Acme::123, que não é muito útil.

docker exec -it ${COMPOSE_PROJECT_NAME:=otobo}_web_1 bash
pwd

/opt/otobo

cpanm -l local Acme::123

--> Working on Acme::123

Fetching http://www.cpan.org/authors/id/N/NA/NATHANM/Acme-123-0.04.zip ... OK
Configuring Acme-123-0.04 ... OK
Building and testing Acme-123-0.04 ... OK
Successfully installed Acme::123-0.04
1 distribution installed

A vantagem deste método é que a própria imagem Docker não precisa ser modificada.
Instalar pacotes Debian adicionais é um pouco mais complicado. Uma abordagem é criar um Dockerfile personalizado usando a imagem OTOBO como imagem base. Outra abordagem é criar diretamente uma imagem modificada a partir de um contêiner em execução. Isso pode ser feito com o comando docker commit, https://docs.docker.com/engine/reference/commandline/commit/. Uma boa explicação desse processo está disponível em https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.
Para a última abordagem, existem dois obstáculos a superar. Primeiro, a imagem otobo é executada por padrão como o usuário otobo com UID 1000. O problema é que o usuário otobo não tem permissão para instalar pacotes do sistema. Assim, a primeira parte da solução é usar a opção --user root ao iniciar a imagem. O segundo obstáculo é que o script de entrada padrão /opt/otobo_install/entrypoint.sh é encerrado imediatamente quando chamado como root. A lógica por trás dessa decisão de design é evitar a execução acidental como root. A segunda parte da solução, portanto, é especificar um script de entrada diferente que não se importe com quem é o chamador. Com isso, chegamos aos seguintes comandos de exemplo, nos quais adicionamos cookies de fortuna ao otobo:
Baixe uma imagem OTOBO marcada, caso ainda não a tenha, e verifique se a imagem já fornece cookies de fortuna:

docker run rotheross/otobo:rel-10_0_10 /usr/games/fortune

/opt/otobo_install/entrypoint.sh: line 57: /usr/games/fortune: No such file or directory

Adicione cookies de fortuna a um contêiner nomeado executando a imagem OTOBO original. Isso é feito em uma sessão interativa como usuário root:

docker run -it --user root --entrypoint /bin/bash --name otobo_orig rotheross/otobo:rel-10_0_10
apt update
apt install fortunes
exit
docker ps -a | head

Crie uma imagem a partir do contêiner parado e dê a ela um nome. Observe que o usuário padrão e o script de entrada devem ser restaurados:
Finalmente, podemos testá-la:

docker run otobo_with_fortune_cookies /usr/games/fortune

A platitude is simply a truth repeated till people get tired of hearing it.
-- Stanley Baldwin

A imagem modificada pode ser definida em seu arquivo .env e então usada para diversão e proveito.

Criação de Imagens Locais

INFO

A criação local de imagens Docker é normalmente necessária apenas durante o desenvolvimento. Outros casos de uso incluem o uso de imagens base mais recentes para uma instalação ou a necessidade de adicionar funcionalidades extras às imagens.

Os arquivos Docker necessários para criar imagens Docker localmente fazem parte do repositório git https://github.com/RotherOSS/otobo:

• otobo.web.dockerfile
• otobo.nginx.dockerfile
• otobo.elasticsearch.dockerfile

O script para a criação real das imagens é bin/docker/build_docker_images.sh.

cd /opt
git clone https://github.com/RotherOSS/otobo.git

Mude para o branch desejado. Por exemplo:

git checkout rel-10_0_11

cd otobo

Altere os arquivos Docker conforme necessário

bin/docker/build_docker_images.sh
docker image ls

As imagens Docker criadas localmente são marcadas como local-<OTOBO_VERSION>, onde a versão é obtida do arquivo RELEASE.
Após a criação das imagens locais, é possível retornar ao diretório docker-compose. As imagens locais são declaradas definindo OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX no arquivo .env.

Instalação Automática

Em vez de realizar o processo via http://yourIPorFQDN/otobo/installer.pl, pode-se usar um atalho. Isso é útil para executar a suíte de testes em uma instalação nova.

WARNING

docker-compose down -v removerá todas as configurações e dados anteriores.

docker-compose down -v
docker-compose up --detach
docker-compose stop daemon
docker-compose exec web bash\
-c "rm -f Kernel/Config/Files/ZZZAAuto.pm ; bin/docker/quick_setup.pl --db-password otobo_root"
docker-compose exec web bash\
-c "bin/docker/run_test_suite.sh"
docker-compose start daemon

Lista de Comandos Úteis

Docker

• docker system prune -a Limpeza do sistema (remove todas as imagens, contêineres, volumes e redes não utilizados)
• docker version Mostra a versão
• e muitos outros comandos Docker úteis.

Docker Compose

• docker-compose config Verifica e exibe a configuração
• docker-compose ps Mostra os contêineres em execução
• e outros comandos úteis do Docker Compose.