From 58a1af0c78d1c64831c082f0ad2316f513007661 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Wed, 5 Oct 2022 09:58:18 +0200 Subject: [PATCH] installation instructions --- docs/source/installation/index.rst | 113 +++++++++++++++++++---------- 1 file changed, 73 insertions(+), 40 deletions(-) diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst index 8d84b795f..9c44d81dd 100644 --- a/docs/source/installation/index.rst +++ b/docs/source/installation/index.rst @@ -21,31 +21,45 @@ Requirements - This project use `docker `_ to be run. As a developer, use `docker-compose `_ to bootstrap a dev environment in a glance. You do not need any other dependencies ; - Make is used to automate scripts. -Installation in development mode -******************************** +Installation +************ + +If you plan to run chill in production: + +1. install it locally first, and check if everything is ok on your local machine; +2. once ready, build the image from your local machine, and deploy them. + +If you want to develop some bundles, the first step is sufficient (until you deploy on production). + 1. Get the code =============== -Clone or download the chill-app project and `cd` into the main directory. +Clone or download the chill-skeleton project and `cd` into the main directory. .. code-block:: bash - git clone https://gitlab.com/Chill-Projet/chill-app.git + git clone https://gitlab.com/Chill-Projet/chill-skeleton-basic.git cd chill-app As a developer, the code will stay on your computer and will be executed in docker container. To avoid permission problem, the code should be run with the same uid/gid from your current user. This is why we get your current user id with the command ``id -u`` in each following scripts. -2. Prepare your variables -========================= +2. Prepare your variables and docker-compose +============================================ -Have a look at the variable in ``.env.dist`` and in ``app/config/parameters.yml.dist`` and check if you need to adapt them. If they do not adapt with your need, or if some are missing: +Have a look at the variable in ``.env`` and check if you need to adapt them. If they do not adapt with your need, or if some are missing: -1. copy the file as ``.env``: ``cp .env.dist .env`` +1. copy the file as ``.env.local``: ``cp .env .env.local`` 2. you may replace some variables inside ``.env`` +Prepare also you docker-compose installation, and adapt it to your needs: + +1. If you plan to deploy on dev, copy the file ``docker-compose.override.dev.template.yml`` to ``docker-compose.override.yml``. +2. adapt to your needs. + + **Note**: If you intend to use the bundle ``Chill-Doc-Store``, you will need to configure and install an openstack object storage container with temporary url middleware. You will have to configure `secret keys `_. 3. Run the bootstrap script @@ -64,6 +78,17 @@ This script will : 3. install the php dependencies 4. build assets +.. warning:: + + The script will work only if the binary ``docker-compose`` is located into your ``PATH``. If you use ``compose`` as a docker plugin, + you can simulate this binary by creating this file at (for instance), ``/usr/local/bin/docker-compose`` (and run ``chmod +x /usr/local/bin/docker-compose``): + + .. code-block:: bash + + #!/bin/bash + + /usr/bin/docker compose "$@" + .. note:: @@ -87,13 +112,20 @@ This script will : .. code-block:: bash - make migrate + # mount into to container + ./docker-php.sh + # and load fixtures + bin/console doctrine:migrations:migrate + Chill will be available at ``http://localhost:8001.`` Currently, there isn't any user or data. To add fixtures, run .. code-block:: bash - docker-compose exec --user $(id -u) php bin/console doctrine:fixtures:load --purge-with-truncate + # mount into to container + ./docker-php.sh + # and load fixtures + bin/console doctrine:fixtures:load --purge-with-truncate There are several users available: @@ -112,16 +144,18 @@ Add a Gitlab token to ensure that you get always the source code: 1. generate a gitlab token there: https://gitlab.com/oauth/token 2. run this command (in php container, at the app's root): :code:`composer config gitlab-token.gitlab.com ` -The auth token should appears now in the directory :code:`.composer`: + The auth token should appears now in the directory :code:`.composer`: -.. code-block: bash + .. code-block: bash + + $ cat .composer/auth.json + { + "gitlab-token": { + "gitlab.com": "" + } + } +3. run ``composer update`` again (into the php container) - $ cat .composer/auth.json - { - "gitlab-token": { - "gitlab.com": "" - } - } See also "how to switch branch and get new dependencies". @@ -145,7 +179,7 @@ How to execute the console ? .. code-block:: bash # if a container is running - docker-compose exec --user $(id -u) php bin/console + ./docker-php.sh # if not docker-compose run --user $(id -u) php bin/console @@ -155,7 +189,8 @@ How to create the database schema (= run migrations) ? .. code-block:: bash # if a container is running - docker-compose exec --user $(id -u) php bin/console doctrine:migrations:migrate + ./docker-php.sh + bin/console doctrine:migrations:migrate # if not docker-compose run --user $(id -u) php bin/console doctrine:migrations:migrate @@ -173,7 +208,8 @@ How to load fixtures ? (development mode only) .. code-block:: bash # if a container is running - docker-compose exec --user $(id -u) php bin/console doctrine:fixtures:load + ./docker-php.sh + bin/console doctrine:fixtures:load # if not docker-compose run --user $(id -u) php bin/console doctrine:fixtures:load @@ -183,7 +219,7 @@ How to open a terminal in the project .. code-block:: bash # if a container is running - docker-compose exec --user $(id -u) php /bin/bash + ./docker-php.sh # if not docker-compose run --user $(id -u) php /bin/bash @@ -193,21 +229,22 @@ How to run composer ? .. code-block:: bash # if a container is running - docker-compose exec --user $(id -u) php ./composer.phar + ./docker-php.sh + composer # if not - docker-compose run --user $(id -u) php ./composer.phar + docker-compose run --user $(id -u) php composer How to access to PGADMIN ? ========================== -Pgadmin is installed with docker-compose. +Pgadmin is installed with docker-compose, and is available **only if you uncomment the appropriate lines into ``docker-compose.override.yml``. You can access it at ``http://localhost:8002``. Credentials: -- login: admin@chill.social -- password: password +- login: from the variable you set into ``docker-composer.override.yml`` +- password: same :-) How to run tests ? ================== @@ -221,13 +258,15 @@ Exemple, for running test inside `main` bundle: .. code-block:: bash # mount into the php image - docker-compose run --user $(id -u) php /bin/bash + ./docker-php.sh # cd into main directory - cd vendor/chill-project/main + cd vendor/chill-project/chill-bundles # download deps - php ../../../composer.phar install + git submodule init + git submodule update + composer install # run tests - /vendor/bin/phpunit + bin/phpunit src/Bundle/path/to/your/test How to run webpack interactively ================================ @@ -253,13 +292,6 @@ In order to do that without pain, use those steps: 2. mount into the php container, and run `composer update` -Build the documentation API -=========================== - -A basic configuration of `sami `_ is embedded within the project. - -A configuration file for `phpDocumentor `_ is present. - Error `An exception has been thrown during the rendering of a template ("Asset manifest file "/var/www/app/web/build/manifest.json" does not exist.").` on first run ==================================================================================================================================================================== @@ -273,7 +305,8 @@ Currently, to run this software in production, the *state of the art* is the fol 1. Run the software locally and tweak the configuration to your needs ; 2. Build the image and store them into a private container registry. This can be done using :code:`make build-and-push-image`. - To be sure to target the correct container registry, you have to adapt the values ``IMAGE_NGINX`` and ``IMAGE_PHP`` date in the ``.env`` file. + To be sure to target the correct container registry, you have to adapt the image names into your ``docker-compose.override.yml`` file. +3. Push the image on your registry, or upload them to the destination machine using ``docker image save`` and ``docker image load``. 3. Run the image on your production server, using docker-compose or eventually docker stack. You have to customize the variable set in docker-compose. See also the :ref:`running-production-tips-and-tricks` below. @@ -305,7 +338,7 @@ It is worth having an eye on the configuration of logstash container. Design principles ***************** -Why the DB URL is set in environment, and not in parameters.yml ? +Why the DB URL is also set in environment, and not in .env file ? ================================================================= Because, at startup, a script does check the db is up and, if not, wait for a couple of seconds before running ``entrypoint.sh``. For avoiding double configuration, the configuration of the PHP app takes his configuration from environment also (and it will be standard in future releases, with symfony 4.0).