.. chill-doc documentation master file, created by
   sphinx-quickstart on Sun Sep 28 22:04:08 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. Copyright (C)  2014-2019 Champs Libres Cooperative SCRLFS
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.3
   or any later version published by the Free Software Foundation;
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled "GNU
   Free Documentation License".

Installation & Usage
####################


Requirements
************

- This project use `docker  <https://docker.com>`_ to be run. As a developer, use `docker-compose <https://docs.docker.com/compose/overview/>`_ 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
********************************

1. Get the code
===============

Clone or download the chill-app project and `cd` into the main directory.


.. code-block:: bash

   git clone https://gitlab.com/Chill-Projet/chill-app.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
=========================

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: 

1. copy the file as ``.env``: ``cp .env.dist .env``
2. you may replace some variables inside ``.env``

**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 <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html#secret-keys>`_.

3. Run the bootstrap script
===========================

This script can be run using `make`

.. code-block:: bash

   make init

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>`_ ; 
3. install the php dependencies
4. build assets


.. note::

   In some cases it can happen that an old image (chill_base_php or chill_php) stored in the docker cache will make the script fail. To solve this problem you have to delete the image and the container, before the make init :

    .. code-block:: bash

       docker-compose images php
       docker rmi -f chill_php:prod
       docker-compose rm php


4. Start the project
====================

.. code-block:: bash

   docker-compose up

**On the first run** (and after each upgrade), you must execute *post update commands* and run database migrations. With a container up and running, execute the following commands:

.. code-block:: bash

   make 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

There are several users available:

- ``center a_social``
- ``center b_social``

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>"
       }
   }


See also "how to switch branch and get new dependencies".


Operations
**********

Build assets
============

run those commands: 

.. code-block:: bash

   make build-assets

How to execute the console ?
============================

.. code-block:: bash

   # if a container is running
   docker-compose exec --user $(id -u) php bin/console
   # if not 
   docker-compose run --user $(id -u) php bin/console

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
   # if not 
   docker-compose run --user $(id -u) php bin/console doctrine:migrations:migrate


How to read the email sent by the program ?
===========================================

Go at ``http://localhost:8005`` and you should have access to mailcatcher.

In case of you should click on a link in the email, be aware that you should remove the "s" from https.

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
   # if not 
   docker-compose run --user $(id -u) php bin/console doctrine:fixtures:load

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
   # if not 
   docker-compose run --user $(id -u) php /bin/bash

How to run composer ?
=====================

.. code-block:: bash

   # if a container is running
   docker-compose exec --user $(id -u) php ./composer.phar
   # if not 
   docker-compose run --user $(id -u) php ./composer.phar

How to access to PGADMIN ?
==========================

Pgadmin is installed with docker-compose.

You can access it at ``http://localhost:8002``.

Credentials:

- login: admin@chill.social
- password: password

How to run tests ?
==================

Tests reside inside the installed bundles. You must `cd` into that directory, download the required packages, and execute them from this place.

**Note**: some bundle require the fixture to be executed. See the dedicated _how-tos_.

Exemple, for running test inside `main` bundle: 

.. code-block:: bash

   # mount into the php image
   docker-compose run --user $(id -u) php /bin/bash
   # cd into main directory
   cd vendor/chill-project/main
   # download deps
   php ../../../composer.phar install
   # run tests
   /vendor/bin/phpunit

How to run webpack interactively
================================

Executing :code:`bash docker-node.sh` will open a terminal in a node container, with volumes mounted.

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.

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:

.. code-block:: json
   {
      "require": {
          "chill-bundles": "dev-<my-branch>@dev"
   }
```

2. mount into the php container, and run `composer update`

Build the documentation API
===========================

A basic configuration of `sami <https://github.com/FriendsOfPhp/Sami>`_ is embedded within the project. 

A configuration file for `phpDocumentor <https://www.phpdoc.org>`_ 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
====================================================================================================================================================================

Run :code:`make build-assets`

Running in production
*********************

Currently, to run this software in production, the *state of the art* is the following :

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

.. warning::

   In production, you **must** set those variables:

   * ``APP_ENV`` to ``prod``
   * ``APP_DEBUG`` to ``false``

   There are security issues if you keep the same variable than for production.


.. _running-production-tips-and-tricks:

Tips and tricks
===============

Operation on database (backups, running custom sql, replication) are easier to set when run outside of a container. If you run into a container, take care of the volume where data are stored.

The PHP sessions are stored inside redis. This is useful if you distribute the traffic amongst different php server: they will share same sessions if a request goes into a different instance of the container.

When the PHP servers are shared across multiple instances, take care that some data is stored into redis: the same redis server should be reachable by all instances.

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 ?
=================================================================

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