From 2eb8b04575f7fa65b91a13f119597cf8e7c1e4d0 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Fri, 11 Aug 2023 15:56:31 +0200 Subject: [PATCH 01/11] First step of the refactor --- .../docker/docker_compose.rst | 2 + .../docker/docker_standalone.rst | 108 ++++++++++++++++++ .../docker/intro_docker.rst | 22 ++++ .../docker/introduction.rst | 8 +- .../docker/verify_images_authenticity.rst | 51 +++++++++ 5 files changed, 188 insertions(+), 3 deletions(-) create mode 100644 languages/en/installation-guide/docker/docker_compose.rst create mode 100644 languages/en/installation-guide/docker/docker_standalone.rst create mode 100644 languages/en/installation-guide/docker/intro_docker.rst create mode 100644 languages/en/installation-guide/docker/verify_images_authenticity.rst diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst new file mode 100644 index 00000000..6ba4bd54 --- /dev/null +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -0,0 +1,2 @@ +Docker Compose +=============== \ No newline at end of file diff --git a/languages/en/installation-guide/docker/docker_standalone.rst b/languages/en/installation-guide/docker/docker_standalone.rst new file mode 100644 index 00000000..a1df11ba --- /dev/null +++ b/languages/en/installation-guide/docker/docker_standalone.rst @@ -0,0 +1,108 @@ +Docker Standalone +================= + +For anything but tests you should have a dedicated MySQL (**version 8.0**) and Redis (last stable recommended) databases. + +External Dependencies +````````````````````` + +The image has two dependencies: + +* A working database with admin credentials (at first run only) +* A persistent filesystem for data storage + +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 environments: + +.. 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 +````````````````` + +You first need to authenticate towards Tuleap's registry: + +.. code-block:: bash + + $ docker login docker.tuleap.org + +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 ` 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 ad ``SITE_ADMINISTRATOR_PASSWORD`` environment variable + + * **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. + +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 tuleap-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 tuleap-data:/data + docker.tuleap.org/tuleap-enterprise-edition:11.13-3 + +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) \ No newline at end of file diff --git a/languages/en/installation-guide/docker/intro_docker.rst b/languages/en/installation-guide/docker/intro_docker.rst new file mode 100644 index 00000000..99f995a1 --- /dev/null +++ b/languages/en/installation-guide/docker/intro_docker.rst @@ -0,0 +1,22 @@ +Introduction - Tuleap on Docker +================================ + +What for ? +`````````` + +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". + +Prerequisites +````````````` + +You need docker on your host. You might want docker-compose as well. + +We are going to pull the `official Tuleap Community Edition image `_. +It's built out of Tuleap official pipelines in rolling release mode. + +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. + diff --git a/languages/en/installation-guide/docker/introduction.rst b/languages/en/installation-guide/docker/introduction.rst index 3f5c9ca9..03ff8813 100644 --- a/languages/en/installation-guide/docker/introduction.rst +++ b/languages/en/installation-guide/docker/introduction.rst @@ -7,8 +7,10 @@ It gives you a fully working Tuleap in minutes with everything preconfigured wit Table of contents: .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - tce - tee + intro_docker + verify_images_authenticity + docker_standalone + docker_compose images-configuration diff --git a/languages/en/installation-guide/docker/verify_images_authenticity.rst b/languages/en/installation-guide/docker/verify_images_authenticity.rst new file mode 100644 index 00000000..752c0017 --- /dev/null +++ b/languages/en/installation-guide/docker/verify_images_authenticity.rst @@ -0,0 +1,51 @@ +Verify the image authenticity +============================= + + +.. _check-image-tce: + +Check Tuleap Community image +```````````````````````````` +We sign the `official Tuleap Community Edition image `_ each time we +publish it. The image is signed using `cosign `_. + +You can verify the image authenticity by :download:`downloading our public key ` into a file named ``tuleap_docker.pub`` and then running: + +.. code-block:: + + $ cosign verify -key tuleap_docker.pub tuleap/tuleap-community-edition + +On success the output will look something like this: + +.. code-block:: + + Verification for tuleap/tuleap-community-edition -- + The following checks were performed on each of these signatures: + - The cosign claims were validated + - The signatures were verified against the specified public key + - Any certificates were verified against the Fulcio roots. + {"critical":{"identity":{"docker-reference":"index.docker.io/tuleap/tuleap-community-edition"},"image":{"docker-manifest-digest":"sha256:e425adc51e915c6974db6c82723a520123c1014a091d93b4f504384c6d916608"},"type":"cosign container image signature"},"optional":null} + + +.. _check-image-tee: + +Check Tuleap Enterprise image +````````````````````````````` +We sign the Tuleap Enterprise Docker images each time we publish them. The images are signed using `cosign `_. + +You can verify an image authenticity by :download:`downloading our public key ` into a file named ``tuleap_enterprise_docker.pub`` and then running: + +.. code-block:: + + $ cosign verify -key tuleap_enterprise_docker.pub docker.tuleap.org/tuleap-enterprise-edition:12.11-2 + +On success the output will look something like this: + +.. code-block:: + + Verification for docker.tuleap.org/tuleap-enterprise-edition:14.11-4 -- + The following checks were performed on each of these signatures: + - The cosign claims were validated + - The signatures were verified against the specified public key + - Any certificates were verified against the Fulcio roots. + {"critical":{"identity":{"docker-reference":"docker.tuleap.org/tuleap-enterprise-edition"},"image":{"docker-manifest-digest":"sha256:9dca6d11d176760c447d671d9a6494f731539712b1d083f161aa800cc46e44ef"},"type":"cosign container image signature"},"optional":null} From c527331d262489b467e91272699d82a0e0fbab38 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Wed, 16 Aug 2023 15:59:10 +0200 Subject: [PATCH 02/11] Continue refactor --- .../docker/docker_compose.rst | 224 ++++++++++++++++- .../docker/docker_standalone.rst | 32 ++- .../docker/intro_docker.rst | 10 +- .../docker/introduction.rst | 2 +- .../en/installation-guide/docker/tce.rst | 234 ------------------ .../en/installation-guide/docker/tee.rst | 105 -------- 6 files changed, 245 insertions(+), 362 deletions(-) delete mode 100644 languages/en/installation-guide/docker/tce.rst delete mode 100644 languages/en/installation-guide/docker/tee.rst diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 6ba4bd54..01fde7f4 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -1,2 +1,224 @@ Docker Compose -=============== \ No newline at end of file +=============== + +In a directory named ``tuleap-stack`` (be careful, with docker-compose, directory name matters) create a +``.env`` file that defines these variables: + +.. code-block:: + + 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 + +* ``TULEAP_FQDN`` is the full name of the machine you are going to run Tuleap on. As we saw in pre-requisite section, it should be the name of your docker host either from DNS or at very least defined in ``/etc/hosts`` (will resolve only locally). +* ``MYSQL_ROOT_PASSWORD`` will be the root password of your mysql instance. +* ``TULEAP_SYS_DBPASSWD`` will be the password used by Tuleap application to connect to the database (default user ``tuleapadm``) +* ``SITE_ADMINISTRATOR_PASSWORD`` will be the password of the Tuleap site administrator application user. + +Notes about passwords: + +* we recommend at least 20 chars but only alphabetical & numbers, +* they are set at the site initialization only (not updated automatically). + +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's + not a recommended setup unless you perfectly understand how to operate (run, backup, restore, troubleshoot) them under + docker constraints. + + +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 + + # This is for test purpose only. Mailhog is there to capture email traffic + mailhog: + image: mailhog/mailhog + + volumes: + tuleap-data: + db80-data: + redis-data: + +By default, we spawned a `mailhog `_ image +that will catch all mails sent by Tuleap and display to anyone who have access to the interface. You will be able to access it after starting the stack + +To see the mails captured by mailhog, you should run: + +.. code-block:: bash + + $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q mailhog) + 172.21.0.2 + +This will give you the IP address of the container that runs mailhog, you can then open a browser at this IP address on port ``8025``: + +.. code-block:: bash + + $ xdg-open http://172.21.0.2:8025 + +Tuleap Enterprise +````````````````` +.. attention:: + + This image is only available to :ref:`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 aforementionned ones): + +.. code-block:: + + TULEAP_VERSION=15.0-1 + DB_FQDN=some random strong password + REDIS_FQDN=another strong password + +* ``TULEAP_VERSION`` is the version of Tuleap Enterprise you wish to use. There is no ``latest``, and the version format is either ``15.0`` or ``15.0-1``. +* ``DB_FQDN`` is the full name of the machine hosting the Database. +* ``REDIS_FQDN`` is the full name of the machine hosting Redis. + + +.. code-block:: yaml + + version: "2" + + services: + tuleap: + image: docker.tuleap.org/tuleap-enterprise-edition:${TULEAP-VERSION} + hostname: ${TULEAP_FQDN} + restart: always + 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} + + nginx: + image: nginx:latest + restart: always + ports: + - 80:80 + - 443:443 + volumes: + - ./nginx/certs:/certs + - ./nginx/nginx.conf:/etc/nginx/nginx.conf + + volumes: + tuleap-data: + +You should put your certificates in ``./nginx/certs``, or else nginx will not boot. + +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 web + +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 to your environment. One of the main +thing you will want to configure is a proper email relay. By default, we spawned a `mailhog `_ image +that will catch all mails sent by Tuleap and display to anyone who have access to the interface. + +To see the mails captured by mailhog, you should run: + +.. code-block:: bash + + $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q mailhog) + 172.21.0.2 + +This will give you the IP address of the container that runs mailhog, you can then open a browser at this IP address on port ``8025``: + +.. code-block:: bash + + $ xdg-open http://172.21.0.2:8025 \ No newline at end of file diff --git a/languages/en/installation-guide/docker/docker_standalone.rst b/languages/en/installation-guide/docker/docker_standalone.rst index a1df11ba..183cc5c6 100644 --- a/languages/en/installation-guide/docker/docker_standalone.rst +++ b/languages/en/installation-guide/docker/docker_standalone.rst @@ -3,13 +3,18 @@ Docker Standalone For anything but tests you should have a dedicated MySQL (**version 8.0**) and Redis (last stable recommended) databases. -External Dependencies -````````````````````` +At first run you will need to provide some information about the platform you want to deploy: -The image has two dependencies: +* 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 ` 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 -* A working database with admin credentials (at first run only) -* A persistent filesystem for data storage + * **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. Tuleap Community ````````````````` @@ -58,6 +63,10 @@ For future runs you don't need to pass all the environments: Tuleap Enterprise ````````````````` +.. attention:: + + This image is only available to :ref:`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: @@ -65,19 +74,6 @@ You first need to authenticate towards Tuleap's registry: $ docker login docker.tuleap.org -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 ` 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 ad ``SITE_ADMINISTRATOR_PASSWORD`` environment variable - - * **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. - 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`` diff --git a/languages/en/installation-guide/docker/intro_docker.rst b/languages/en/installation-guide/docker/intro_docker.rst index 99f995a1..b7077473 100644 --- a/languages/en/installation-guide/docker/intro_docker.rst +++ b/languages/en/installation-guide/docker/intro_docker.rst @@ -14,9 +14,13 @@ Prerequisites You need docker on your host. You might want docker-compose as well. -We are going to pull the `official Tuleap Community Edition image `_. -It's built out of Tuleap official pipelines in rolling release mode. - 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 \ No newline at end of file diff --git a/languages/en/installation-guide/docker/introduction.rst b/languages/en/installation-guide/docker/introduction.rst index 03ff8813..a2ba0195 100644 --- a/languages/en/installation-guide/docker/introduction.rst +++ b/languages/en/installation-guide/docker/introduction.rst @@ -10,7 +10,7 @@ Table of contents: :maxdepth: 2 intro_docker + images-configuration verify_images_authenticity docker_standalone docker_compose - images-configuration diff --git a/languages/en/installation-guide/docker/tce.rst b/languages/en/installation-guide/docker/tce.rst deleted file mode 100644 index 73b46589..00000000 --- a/languages/en/installation-guide/docker/tce.rst +++ /dev/null @@ -1,234 +0,0 @@ -Tuleap Community Edition -======================== - -What for ? -`````````` - -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". - -Prerequisites -````````````` - -You need docker on your host. You might want docker-compose as well. - -We are going to pull the `official Tuleap Community Edition image `_. -It's built out of Tuleap official pipelines in rolling release mode. - -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. - -Verify the image authenticity -````````````````````````````` - -We sign the `official Tuleap Community Edition image `_ each time we -publish it. The image is signed using `cosign `_. - -You can verify the image authenticity by :download:`downloading our public key ` into a file named ``tuleap_docker.pub`` and then running: - -.. code-block:: - - $ cosign verify -key tuleap_docker.pub tuleap/tuleap-community-edition - -On success the output will look something like this: - -.. code-block:: - - Verification for tuleap/tuleap-community-edition -- - The following checks were performed on each of these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. - {"critical":{"identity":{"docker-reference":"index.docker.io/tuleap/tuleap-community-edition"},"image":{"docker-manifest-digest":"sha256:e425adc51e915c6974db6c82723a520123c1014a091d93b4f504384c6d916608"},"type":"cosign container image signature"},"optional":null} - -.. _docker-images-compose: - -Deploy a test environment with docker-compose -````````````````````````````````````````````` - -.. warning:: - - The following section is meant for test purpose only. The databases (mysql and redis) are handled by docker and it's - not a recommended setup unless you perfectly understand how to operate (run, backup, restore, troubleshoot) them under - docker constraints. - -In a directory named ``tuleap-community-edition`` (be careful, with docker-compose, directory name matters) create a -``.env`` file that defines two variables: - -.. code-block:: - - 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 - -* ``TULEAP_FQDN`` is the full name of the machine you are going to run Tuleap on. As we saw in pre-requisite section, it should be the name of your docker host either from DNS or at very least defined in ``/etc/hosts`` (will resolve only locally). -* ``MYSQL_ROOT_PASSWORD`` will be the root password of your mysql instance. -* ``TULEAP_SYS_DBPASSWD`` will be the password used by Tuleap application to connect to the database (default user ``tuleapadm``) -* ``SITE_ADMINISTRATOR_PASSWORD`` will be the password of the Tuleap site administrator application user. - -Notes about passwords: - -* we recommend at least 20 chars but only alphabetical & numbers, -* they are set at the site initialization only (not updated automatically). - -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: - - db80-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 - - # This is for test purpose only. Mailhog is there to capture email traffic - mailhog: - image: mailhog/mailhog - - volumes: - tuleap-data: - db80-data: - redis-data: - -Run with docker-compose -``````````````````````` - -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 web - -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 to your environment. One of the main -thing you will want to configure is a proper email relay. By default, we spawned a `mailhog `_ image -that will catch all mails sent by Tuleap and display to anyone who have access to the interface. - -To see the mails captured by mailhog, you should run: - -.. code-block:: bash - - $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q mailhog) - 172.21.0.2 - -This will gives you the IP address of the container that runs mailhog, you can then open a browser at this IP address on port ``8025``: - -.. code-block:: bash - - $ xdg-open http://172.21.0.2:8025 - -Run without docker compose -`````````````````````````` - -For anything but tests you should have a dedicated MySQL (**version 8.0**) and Redis (last stable recommended) databases. - -Then 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 environments: - -.. 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 diff --git a/languages/en/installation-guide/docker/tee.rst b/languages/en/installation-guide/docker/tee.rst deleted file mode 100644 index 410509e2..00000000 --- a/languages/en/installation-guide/docker/tee.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _tee_docker_image: - -Tuleap Enterprise Edition -========================= - -.. attention:: - - This image is only available to :ref:`Tuleap Enterprise ` subscribers. Please contact your support - team to get your access to the private registry. - -What for ? -`````````` - -The Tuleap Enterprise Edition docker image is meant to be used in production with an orchestrator (Kubernetes, Swarm, Nomad, etc) -or not. - -The current image bundles everything in one image to ease the deployment. It's not recommended to configure your deployment -to scale the images (replicate) as it's not designed to run concurrently. - -External Dependencies -````````````````````` - -The image has two dependencies: - -* A working database with admin credentials (at first run only) -* A persistent filesystem for data storage - -How to -`````` - -You first need to authenticate toward Tuleap registry: - -.. code-block:: bash - - $ docker login docker.tuleap.org - -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 ` 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 ad ``SITE_ADMINISTRATOR_PASSWORD`` environment variable - - * **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. - -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 tuleap-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 tuleap-data:/data - docker.tuleap.org/tuleap-enterprise-edition:11.13-3 - -.. NOTE:: - - In the context of an orchestrator you don't need to separate the 2 modes (first run or restart), you can expose the - variables in all runs. Please note however that changing the variables in your deployment (compose, helm, etc) won't - have any impact on the container. You will have to manually edit the configuration files to update the relevant data. - -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) - -Verify the image authenticity -````````````````````````````` - -We sign the Tuleap Enterprise Docker images each time we publish them. The images are signed using `cosign `_. - -You can verify an image authenticity by :download:`downloading our public key ` into a file named ``tuleap_enterprise_docker.pub`` and then running: - -.. code-block:: - - $ cosign verify -key tuleap_enterprise_docker.pub docker.tuleap.org/tuleap-enterprise-edition:12.11-2 - -On success the output will look something like this: - -.. code-block:: - - Verification for docker.tuleap.org/tuleap-enterprise-edition:12.11-2 -- - The following checks were performed on each of these signatures: - - The cosign claims were validated - - The signatures were verified against the specified public key - - Any certificates were verified against the Fulcio roots. - {"critical":{"identity":{"docker-reference":"docker.tuleap.org/tuleap-enterprise-edition"},"image":{"docker-manifest-digest":"sha256:9dca6d11d176760c447d671d9a6494f731539712b1d083f161aa800cc46e44ef"},"type":"cosign container image signature"},"optional":null} From 2cbbeeae15c4656184db8a777eae4b6843ea4a90 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Mon, 28 Aug 2023 15:49:40 +0200 Subject: [PATCH 03/11] Polished a bit --- .../docker/docker_compose.rst | 26 ++++++------------- .../docker/introduction.rst | 3 +++ .../docker/verify_images_authenticity.rst | 5 ---- 3 files changed, 11 insertions(+), 23 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 01fde7f4..ce37a454 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -1,6 +1,10 @@ Docker Compose =============== +.. _env-variables: + +The Environment +```````````````` In a directory named ``tuleap-stack`` (be careful, with docker-compose, directory name matters) create a ``.env`` file that defines these variables: @@ -117,7 +121,7 @@ You first need to authenticate towards Tuleap's registry: $ docker login docker.tuleap.org -You should add these variables in your ``.env`` file (along with the aforementionned ones): +You should add these variables in your ``.env`` file (along with the :ref:`aforementionned ones `): .. code-block:: @@ -164,7 +168,7 @@ You should add these variables in your ``.env`` file (along with the aforementio volumes: tuleap-data: -You should put your certificates in ``./nginx/certs``, or else nginx will not boot. +You should put your certificates in ``./nginx/certs`` or else nginx will not boot. Run the docker-compose file ``````````````````````````` @@ -206,19 +210,5 @@ Until you see something like: 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 to your environment. One of the main -thing you will want to configure is a proper email relay. By default, we spawned a `mailhog `_ image -that will catch all mails sent by Tuleap and display to anyone who have access to the interface. - -To see the mails captured by mailhog, you should run: - -.. code-block:: bash - - $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q mailhog) - 172.21.0.2 - -This will give you the IP address of the container that runs mailhog, you can then open a browser at this IP address on port ``8025``: - -.. code-block:: bash - - $ xdg-open http://172.21.0.2:8025 \ No newline at end of file +The docker-compose file provided here is for general guidance and you should adapt to your environment. +One of the main thing you will want to configure is a proper email relay. \ No newline at end of file diff --git a/languages/en/installation-guide/docker/introduction.rst b/languages/en/installation-guide/docker/introduction.rst index a2ba0195..9bb3e493 100644 --- a/languages/en/installation-guide/docker/introduction.rst +++ b/languages/en/installation-guide/docker/introduction.rst @@ -1,6 +1,9 @@ +.. _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. diff --git a/languages/en/installation-guide/docker/verify_images_authenticity.rst b/languages/en/installation-guide/docker/verify_images_authenticity.rst index 752c0017..f778fffd 100644 --- a/languages/en/installation-guide/docker/verify_images_authenticity.rst +++ b/languages/en/installation-guide/docker/verify_images_authenticity.rst @@ -1,9 +1,6 @@ Verify the image authenticity ============================= - -.. _check-image-tce: - Check Tuleap Community image ```````````````````````````` We sign the `official Tuleap Community Edition image `_ each time we @@ -27,8 +24,6 @@ On success the output will look something like this: {"critical":{"identity":{"docker-reference":"index.docker.io/tuleap/tuleap-community-edition"},"image":{"docker-manifest-digest":"sha256:e425adc51e915c6974db6c82723a520123c1014a091d93b4f504384c6d916608"},"type":"cosign container image signature"},"optional":null} -.. _check-image-tee: - Check Tuleap Enterprise image ````````````````````````````` We sign the Tuleap Enterprise Docker images each time we publish them. The images are signed using `cosign `_. From cc63eb6134c90c1c28322848f58c752da81568ca Mon Sep 17 00:00:00 2001 From: fkozmik <121037513+fkozmik@users.noreply.github.com> Date: Tue, 5 Sep 2023 09:43:30 +0200 Subject: [PATCH 04/11] Update languages/en/installation-guide/docker/docker_compose.rst Co-authored-by: Thomas Gerbet --- languages/en/installation-guide/docker/docker_compose.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index ce37a454..0fd88b75 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -31,9 +31,7 @@ Tuleap Community .. warning:: - The following section is meant for test purpose only. The databases (mysql and redis) are handled by docker and it's - not a recommended setup unless you perfectly understand how to operate (run, backup, restore, troubleshoot) them under - docker constraints. + The following section is meant for test purpose only. The databases (MySQL and Redis) are handled by Docker and it is not a recommend setup. Then create a ``compose.yaml`` file with following content: From a1636585b997a039e97978659bffb75488eae224 Mon Sep 17 00:00:00 2001 From: fkozmik <121037513+fkozmik@users.noreply.github.com> Date: Tue, 5 Sep 2023 09:43:38 +0200 Subject: [PATCH 05/11] Update languages/en/installation-guide/docker/docker_compose.rst Co-authored-by: Thomas Gerbet --- languages/en/installation-guide/docker/docker_compose.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 0fd88b75..8cac9566 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -119,7 +119,7 @@ You first need to authenticate towards Tuleap's registry: $ docker login docker.tuleap.org -You should add these variables in your ``.env`` file (along with the :ref:`aforementionned ones `): +You should add these variables in your ``.env`` file (along with the :ref:`aforementioned ones `): .. code-block:: From 3205e100365ae7e496b1916acdd7d522fc3e4cf4 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Tue, 5 Sep 2023 10:04:29 +0200 Subject: [PATCH 06/11] Reviews taken into account --- .../docker/docker_compose.rst | 47 ++++--------------- 1 file changed, 10 insertions(+), 37 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 8cac9566..094d8819 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -5,8 +5,7 @@ Docker Compose The Environment ```````````````` -In a directory named ``tuleap-stack`` (be careful, with docker-compose, directory name matters) create a -``.env`` file that defines these variables: +In a special directory (created only for the Tuleap stack), create a ``.env`` file that defines these variables: .. code-block:: @@ -81,31 +80,11 @@ Then create a ``compose.yaml`` file with following content: - redis-data:/data command: redis-server --appendonly yes --auto-aof-rewrite-percentage 20 --auto-aof-rewrite-min-size 200kb - # This is for test purpose only. Mailhog is there to capture email traffic - mailhog: - image: mailhog/mailhog - volumes: tuleap-data: - db80-data: + db-data: redis-data: -By default, we spawned a `mailhog `_ image -that will catch all mails sent by Tuleap and display to anyone who have access to the interface. You will be able to access it after starting the stack - -To see the mails captured by mailhog, you should run: - -.. code-block:: bash - - $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q mailhog) - 172.21.0.2 - -This will give you the IP address of the container that runs mailhog, you can then open a browser at this IP address on port ``8025``: - -.. code-block:: bash - - $ xdg-open http://172.21.0.2:8025 - Tuleap Enterprise ````````````````` .. attention:: @@ -124,8 +103,8 @@ You should add these variables in your ``.env`` file (along with the :ref:`afore .. code-block:: TULEAP_VERSION=15.0-1 - DB_FQDN=some random strong password - REDIS_FQDN=another strong password + DB_FQDN=mysql.example.com + REDIS_FQDN=redis.example.com * ``TULEAP_VERSION`` is the version of Tuleap Enterprise you wish to use. There is no ``latest``, and the version format is either ``15.0`` or ``15.0-1``. * ``DB_FQDN`` is the full name of the machine hosting the Database. @@ -141,6 +120,10 @@ You should add these variables in your ``.env`` file (along with the :ref:`afore 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: @@ -153,20 +136,10 @@ You should add these variables in your ``.env`` file (along with the :ref:`afore - TULEAP_FPM_SESSION_MODE=redis - TULEAP_REDIS_SERVER=${REDIS_FQDN} - nginx: - image: nginx:latest - restart: always - ports: - - 80:80 - - 443:443 - volumes: - - ./nginx/certs:/certs - - ./nginx/nginx.conf:/etc/nginx/nginx.conf - volumes: tuleap-data: -You should put your certificates in ``./nginx/certs`` or else nginx will not boot. +If you want to secure your server and use certificates, you may spawn a Reverse-Proxy in the stack. Run the docker-compose file ``````````````````````````` @@ -181,7 +154,7 @@ Then you can follow the progress of the installation with .. code-block:: bash - $ docker-compose logs -f web + $ docker-compose logs -f tuleap Until you see something like: From cee8abecb5233a40dbd64c510b886c902ff91e85 Mon Sep 17 00:00:00 2001 From: fkozmik <121037513+fkozmik@users.noreply.github.com> Date: Thu, 14 Sep 2023 09:11:54 +0200 Subject: [PATCH 07/11] Update languages/en/installation-guide/docker/intro_docker.rst Co-authored-by: Joris MASSON --- languages/en/installation-guide/docker/intro_docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/languages/en/installation-guide/docker/intro_docker.rst b/languages/en/installation-guide/docker/intro_docker.rst index b7077473..1a682a1e 100644 --- a/languages/en/installation-guide/docker/intro_docker.rst +++ b/languages/en/installation-guide/docker/intro_docker.rst @@ -7,7 +7,7 @@ What for ? 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". +That's the recommended way to install Tuleap, especially if you just want to give it a try. Prerequisites ````````````` From 65c66b8a94f991754911a33a4a993d8ef4d3db56 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Thu, 14 Sep 2023 10:36:47 +0200 Subject: [PATCH 08/11] Streamlined docker Installation Guide. --- .../docker/docker_compose.rst | 20 ++++++--------- .../docker/docker_standalone.rst | 25 +++++++++++-------- .../docker/images-configuration.rst | 2 ++ .../docker/intro_docker.rst | 6 ++++- .../docker/verify_images_authenticity.rst | 10 ++++---- 5 files changed, 33 insertions(+), 30 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 094d8819..74ced8c5 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -7,22 +7,19 @@ The Environment ```````````````` In a special directory (created only for the Tuleap stack), create a ``.env`` file that defines these variables: -.. code-block:: +.. 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 -* ``TULEAP_FQDN`` is the full name of the machine you are going to run Tuleap on. As we saw in pre-requisite section, it should be the name of your docker host either from DNS or at very least defined in ``/etc/hosts`` (will resolve only locally). -* ``MYSQL_ROOT_PASSWORD`` will be the root password of your mysql instance. -* ``TULEAP_SYS_DBPASSWD`` will be the password used by Tuleap application to connect to the database (default user ``tuleapadm``) -* ``SITE_ADMINISTRATOR_PASSWORD`` will be the password of the Tuleap site administrator application user. +Please check the :ref:`environment variables ` to know what they stand for. Notes about passwords: * we recommend at least 20 chars but only alphabetical & numbers, -* they are set at the site initialization only (not updated automatically). +* they are set at the first run only (not updated automatically). Tuleap Community ````````````````` @@ -100,16 +97,13 @@ You first need to authenticate towards Tuleap's registry: You should add these variables in your ``.env`` file (along with the :ref:`aforementioned ones `): -.. code-block:: +.. code-block:: ini TULEAP_VERSION=15.0-1 DB_FQDN=mysql.example.com REDIS_FQDN=redis.example.com -* ``TULEAP_VERSION`` is the version of Tuleap Enterprise you wish to use. There is no ``latest``, and the version format is either ``15.0`` or ``15.0-1``. -* ``DB_FQDN`` is the full name of the machine hosting the Database. -* ``REDIS_FQDN`` is the full name of the machine hosting Redis. - +Please check the :ref:`environment variables ` to know what they stand for. .. code-block:: yaml @@ -181,5 +175,5 @@ Until you see something like: 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 to your environment. -One of the main thing you will want to configure is a proper email relay. \ No newline at end of file +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. \ No newline at end of file diff --git a/languages/en/installation-guide/docker/docker_standalone.rst b/languages/en/installation-guide/docker/docker_standalone.rst index 183cc5c6..84aa64b4 100644 --- a/languages/en/installation-guide/docker/docker_standalone.rst +++ b/languages/en/installation-guide/docker/docker_standalone.rst @@ -1,7 +1,7 @@ Docker Standalone ================= -For anything but tests you should have a dedicated MySQL (**version 8.0**) and Redis (last stable recommended) databases. +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: @@ -12,9 +12,18 @@ At first run you will need to provide some information about the platform you wa * The database application user (typically ``tuleapadm``) password as ``TULEAP_SYS_DBPASSWD`` environment variable * The Tuleap ``admin`` user password as ``SITE_ADMINISTRATOR_PASSWORD`` environment variable - * **WARNING**: You cannot enforce encryption of Redis communication if you enabled Subversion because the underlying code, written in perl, doesn't support encryption. +Please check the :ref:`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 ````````````````` @@ -43,7 +52,7 @@ You can init docker image in command line: -v /srv/path/to/data:/data tuleap/tuleap-community-edition -For future runs you don't need to pass all the environments: +For future runs you don't need to pass all the environment variables: .. code-block:: bash @@ -86,7 +95,7 @@ You must specify the Tuleap tag you want to run (there is no ``:latest`` to avoi -e DB_HOST=db-tuleap.example.com \ -e DB_ADMIN_USER="root" \ -e DB_ADMIN_PASSWORD="a fine password" \ - -v tuleap-data:/data + -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: @@ -94,11 +103,5 @@ The next runs won't need the environment variable so you can restart with: .. code-block:: bash $ docker run -d \ - -v tuleap-data:/data + -v /srv/path/to/data:/data docker.tuleap.org/tuleap-enterprise-edition:11.13-3 - -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) \ No newline at end of file diff --git a/languages/en/installation-guide/docker/images-configuration.rst b/languages/en/installation-guide/docker/images-configuration.rst index 1cd01a11..49153140 100644 --- a/languages/en/installation-guide/docker/images-configuration.rst +++ b/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 ````````````````````` diff --git a/languages/en/installation-guide/docker/intro_docker.rst b/languages/en/installation-guide/docker/intro_docker.rst index 1a682a1e..7095efa3 100644 --- a/languages/en/installation-guide/docker/intro_docker.rst +++ b/languages/en/installation-guide/docker/intro_docker.rst @@ -4,11 +4,15 @@ 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 ````````````` diff --git a/languages/en/installation-guide/docker/verify_images_authenticity.rst b/languages/en/installation-guide/docker/verify_images_authenticity.rst index f778fffd..749a7131 100644 --- a/languages/en/installation-guide/docker/verify_images_authenticity.rst +++ b/languages/en/installation-guide/docker/verify_images_authenticity.rst @@ -8,13 +8,13 @@ publish it. The image is signed using `cosign ` into a file named ``tuleap_docker.pub`` and then running: -.. code-block:: +.. code-block:: bash $ cosign verify -key tuleap_docker.pub tuleap/tuleap-community-edition On success the output will look something like this: -.. code-block:: +.. code-block:: text Verification for tuleap/tuleap-community-edition -- The following checks were performed on each of these signatures: @@ -26,17 +26,17 @@ On success the output will look something like this: Check Tuleap Enterprise image ````````````````````````````` -We sign the Tuleap Enterprise Docker images each time we publish them. The images are signed using `cosign `_. +We sign the Tuleap Enterprise Docker image each time we publish it. The image is signed using `cosign `_. You can verify an image authenticity by :download:`downloading our public key ` into a file named ``tuleap_enterprise_docker.pub`` and then running: -.. code-block:: +.. code-block:: bash $ cosign verify -key tuleap_enterprise_docker.pub docker.tuleap.org/tuleap-enterprise-edition:12.11-2 On success the output will look something like this: -.. code-block:: +.. code-block:: text Verification for docker.tuleap.org/tuleap-enterprise-edition:14.11-4 -- The following checks were performed on each of these signatures: From c49a62be3e999569bc14fb2317032b70821b98f0 Mon Sep 17 00:00:00 2001 From: fkozmik Date: Thu, 14 Sep 2023 10:43:11 +0200 Subject: [PATCH 09/11] Docker Compose Installation guide - Environment Variables need double quotes to parse --- .../installation-guide/docker/docker_compose.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 74ced8c5..09940577 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -9,10 +9,12 @@ In a special directory (created only for the Tuleap stack), create a ``.env`` fi .. 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 + 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 ` to know what they stand for. @@ -99,9 +101,9 @@ You should add these variables in your ``.env`` file (along with the :ref:`afore .. code-block:: ini - TULEAP_VERSION=15.0-1 - DB_FQDN=mysql.example.com - REDIS_FQDN=redis.example.com + TULEAP_VERSION="15.0-1" + DB_FQDN="mysql.example.com" + REDIS_FQDN="redis.example.com" Please check the :ref:`environment variables ` to know what they stand for. From 43935578b81e12f9bf06f496fcabc10b9e9faece Mon Sep 17 00:00:00 2001 From: fkozmik Date: Thu, 14 Sep 2023 11:31:25 +0200 Subject: [PATCH 10/11] Docker installation guide - Note about passwords should be in Images Configuration --- languages/en/installation-guide/docker/docker_compose.rst | 4 ---- .../en/installation-guide/docker/images-configuration.rst | 6 ++++++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index 09940577..b10aa5df 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -18,10 +18,6 @@ Please be aware that you need **double quotes** around your variables in order f Please check the :ref:`environment variables ` to know what they stand for. -Notes about passwords: - -* we recommend at least 20 chars but only alphabetical & numbers, -* they are set at the first run only (not updated automatically). Tuleap Community ````````````````` diff --git a/languages/en/installation-guide/docker/images-configuration.rst b/languages/en/installation-guide/docker/images-configuration.rst index 49153140..be813482 100644 --- a/languages/en/installation-guide/docker/images-configuration.rst +++ b/languages/en/installation-guide/docker/images-configuration.rst @@ -53,6 +53,12 @@ Email Please note that not all plugins can be used with this configuration setting (:ref:`email_relay`) 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 ```````````````` From eaa86416834c092b6abf2218327a8a99722230c2 Mon Sep 17 00:00:00 2001 From: fkozmik <121037513+fkozmik@users.noreply.github.com> Date: Fri, 15 Sep 2023 09:38:16 +0200 Subject: [PATCH 11/11] Update languages/en/installation-guide/docker/docker_compose.rst Co-authored-by: Joris MASSON --- languages/en/installation-guide/docker/docker_compose.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/languages/en/installation-guide/docker/docker_compose.rst b/languages/en/installation-guide/docker/docker_compose.rst index b10aa5df..279fdc8e 100644 --- a/languages/en/installation-guide/docker/docker_compose.rst +++ b/languages/en/installation-guide/docker/docker_compose.rst @@ -25,7 +25,7 @@ Tuleap Community .. warning:: - The following section is meant for test purpose only. The databases (MySQL and Redis) are handled by Docker and it is not a recommend setup. + 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: