Skip to content

Commit

Permalink
Refactor docker install doc (#1252)
Browse files Browse the repository at this point in the history 
* First step of the refactor

* Continue refactor

* Polished a bit

* Update languages/en/installation-guide/docker/docker_compose.rst

Co-authored-by: Thomas Gerbet <[email protected]>

* Update languages/en/installation-guide/docker/docker_compose.rst

Co-authored-by: Thomas Gerbet <[email protected]>

* Reviews taken into account

* Update languages/en/installation-guide/docker/intro_docker.rst

Co-authored-by: Joris MASSON <[email protected]>

* Streamlined docker Installation Guide.

* Docker Compose Installation guide - Environment Variables need double quotes to parse

* Docker installation guide - Note about passwords should be in Images Configuration

* Update languages/en/installation-guide/docker/docker_compose.rst

Co-authored-by: Joris MASSON <[email protected]>

---------

Co-authored-by: fkozmik <[email protected]>
Co-authored-by: Thomas Gerbet <[email protected]>
Co-authored-by: Joris MASSON <[email protected]>
  • Loading branch information
@fkozmik @LeSuisse @Hyzual
4 people authored Sep 15, 2023
1 parent 6a20280 commit 2bcd2ea
Show file tree
Hide file tree
Showing 8 changed files with 376 additions and 342 deletions.
177 changes: 177 additions & 0 deletions languages/en/installation-guide/docker/docker_compose.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
Docker Compose
===============

.. _env-variables:

The Environment
````````````````
In a special directory (created only for the Tuleap stack), create a ``.env`` file that defines these variables:

.. code-block:: ini
TULEAP_FQDN="tuleap.example.com"
MYSQL_ROOT_PASSWORD="some random strong password"
TULEAP_SYS_DBPASSWD="another strong password"
SITE_ADMINISTRATOR_PASSWORD="and a third strong password"
Please be aware that you need **double quotes** around your variables in order for docker to parse the whole string.

Please check the :ref:`environment variables <docker-environment-variables>` to know what they stand for.


Tuleap Community
`````````````````
.. _docker-images-compose:

.. warning::

The following section is meant for test purpose only. The databases (MySQL and Redis) are handled by Docker and it is not a recommended setup.


Then create a ``compose.yaml`` file with following content:

.. code-block:: yaml
version: "2"
services:
web:
image: tuleap/tuleap-community-edition
hostname: ${TULEAP_FQDN}
restart: always
ports:
- "80:80"
- "443:443"
- "22:22"
volumes:
- tuleap-data:/data
depends_on:
- db
- redis
- mailhog
environment:
- TULEAP_FQDN=${TULEAP_FQDN}
- TULEAP_SYS_DBHOST=db
- TULEAP_SYS_DBPASSWD=${TULEAP_SYS_DBPASSWD}
- SITE_ADMINISTRATOR_PASSWORD=${SITE_ADMINISTRATOR_PASSWORD}
- DB_ADMIN_USER=root
- DB_ADMIN_PASSWORD=${MYSQL_ROOT_PASSWORD}
- TULEAP_FPM_SESSION_MODE=redis
- TULEAP_REDIS_SERVER=redis
# This is for test purpose only. It's not advised to run a production database as a docker container
db:
image: mysql:8.0
command: ["--character-set-server=utf8mb4", "--collation-server=utf8mb4_unicode_ci", "--sql-mode=NO_ENGINE_SUBSTITUTION"]
environment:
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
volumes:
- db-data:/var/lib/mysql
# This is for test purpose only. It's not advised to run a production database as a docker container
redis:
image: redis:6
volumes:
- redis-data:/data
command: redis-server --appendonly yes --auto-aof-rewrite-percentage 20 --auto-aof-rewrite-min-size 200kb
volumes:
tuleap-data:
db-data:
redis-data:
Tuleap Enterprise
`````````````````
.. attention::

This image is only available to :ref:`Tuleap Enterprise <tuleap-enterprise>` subscribers. Please contact your support
team to get your access to the private registry.

You first need to authenticate towards Tuleap's registry:

.. code-block:: bash
$ docker login docker.tuleap.org
You should add these variables in your ``.env`` file (along with the :ref:`aforementioned ones <env-variables>`):

.. code-block:: ini
TULEAP_VERSION="15.0-1"
DB_FQDN="mysql.example.com"
REDIS_FQDN="redis.example.com"
Please check the :ref:`environment variables <docker-environment-variables>` to know what they stand for.

.. code-block:: yaml
version: "2"
services:
tuleap:
image: docker.tuleap.org/tuleap-enterprise-edition:${TULEAP-VERSION}
hostname: ${TULEAP_FQDN}
restart: always
ports:
- "80:80"
- "443:443"
- "22:22"
volumes:
- tuleap-data:/data
environment:
- TULEAP_FQDN=${TULEAP_FQDN}
- TULEAP_SYS_DBHOST=${DB_FQDN}
- TULEAP_SYS_DBPASSWD=${TULEAP_SYS_DBPASSWD}
- SITE_ADMINISTRATOR_PASSWORD=${SITE_ADMINISTRATOR_PASSWORD}
- DB_ADMIN_USER=root
- DB_ADMIN_PASSWORD=${MYSQL_ROOT_PASSWORD}
- TULEAP_FPM_SESSION_MODE=redis
- TULEAP_REDIS_SERVER=${REDIS_FQDN}
volumes:
tuleap-data:
If you want to secure your server and use certificates, you may spawn a Reverse-Proxy in the stack.

Run the docker-compose file
```````````````````````````

Go inside the directory where you created the two files and run

.. code-block:: bash
$ docker-compose up -d
Then you can follow the progress of the installation with

.. code-block:: bash
$ docker-compose logs -f tuleap
Until you see something like:

.. code-block::
...
web_1 | ***********************************************************************************************************
web_1 | * Your Tuleap fully qualified domain name is tuleap.example.com and it's IP address is 172.21.0.5 *
web_1 | ***********************************************************************************************************
web_1 | Setup Supervisord
web_1 | Let the place for Supervisord
web_1 | 2021-06-15 14:46:50,731 INFO Included extra file "/etc/supervisord.d/backend_workers.ini" during parsing
web_1 | 2021-06-15 14:46:50,731 INFO Included extra file "/etc/supervisord.d/crond.ini" during parsing
web_1 | 2021-06-15 14:46:50,731 INFO Included extra file "/etc/supervisord.d/fpm.ini" during parsing
web_1 | 2021-06-15 14:46:50,731 INFO Included extra file "/etc/supervisord.d/httpd.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Included extra file "/etc/supervisord.d/nginx.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Included extra file "/etc/supervisord.d/postfix.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Included extra file "/etc/supervisord.d/rsyslog.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Included extra file "/etc/supervisord.d/sshd.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Included extra file "/etc/supervisord.d/supervisord-server-credentials.ini" during parsing
web_1 | 2021-06-15 14:46:50,732 INFO Set uid to user 0 succeeded
web_1 | 2021-06-15 14:46:50,769 INFO RPC interface 'supervisor' initialized
...
You can then quit the logs command (Ctrl+C) and open your browser at the address set in ``TULEAP_FQDN`` and that's it.

The docker-compose file provided here is for general guidance and you should adapt it to your environment.
One of the main things you will want to configure is a proper email relay.
107 changes: 107 additions & 0 deletions languages/en/installation-guide/docker/docker_standalone.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
Docker Standalone
=================

For anything but tests, you should have a dedicated MySQL (**version 8.0**) and Redis (last stable recommended) databases.

At first run you will need to provide some information about the platform you want to deploy:

* The Tuleap server name (without https) as ``TULEAP_FQDN`` environment variable
* The Database server name as ``TULEAP_SYS_DBHOST`` environment variable. See :ref:`database installation <install_database>` for specific configuration.
* The database admin user (root or equivalent) as ``DB_ADMIN_USER`` environment variable
* The database admin user password as ``DB_ADMIN_PASSWORD`` environment variable
* The database application user (typically ``tuleapadm``) password as ``TULEAP_SYS_DBPASSWD`` environment variable
* The Tuleap ``admin`` user password as ``SITE_ADMINISTRATOR_PASSWORD`` environment variable

Please check the :ref:`environment variables <docker-environment-variables>` to know what they stand for.

.. warning::

You cannot enforce encryption of Redis communication if you enabled Subversion because the underlying code, written in perl, doesn't support encryption.

The data volume must be mounted on ``/data`` inside the container.
When running, the container exposes the following ports:

* ``80`` TCP http traffic, automatically redirected to ``443``
* ``443`` TCP https traffic
* ``22`` TCP ssh traffic (for git)

Tuleap Community
`````````````````

You can init docker image in command line:

.. code-block:: bash
$ docker run -ti \
--restart always \
--publish 22:22 \
--publish 80:80 \
--publish 443:443 \
--hostname tuleap-ce.example.com \
-e TULEAP_FQDN=tuleap-ce.example.com \
-e TULEAP_SYS_DBHOST=db-tuleap-ce.example.com \
-e DB_ADMIN_USER=root \
-e DB_ADMIN_PASSWORD=${MYSQL_ROOT_PASSWORD} \
-e TULEAP_SYS_DBPASSWD=${TULEAP_SYS_DBPASSWD} \
-e SITE_ADMINISTRATOR_PASSWORD=${SITE_ADMINISTRATOR_PASSWORD} \
-e TULEAP_FPM_SESSION_MODE=redis \
-e TULEAP_REDIS_SERVER=redis \
-e TULEAP_REDIS_PASSWORD=${REDIS_PASSWORD} \
-e TULEAP_EMAIL_TRANSPORT=smtp \
-e TULEAP_EMAIL_RELAYHOST=your-smtp.example.com:2025 \
-v /srv/path/to/data:/data
tuleap/tuleap-community-edition
For future runs you don't need to pass all the environment variables:

.. code-block:: bash
$ docker run -d \
--restart always \
--publish 22:22 \
--publish 80:80 \
--publish 443:443 \
--hostname tuleap-ce.example.com \
-e TULEAP_FPM_SESSION_MODE=redis \
-e TULEAP_REDIS_SERVER=redis \
-e TULEAP_EMAIL_TRANSPORT=smtp \
-e TULEAP_EMAIL_RELAYHOST=your-smtp.example.com:2025 \
-v /srv/path/to/data:/data
tuleap/tuleap-community-edition
Tuleap Enterprise
`````````````````
.. attention::

This image is only available to :ref:`Tuleap Enterprise <tuleap-enterprise>` subscribers. Please contact your support
team to get your access to the private registry.

You first need to authenticate towards Tuleap's registry:

.. code-block:: bash
$ docker login docker.tuleap.org
You must specify the Tuleap tag you want to run (there is no ``:latest`` to avoid mistakes). Please note that you can either:

* Use the exact Tuleap Enterprise Edition tag like ``11.13-4``
* Or just run the head tag of the release like ``11.13``

.. code-block:: bash
$ docker run -ti \
-e TULEAP_FQDN=tuleap.example.com \
-e DB_HOST=db-tuleap.example.com \
-e DB_ADMIN_USER="root" \
-e DB_ADMIN_PASSWORD="a fine password" \
-v /srv/path/to/data:/data
docker.tuleap.org/tuleap-enterprise-edition:11.13-3
The next runs won't need the environment variable so you can restart with:

.. code-block:: bash
$ docker run -d \
-v /srv/path/to/data:/data
docker.tuleap.org/tuleap-enterprise-edition:11.13-3
8 changes: 8 additions & 0 deletions languages/en/installation-guide/docker/images-configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ Docker images configuration

This section covers the configuration details that applies to both images.

.. _docker-environment-variables:

Environment variables
`````````````````````

Expand Down Expand Up @@ -51,6 +53,12 @@ Email
Please note that not all plugins can be used with this configuration setting (:ref:`email_relay<emailrelay>`) and you might need to
customize the image to fit your needs.

Passwords
`````````

* We recommend at least 20 chars but only alphabetical & numbers,
* They are set at the first run only (not updated automatically).

TLS Certificates
````````````````

Expand Down
30 changes: 30 additions & 0 deletions languages/en/installation-guide/docker/intro_docker.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
Introduction - Tuleap on Docker
================================

What for ?
``````````

Tuleap delivers two different images:

The Tuleap Community Edition docker image allows you to test Tuleap quickly by skipping the installation and customization part.
It gives you a fully working Tuleap in minutes with everything preconfigured with sensible defaults.
That's the recommended way to install Tuleap, especially if you just want to give it a try.

The Tuleap Enterprise Edition docker image brings a persistent way to keep Tuleap at home.
It allows you to not be bothered by different OS migrations and the like.

Prerequisites
`````````````

You need docker on your host. You might want docker-compose as well.

The following sections assume that you are going to run the Tuleap container as the only "visible" container on the server.
That means that Tuleap web container will publish it's ports (``80``, ``443`` and ``22``) on hosts ports.

External Dependencies
`````````````````````

The image has two dependencies:

* A working database with admin credentials (at first run only)
* A persistent filesystem for data storage
11 changes: 8 additions & 3 deletions languages/en/installation-guide/docker/introduction.rst
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
.. _tee_docker_image:

Docker installation
===================


The Tuleap docker images allow you to test Tuleap quickly by skipping the installation and customization part.
It gives you a fully working Tuleap in minutes with everything preconfigured with sensible defaults.

Table of contents:

.. toctree::
:maxdepth: 1
:maxdepth: 2

tce
tee
intro_docker
images-configuration
verify_images_authenticity
docker_standalone
docker_compose
Loading

0 comments on commit 2bcd2ea

Please sign in to comment.