Instalando usando Docker e Docker Compose

With the dockerized OTOBO deployment you can get your personal OTOBO instance up and running within minutes. All of OTOBO´s dependencies are already included in the provided collection of Docker images.

  • MariaDB é configurado como o banco de dados padrão.
  • Elasticsearch é configurado para a busca avançada no OTOBO.
  • Redis está habilitado para cache rápido.
  • Gazelle é usado como um servidor web Perl rápido.
  • nginx é usado como proxy reverso opcional para suporte HTTPS.

We think that this setup will become the perfect environment for an OTOBO installation.

Requerimentos

As versões mínimas do software necessário, que foram testadas, estão listadas aqui:

  • Docker 19.03.13
  • Docker Compose 1.25.0
  • Git 2.17.1

Nota

Para obter as versões mínimas necessárias no Ubuntu 18.04, siga as instruções em https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04 e https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04.

git, Docker e Docker Compose podem ser instalados com as ferramentas de sistema padrão. Aqui está um exemplo de instalação no Ubuntu 20.04:

root> apt-get install git docker docker-compose
root> systemctl enable docker

Verifique a documentação do Git e do Docker para obter instruções sobre configurações adicionais.

Instalação

As instruções a seguir pressupõem que todos os requisitos sejam atendidos, que você tenha um ambiente Docker funcionando. Presumimos aqui que o usuário docker_admin é usado para interagir com o Docker. O administrador do Docker pode ser o usuário root do host do Docker ou um usuário dedicado com as permissões necessárias.

1. Clone the otobo-docker repo

The Docker images will eventually be fetched from the repository https://hub.docker.com. But there are some setup and command files that need to be cloned from the otobo-docker Github repository. Make sure that you specify the branch that corresponds to the current version of OTOBO. For example, when OTOBO 10.0.12 is the current version then please use the branch rel-10_0.

Nota

A localização do repositório clonado não importa. Para essas instruções, escolhemos /opt/otobo-docker como o diretório de trabalho.

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo-docker.git --branch <BRANCH> --single-branch
docker_admin> ls otobo-docker    # just a sanity check, README.md should exist

2. Create an initial .env file

The Docker Compose configuration file .env is your primary interface for managing your installation of OTOBO. This file must first be created and then be adapted by yourself. In order to simplify the task there are several example files that should be used as starting point. Which sample file it the best fit depends on your use case. In most cases the decision is between .docker_compose_env_http and .docker_compose_env_https, depending on whether TLS must be supported or not. The other files are for more specialised use cases.

.docker_compose_env_http
O aplicativo da web OTOBO fornece HTTP.
.docker_compose_env_https
The OTOBO web app provides HTTPS by runnning Nginx as a reverse proxy webserver.
.docker_compose_env_https_custom_nginx
Like .docker_compose_env_https but with support for a custom Nginx configuration.
.docker_compose_env_https_kerberos
Like .docker_compose_env_https but with sample setup for single sign on.
.docker_compose_env_http_selenium and .docker_compose_env_https_selenium
These are used only for development when Selenium testing is activated.

Nota

Use ls -a for listing the hidden sample files.

Por padrão, o OTOBO é servido nas portas padrão. Porta 443 para HTTPS e porta 80 para HTTP. Quando o HTTPS é ativado, o aplicativo da web OTOBO ainda é executado com HTTP. O suporte HTTPS é obtido por um proxy reverso adicional, que é implementado como um serviço nginx.

Para os comandos a seguir, presumimos que HTTPS deve ser compatível.

docker_admin> cd /opt/otobo-docker
docker_admin> cp -p .docker_compose_env_https .env # or .docker_compose_env_http for HTTP

3. Configure the password for the database admin user

Altere o seguinte valor dentro do arquivo .env:

OTOBO_DB_ROOT_PASSWORD=<your_secret_password>

A senha do usuário administrador do banco de dados pode ser escolhida livremente. O usuário administrador do banco de dados é necessário para criar o usuário do banco de dados otobo e o esquema do banco de dados otobo. O OTOBO realmente usará o usuário de banco de dados dedicado otobo.

4. Set up a volume with SSL configuration for the nginx webproxy (optional)

Esta etapa pode ser ignorada quando o OTOBO deve estar disponível apenas via HTTP.

O nginx precisa de um certificado e uma chave privada para criptografia SSL.

Nota

Para teste e desenvolvimento, um certificado auto-assinado pode ser usado. No entanto, para uso produtivo, você deve trabalhar com certificados regulares registrados.

Veja, por exemplo https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04 sobre como criar certificados auto-assinados.

Nota

Para especificar uma cadeia de CA com um certificado no nginx, é necessário copiar o arquivo de cadeia de CA com o certificado real em um arquivo.

O certificado e a chave privada são armazenados em um volume, para que possam ser usados pelo nginx posteriormente. Em qualquer caso, o volume precisa ser gerado manualmente e precisamos copiar o certificado e a chave para o volume:

docker_admin> docker volume create otobo_nginx_ssl
docker_admin> otobo_nginx_ssl_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl)
docker_admin> echo $otobo_nginx_ssl_mp  # just a sanity check
docker_admin> cp /PathToYourSSLCert/ssl-cert.crt /PathToYourSSLCert/ssl-key.key $otobo_nginx_ssl_mp

Os nomes dos arquivos copiados precisam ser definidos em nosso arquivo .env recém-criado. Por exemplo.

OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/ssl-cert.crt and OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/ssl-key.key

Adapte apenas o nome dos arquivos, pois o caminho /etc/nginx/ssl/ é codificado na imagem do Docker.

5. Start the Docker containers with Docker Compose

Now we start the Docker containers using docker-compose. Per default the Docker images will be fetched from https://hub.docker.com/u/rotheross.

docker_admin> docker-compose up --detach

Para verificar se os seis serviços necessários (cinco no caso de HTTP apenas) estão realmente em execução, digite:

docker_admin> docker-compose ps
docker_admin> docker volume ls

6. Install and start OTOBO

Execute o instalador OTOBO em http: //yourIPorFQDN/otobo/installer.pl.

Nota

Please configure OTOBO inside the installer with a new MySQL database. As MySQL database root password please use the password you configured in the variable OTOBO_DB_ROOT_PASSWORD of your .env file. Please leave the value db for the MySQL hostname untouched.

Divirta-se com o OTOBO!

Nota

To change to the OTOBO directory, inside the running container, to work on command line as usual, you can use the following Docker command: docker-compose exec web bash.

Informações técnicas adicionais

Esta seção oferece mais informações técnicas sobre o que está acontecendo nos bastidores.

Lista de contêineres Docker

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
Execute o Redis como serviço de cache.
Contêiner opcional otobo_nginx_1
Execute o nginx como proxy reverso para fornecer suporte HTTPS.

Visão geral dos volumes do Docker

Os volumes Docker são criados no host para dados persistentes. Isso permite iniciar e interromper os serviços sem perder dados. Lembre-se de que os contêineres são temporários e apenas os dados nos volumes são permanentes.

otobo_opt_otobo
contains /opt/otobo in the container web and daemon.
otobo_mariadb_data
contains /var/lib/mysql in the container db.
otobo_elasticsearch_data
contains /usr/share/elasticsearch/datal in the container 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 do Docker

In the instructions we did only minimal configuration. But the file .env allows to set more variables. Here is a short list of the most important environment variables. Note that more environment variables are supported by the base images.

Configurações MariaDB

OTOBO_DB_ROOT_PASSWORD
A senha raiz do MySQL. Deve ser definido para rodar otobo db.

Configurações do Elasticsearch

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

OTOBO_Elasticsearch_ES_JAVA_OPTS
Configuração de exemplo: OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m Ajuste este valor para env de produção para um valor de até 4g.

**Configurações do Webserver **

OTOBO_WEB_HTTP_PORT
Definido caso a porta HTTP deva se desviar da porta 80 padrão. Quando HTTPS está habilitado, a porta HTTP redireciona para HTTPS.

configurações do webproxy nginx

Essas configurações serão usadas quando HTTPS está habilitado.

OTOBO_WEB_HTTP_PORT
Definido caso a porta HTTP se desvie da porta 80 padrão. Irá redirecionar para HTTPS.
OTOBO_WEB_HTTPS_PORT
Definido no caso de a porta HTTPS se desviar da porta 443 padrão.
OTOBO_NGINX_SSL_CERTIFICATE
Certificado SSL para o webproxy nginx. Exemplo: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt
OTOBO_NGINX_SSL_CERTIFICATE_KEY
Chave SSL para o webproxy nginx. Exemplo: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Configurações do Docker Compose

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

COMPOSE_PROJECT_NAME
The project name is used as the prefix for the volumes and containers. Per default this prefix is set to otobo, resulting in container names like otobo_web_1 and otobo_db_1. Change this name when you want to run more then one instance of OTOBO on the same server.
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, …
Used for specifying alternative Docker images. Useful for testing local builds or for using updated versions of the images.

Tópicos avançados

Configuração personalizada do nginx webproxy

The container otobo_nginx_1 provides HTTPS support by running Nginx as a reverse proxy. The Docker image that runs in the container is composed of the official Nginx Docker image, https://hub.docker.com/_/nginx, along with a OTOBO specific configuration of Nginx.

The default OTOBO specific configuration can be found within the Docker image at /etc/nginx/template/otobo_nginx.conf.template. Actually, this is only a template for the final configuration. There is a process, provided by the Nginx base image, that replaces the macros in the template with the corresponding environment variable. This process runs when the container starts up. In the default template file, the following macros are used:

OTOBO_NGINX_SSL_CERTIFICATE
For configuring SSL.
OTOBO_NGINX_SSL_CERTIFICATE_KEY
For configuring SSL.
OTOBO_NGINX_WEB_HOST
The internally used HTTP host.
OTOBO_NGINX_WEB_PORT
The internally used HTTP port.

See step 4. for how this configuration possibility was used for setting up the SSL certificate.

Aviso

A abordagem a seguir só é compatível com OTOBO 10.0.4 ou posterior.

When the standard macros are not sufficient, then the customisation can go further. This can be achieved by replacing the default config template with a customized version. It is best practice to not simple change the configuration in the running container. Instead we first create a persistent volume that contains the custom config. Then we tell the otobo_nginx_1 to mount the new volume and to use the customized configuration.

First comes generation of the new volume. In these sample commands, we use the existing template as a starting point.

# stop the possibly running containers
docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose down

# create a volume that is initially not connected to otobo_nginx_1
docker_admin> docker volume create otobo_nginx_custom_config

# find out where the new volume is located on the Docker host
docker_admin> otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker_admin> echo $otobo_nginx_custom_config_mp  # just a sanity check
docker_admin> ls $otobo_nginx_custom_config_mp    # another sanity check

# copy the default config into the new volume
docker_admin> docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest  # use the appropriate label
docker_admin> docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx.conf.template $otobo_nginx_custom_config_mp # might need 'sudo'
docker_admin> ls -l $otobo_nginx_custom_config_mp/otobo_nginx.conf.template # just checking, might need 'sudo'
docker_admin> docker rm tmp-nginx-container

# adapt the file $otobo_nginx_custom_config_mp/otobo_nginx.conf.template to your needs
docker_admin> vim $otobo_nginx_custom_config_mp/otobo_nginx.conf.template

Aviso

Sua configuração nginx adaptada geralmente contém a diretiva listen, que declara as portas do servidor web. As portas usadas internamente foram alteradas entre OTOBO 10.0.3 e OTOBO 10.0.4. Essa mudança deve ser refletida na configuração nginx adaptada. Portanto, para a versão 10.0.3 ou anterior, escute as portas 80 e 443. Para o OTOBO 10.0.4, escute as portas 8080 e 8443.

After setting up the volume, the adapted configuration must be activated. The new volume is set up in docker-compose/otobo-nginx-custom-config.yml. Therefore this file must be added to COMPOSE_FILE. Then Nginx must be directed to use the new config. This is done by setting NGINX_ENVSUBST_TEMPLATE_DIR in the environment. In order to achieve this, uncomment or add the following lines in your .env file:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml:docker-compose/otobo-nginx-custom-config.yml
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom

A configuração do Docker Compose alterada pode ser inspecionada com:

docker_admin> docker-compose config | more

Finalmente, os contêineres podem ser iniciados novamente:

docker_admin> docker-compose up --detach

Consulte também a seção “Using environment variables in nginx configuration (new in 1.19)” em https://hub.docker.com/_/nginx.

Escolhendo 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 as portas já são usadas por outros serviços. Nestes casos, as portas padrão podem ser substituídas especificando OTOBO_WEB_HTTP_PORT e OTOBO_WEB_HTTPS_PORT no arquivo .env.

Personalizando a imagem do OTOBO Docker

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. A vantagem dessa abordagem é que a própria imagem não precisa ser modificada.

Installing extra Debian packages is a little bit trickier. One approach is to create a custom Dockerfile and use the OTOBO image as the base image. Another approach is to create a modified image directly from a running container. This can be done with the command docker commit, https://docs.docker.com/engine/reference/commandline/commit/. A nice writeup of that process is available at https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.

But for the latter approach there are two hurdles to overcome. First, the image otobo runs per default as the user otobo with the UID 1000. The problem is that the user otobo is not allowed to install system packages. Thus, the first part of the solution is to pass the option –user root when running the image. However the second hurdle is that the default entrypoint script /opt/otobo_install/entrypoint.sh exits immediately when it is called as root. The reasoning behind that design decision is that running inadvertently as root should be discouraged. So, the second part of the solution is to specify a different entrypoint script that does not care who the caller is. This leaves us with following example commands, where we add fortune cookies to otobo:

Pull a tagged OTOBO image, if we don’t have it yet, and check whether the image already provides fortune cookies:

$ 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

Add fortune cookies to a named container running the original OTOBO image. This is done in an interactive session as the user root:

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

Create an image from the stopped container and give it a name. Take into account that the default user and entrypoint script must be restored:

$ docker commit -c 'USER otobo'  -c 'ENTRYPOINT ["/opt/otobo_install/entrypoint.sh"]' otobo_orig otobo_with_fortune_cookies

Finally we can doublecheck:

$ 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

The modified image can be specified in your .env file and then be used for fun and profit.

Construindo imagens locais

Nota

Building Docker images locally is usually only needed during development. Other use cases are when more current base images should be used for an installation or when extra functionality must be added to the images.

The Docker files needed for creating Docker images locally are part of the the git repository https://github.com/RotherOSS/otobo:

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

The script for the actual creation of the images is bin/docker/build_docker_images.sh.

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo.git
docker_admin> # checkout the wanted branch. e.g. git checkout rel-10_0_11
docker_admin> cd otobo
docker_admin> # modify the docker files if necessary
docker_admin> bin/docker/build_docker_images.sh
docker_admin> docker image ls

The locally built Docker images are tagged as local-<OTOBO_VERSION> using the version set up the file RELEASE.

After building the local images, one can return to the docker-compose directory. The local images are declared by setting OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX in .env.

Instalação automática

Instead of going through http://yourIPorFQDN/otobo/installer.pl, one can take a short cut. This is useful for running the test suite on a fresh installation.

Aviso

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

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

Lista de comandos úteis

Docker

  • docker system prune -a system clean-up (removes all unused images, containers, volumes, networks)
  • docker version show version
  • docker build --tag otobo --file=otobo.web.Dockerfile . build an image
  • docker run --publish 80:5000 otobo run the new image
  • docker run -it -v opt_otobo:/opt/otobo otobo bash log into the new image
  • docker run -it -v opt_otobo:/opt/otobo --entrypoint bash otobo try that in case entrypoint.sh is broken
  • docker ps show running images
  • docker images show available images
  • docker volume ls list volumes
  • docker volume inspect otobo_opt_otobo inspect a volume
  • docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl get volume mountpoint
  • docker volume rm tmp_volume remove a volume
  • docker inspect <container> inspect a container
  • docker save --output otobo.tar otobo:latest && tar -tvf otobo.tar list files in an image
  • docker exec -it nginx-server nginx -s reload reload nginx

Docker Compose

  • docker-compose config check and show the configuration
  • docker-compose ps show the running containers
  • docker-compose exec nginx nginx -s reload reload nginx