Refactor docker install doc

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

@@ -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.

languages/en/installation-guide/docker/docker_standalone.rst

@@ -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

languages/en/installation-guide/docker/images-configuration.rst

@@ -3,6 +3,8 @@ Docker images configuration
 
 This section covers the configuration details that applies to both images.
 
+.. _docker-environment-variables:
+
 Environment variables
 `````````````````````
 
@@ -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
 ````````````````
 

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

@@ -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

languages/en/installation-guide/docker/introduction.rst

@@ -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