Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-06-07 18:44:08 +00:00
Code Issues Actions Projects Releases Wiki Activity

installation instructions

Browse Source
This commit is contained in:
Julien Fastré 2022-10-05 09:58:18 +02:00
parent 99b261b1d7
commit 58a1af0c78
1 changed files with 73 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
docs/source/installation/index.rst
View File

@ -21,31 +21,45 @@ 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
********************************
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 <https://docs.openstack.org/swift/latest/api/temporary_url_middleware.html#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 <your token>`
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": "<your token>"
}
}
3. run ``composer update`` again (into the php container)
$ cat .composer/auth.json
{
"gitlab-token": {
"gitlab.com": "<your token>"
}
}
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 <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
====================================================================================================================================================================
@ -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).