more explanation for installation instructions

docs/source/installation/index.rst

@@ -14,6 +14,13 @@
 Installation & Usage
 ####################
 
+.. toctree::
+   :maxdepth: 2
+
+   prod.rst
+   prod-calendar-sms-sending.rst
+   msgraph-configure.rst
+
 
 Requirements
 ************
@@ -46,6 +53,35 @@ Clone or download the chill-skeleton project and `cd` into the main directory.
 
 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 composer to download the sources
+===========================================
+
+As you are running in dev, you must configure an auth token for getting the source code.
+
+.. warning
+
+   If you skip this part, the code will be downloaded from dist instead of source (with git repository). You will probably replace the source manually, but the next time you will run ```composer update```, your repository will be replaced and you might loose something.
+
+1. Create a personal access token from https://gitlab.com/-/profile/personal_access_tokens, with the `read_api` scope.
+2. add a file called ```.composer/auth.json``` with this content:
+
+   .. code-block:: json
+
+      {
+        "gitlab-token": {
+            "gitlab.com": "glXXX-XXXXXXXXXXXXXXXXXXXX"
+        }
+      }
+
+2. Prepare your variables and environment
+=========================================
+
+Copy ```docker-compose.override.dev.yml``` into ```docker-compose.override.yml```
+
+.. code-block:: bash
+
+   cp docker-compose.override.dev.template.yml docker-compose.override.yml
+
 2. Prepare your variables and docker-compose
 ============================================
 
@@ -74,7 +110,7 @@ This script can be run using `make`
 This script will :
 
 1. force docker-compose to, eventually, pull the base images and build the image used by this project ;
-2. run an install script to download `composer <https://getcomposer.org>`_ ; 
+2. run an install script to download `composer <https://getcomposer.org>`_ ;
 3. install the php dependencies
 4. build assets
 
@@ -136,30 +172,6 @@ The password is always ``password``.
 
 Now, read `Operations` below.
 
-Prepare for development
-***********************
-
-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 <your token>`
-
-   The auth token should appears now in the directory :code:`.composer`:
-
-   .. code-block: bash
-
-      $ cat .composer/auth.json
-      {
-          "gitlab-token": {
-              "gitlab.com": "<your token>"
-          }
-      }
-3. run ``composer update`` again (into the php container)
-
-
-
-See also "how to switch branch and get new dependencies".
-
 
 Operations
 **********
@@ -167,7 +179,7 @@ Operations
 Build assets
 ============
 
-run those commands: 
+run those commands:
 
 .. code-block:: bash
 
@@ -180,7 +192,7 @@ How to execute the console ?
 
    # if a container is running
    ./docker-php.sh
-   # if not 
+   # if not
    docker-compose run --user $(id -u) php bin/console
 
 How to create the database schema (= run migrations) ?
@@ -191,7 +203,7 @@ How to create the database schema (= run migrations) ?
    # if a container is running
    ./docker-php.sh
    bin/console doctrine:migrations:migrate
-   # if not 
+   # if not
    docker-compose run --user $(id -u) php bin/console doctrine:migrations:migrate
 
 
@@ -210,7 +222,7 @@ How to load fixtures ? (development mode only)
    # if a container is running
    ./docker-php.sh
    bin/console doctrine:fixtures:load
-   # if not 
+   # if not
    docker-compose run --user $(id -u) php bin/console doctrine:fixtures:load
 
 How to open a terminal in the project
@@ -220,7 +232,7 @@ How to open a terminal in the project
 
    # if a container is running
    ./docker-php.sh
-   # if not 
+   # if not
    docker-compose run --user $(id -u) php /bin/bash
 
 How to run composer ?
@@ -231,7 +243,7 @@ How to run composer ?
    # if a container is running
    ./docker-php.sh
    composer
-   # if not 
+   # if not
    docker-compose run --user $(id -u) php composer
 
 How to access to PGADMIN ?
@@ -253,7 +265,7 @@ Tests reside inside the installed bundles. You must `cd` into that directory, do
 
 **Note**: some bundle require the fixture to be executed. See the dedicated _how-tos_.
 
-Exemple, for running test inside `main` bundle: 
+Exemple, for running test inside `main` bundle:
 
 .. code-block:: bash
 
@@ -278,10 +290,14 @@ How to switch the branch for chill-bundles, and get new dependencies
 
 During development, you will switch to new branches for chill-bundles. As long as the dependencies are equals, this does not cause any problem. But sometimes, a new branch introduces a new dependency, and you must download it.
 
+.. warning::
+
+   Ensure that you have gitlab-token ready before updating your branches. See above.
+
 In order to do that without pain, use those steps:
 
 0. Ensuire you have a token, set
-1. at the app's root, update the `composer.json` to your current branch:
+1. at the app's root, update the ``composer.json`` to your current branch:
 
 .. code-block:: json
 
@@ -290,7 +306,7 @@ In order to do that without pain, use those steps:
           "chill-bundles": "dev-<my-branch>@dev"
    }
 
-2. mount into the php container, and run `composer update`
+2. mount into the php container (``./docker-php.sh``), and run ``composer update``
 
 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
 ====================================================================================================================================================================
@@ -304,7 +320,7 @@ 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 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.