安装应用 Docker和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.

  • Service db: MariaDB is set up as the default database.
  • Service elastic: Elasticsearch is set up for the OTOBO power search.
  • Service redis: Redis is enabled for fast caching.
  • Service web: Gazelle is used as fast Perl webserver.
  • Service nginx: Nginx is used as optional reverse proxy for HTTPS support.

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

需求

经过测试的所需软件最低版本，请参考下面列表：

  • Docker 19.03.08
  • DockerCompose 1.25.0
  • Git 2.25.1

Note

要得到所需的Ubuntu18.04最低版本，请按照https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04和https://wwwdigitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04中的说明进行操作。

可以使用标准系统工具来安装git，Docker和Docker Compose。这是在Ubuntu 20.04上安装的示例：

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

请查看Git和Docker文档，得到更多步骤的说明。

安装

下面的介绍是在假设所有需要的系统都已经安装，并且你已经有了一个工作的Docker环境。我们假设用户**root**被用来和Docker互动，请注意针对一个生产环境，需要有一个专用用户作为Docker管理员。

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.15 is the current version then please use the branch rel-10_0.

Note

克隆副本的位置并不重要，在介绍中我们选择 */opt/otobo-docker*作为工作目录。

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
The OTOBO web app provides 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. Note that Kerberos support is still experimental.
.docker_compose_env_http_selenium and .docker_compose_env_https_selenium
These are used only for development when Selenium testing is activated.

Note

Use ls -a for listing the hidden sample files.

默认情况下，OTOBO在标准端口上提供， HTTPS的端口443和端口80。激活HTTPS后，OTOBO Web应用程序实际上始终使用HTTP运行。 HTTPS的支持通过另外的反向代理来实现，该代理通过nginx服务实现。

我们假定以下命令都支持HTTPS。

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

调整*.env*文件中的以下数值：

OTOBO_DB_ROOT_PASSWORD=<your_secret_password>

``OTOBO_DB_ROOT_PASSWORD``数据库管理员的密码可以自由选择，数据库管理员创建了数据库用户**otobo**和数据库模式**otobo**。

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

如果OTOBO只能通过HTTP进行，这个步骤就可以跳过。

nginx需要SSL加密的证书和私钥。

Note

为了进行测试和开发，可以使用自签名证书。在一般情况下，必须使用注册证书。

参考<https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04>`中的案例，如何创建自己签名的证书。

Note

在nginx中指定一个带有证书的CA链，需要将这个带有实际证书的CA链文件考入一个文件中去。

证书和私钥存储在一个卷中，以便以后Nginx使用，在任何情况下，都需要手动生成该卷，并且需要将证书和密钥复制到该卷：

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

需要在我们新创建的* .env *文件中设置复制文件的名称，例如。

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

请仅调整文件名，因为路径* / etc / nginx / ssl / *在Docker映像中是硬编码的。

安装应用 Docker和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

在使用HTTP的情况下，要验证六个或五个服务是否正在实际运行，请输入：

docker_admin> docker-compose ps
docker_admin> docker volume ls

6. Install and start OTOBO

在http：//yourIPorFQDN/otobo/installer.pl中运行OTOBO安装程序。

Note

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.

与OTOBO玩得开心吧！

Note

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.

附加技术信息

本节对隐含的内容提供了更多的技术见解。

Docker容器列表

容器otobo_web_1
内部端口5000上的OTOBO Web服务器。
容器otobo_daemon_1
OTOBO守护程序。 OTOBO守护程序已启动并定期检查。
容器otobo_db_1
在内部端口3306上运行数据库MariaDB。
容器otobo_elastic_1
在内部端口9200和9300上运行Elasticsearch。
容器otobo_redis_1
将Redis作为缓存服务运行。
可选容器otobo_nginx_1
运行nginx作为反向代理以提供HTTPS支持。

Docker卷概述

Docker卷是在主机上创建的，用于持久性数据。这些允许启动和停止服务而不会丢失数据。请记住，容器是临时的，只有卷中的数据是永久的。

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
包含容器“ redis”的数据。
otobo_nginx_ssl
包含TLS文件，证书和私钥，必须手动初始化。

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.

MariaDB设置

OTOBO_DB_ROOT_PASSWORD
The root password for MariaDB. This setting is required for running the service db.

Elasticsearch设置

Elasticsearch需要在生产环境中进行一些设置。请阅读https://www.elastic.co/guide/zh-CN/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites了解详细信息。

OTOBO_Elasticsearch_ES_JAVA_OPTS
设置案例：* OTOBO_Elasticsearch_ES_JAVA_OPTS = -Xms512m -Xmx512m *，在生产环境中，请将该值提高为4G。

Webserver设置

OTOBO_WEB_HTTP_PORT
设置以防HTTP端口偏离标准端口80。启用HTTPS时，HTTP端口将重定向到HTTPS。

Nginx webproxy settings

这些设置在启用HTTPS时使用。

OTOBO_WEB_HTTP_PORT
设置以防HTTP端口偏离标准端口80。将重定向到HTTPS。
OTOBO_WEB_HTTPS_PORT
设置以防HTTPS端口偏离标准端口443。
OTOBO_NGINX_SSL_CERTIFICATE
Nginx Webproxy的SSL证书。例如：* OTOBO_NGINX_SSL_CERTIFICATE = / etc / nginx / ssl / acme.crt *
OTOBO_NGINX_SSL_CERTIFICATE_KEY
Nginx Webproxy的SSL密钥。例如：* OTOBO_NGINX_SSL_CERTIFICATE_KEY = / etc / nginx / ssl / acme.key *

Nginx webproxy settings for Kerberos

This settings are used by Nginx when Kerberos is used for single sign on.

OTOBO_NGINX_KERBEROS_KEYTAB
Kerberos keytab file. The default is /etc/krb5.keytab.
OTOBO_NGINX_KERBEROS_CONFIG
Kerberos config file. The default is /etc/krb5.conf, usually generated from krb5.conf.template
OTOBO_NGINX_KERBEROS_SERVICE_NAME
Kerberos Service Name. It is not clear where this setting is actually used anywhere.
OTOBO_NGINX_KERBEROS_REALM
Kerberos REALM. Used in /etc/krb5.conf.
OTOBO_NGINX_KERBEROS_KDC
Kerberos kdc / AD Controller. Used in /etc/krb5.conf.
OTOBO_NGINX_KERBEROS_ADMIN_SERVER
Kerberos Admin Server. Used in /etc/krb5.conf.
OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN
Kerberos Default Domain. Used in /etc/krb5.conf.
NGINX_ENVSUBST_TEMPLATE_DIR
Provide a custom Nginx config template dir. Gives extra flexibility.

docker-compose设置

这些设置由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
COMPOSE_FILE数值的分隔符
COMPOSE_FILE
使用* docker-compose / otobo-base.yml 作为基础，并添加所需的扩展文件。例如 docker-compose / otobo-override-http.yml 或 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.

进阶主题

Nginx网络代理的自定义配置

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.

Warning

只有OTOBO 10.0.4或更高版本支持以下方法。

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-10_0  # or latest-10_1, 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

Warning

调整后的Nginx配置通常包含指令** listen **，以明确Web服务器的端口。在OTOBO 10.0.3和OTOBO 10.0.4两个版本中，内部使用的端口有所变化。这个变化必须体现在调整后的nginx配置中。因此，对于10.0.3或更早版本，请使用端口80和443。对于OTOBO 10.0.4，请使用端口8080和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

更改后的Docker Compose配置可以通过以下方式进行检查：

docker_admin> docker-compose config | more

最后，可以再次启动容器：

docker_admin> docker-compose up --detach

另请参见https://hub.docker.com/_/nginx中的“在nginx配置中使用环境变量（1.19中的新功能）”部分。

Single Sign On Using the Kerberos Support in Nginx

Short Description

For enabling authentication with Kerberos please base you .env file on the sample file .docker_compose_env_https_kerberos. This activates the special configuration in docker-compose/otobo-override-https-kerberos.yml. This Docker compose configuration file selects a Nginx image that supports Kerberos. It also passes some Kerberos specific settings as environment values to the running Nginx container. These settings are listed above.

As usual, the values for these setting can be specified in the .env file. Most of ghese setting will be used as replacement values for the template https://github.com/RotherOSS/otobo/blob/rel-10_1/scripts/nginx/kerberos/templates/krb5.conf.template . The replacement takes place during the startup of the container. In the running container the adapted config will be available in /etc/krb5.conf.

Providing an user specific /etc/krb5.conf file is still possible. This can be done by mounting a volume that overrides /etc/krb5.conf in the container. This can be achieved by setting OTOBO_NGINX_KERBEROS_CONFIG in the .env file and by activating the mount directove in docker-compose/otobo-override-https-kerberos.yml.

/etc/krb5.keytab is always installation specific and must therefore always be mounted from the host system.

Kerberos SSO Installation Tutorial

Kerberos Single Sign On in OTOBO Docker installation

选择非标准端口

默认情况下，端口443和80分别为HTTPS和HTTP服务。在某些情况下，其他服务可能已经使用了这些端口中的一个或两个。在这些情况下，可以通过在* .env *文件中指定`OTOBO_WEB_HTTP_PORT`和`OTOBO_WEB_HTTPS_PORT`来覆盖默认端口。

Skip startup of specific services

The current Docker compose setup start five, six when HTTPS is activated, services. But there are valid use cases where one or more of these services are not needed. The prime example is when the database should not run as a Docker service, but as an external database. Unfortunately there is no dedicated Docker compose option for skipping specific services. But the option --scale can be abused for this purpose. So for an installation with an external database the following command can be used:

docker_admin> docker-compose up --detach --scale db=0

Of course the same goal can also be achieved by editing the file docker-compose/otobo-base.yml and removing the relevant service definitions.

Prepare offline installation

Please download the latest version of otobo-docker on a system that has internet access and where docker is installed. Then navigate to the following folder otobo-docker/docker-compose.

cd otobo-docker/docker-compose

Now you can run the following command to download all Docker images from a specific file, in my example I use the otobo-base.yml.

for i in $(cat otobo-base.yml| grep image:| cut -d":" -f3,4 | sed -e "s/-//1" -e"s/\}//g"); do docker pull $i; docker save $i -o $(echo $i|sed "s/\//-/g").docker; done

After that, the images (.docker) are located in the docker-compose folder and can be uploaded to the target system via e.g SCP.

On the offline target system, go to the folder where the docker images are stored. And enter the following command to import them one by one.

In the following example I import the mariadb image:

docker load --input mariadb:10.5.docker

Customizing OTOBO Docker Compose

Instead of editing the files under docker-compose/ and risking to overwrite your own options with the next update of the otobo-docker folder, it is advisable to create an extra YAML file where the specific services are overwritten with additional options.

A common example would be to make the database container accessible from the outside via port 3306. For this you could create an extra docker compose file thats look like:

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

Now we have to tell docker-compose to include our new file. For this you have to add your YAML file to the COMPOSE_FILE variable in the .env file, for example:

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

Now we can use docker-compose to recreate our container

$ docker-compose stop # if otobo is running
$ docker-compose up -d

With this procedure you can customize any service or volumes.

Customizing the OTOBO Docker image

Many customizations can be done in the external volume otobo_opt_otobo which corresponds to the directory /opt/otobo in the Docker image. This works e.g. for local Perl modules which can be installed into /opt/otobo/local. Here is an example that installs the not very useful CPAN module Acme::123.

$ docker exec -it ${COMPOSE_PROJECT_NAME:=otobo}_web_1 bash
otobo@ce36ff89e637:~$ pwd
/opt/otobo
otobo@ce36ff89e637:~$ 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
otobo@ce36ff89e637:~$

The nice thing of this approach is that the Docker image itself does not have to be modified.

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.

创建本地镜像

Note

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.

自动安装

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.

Warning

docker-compose down -v 将清除所有之前的配置和数据。

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

常用命令列表

** 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-10_0 && 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