Skip to content

Install Chill for production with or without adding personal features

Chill is a set of "bundles" for a symfony app.

To run Chill in production or add new features to it (without merging those features to the chill core), you must create a symfony app, and eventually add those features into your app.

Once you are happy with the configuration, you should follow the dedicated instructions of how to go into production for Symfony apps .

Install a new app

Install required dependencies:

  • jq: https://jqlang.org/ (install it through your package manager);
  • php, minimal version: 8.4;
  • composer: https://getcomposer.org/download/
  • symfony-cli: https://symfony.com/download
  • docker with the plugin compose: https://docs.docker.com/engine/install/ and https://docs.docker.com/compose/install/

Initialize the project and it's dependencies

   symfony new --version=5.4 my_chill_project
   cd my_chill_project

We strongly encourage you to initialize a git repository at this step, to track further changes. 

   # add the flex endpoints required for custom recipes
   `cat <<< "$(jq '.extra.symfony += {"endpoint": ["flex://defaults", "https://gitlab.com/api/v4/projects/57371968/repository/files/index.json/raw?ref=main"]}' composer.json)" > composer.json`
   # install chill and some dependencies
   `symfony composer require -W chill-project/chill-bundles ^3.7.1 champs-libres/wopi-lib dev-master@dev champs-libres/wopi-bundle dev-master@dev symfony/amqp-messenger`

We encourage you to accept the inclusion of the "Docker configuration from recipes": this is the documented way to run the database. You must also accept to configure recipes from the contrib repository, unless you want to configure the bundles manually).

   # fix some configuration
   ./post-install-chill.sh
   # populate the cache for the first time. This is necessary to dump some translation files, required for the asset compilation
   symfony console cache:clear
   # install node dependencies
   npm install
   # and compile assets
   npm run build

If you encounter this error during asset compilation (npm run build) (repeated multiple times):

  [tsl] ERROR in /tmp/chill/v1/public/bundles/chillcalendar/types.ts(2,65)
    TS2307: Cannot find module '../../../ChillMainBundle/Resources/public/types' or its corresponding type declarations.

run:

  rm -rf public/bundles/*

Then restart the compilation of assets (npm run build)

Configure your project

You should read the configuration files in chill/config/packages carefully, especially if you have custom developments. But most of the time, this should be fine.

You have to configure some local variables, which are described in the .env file. The secrets should not be stored in this .env file, but instead using the secrets management tool ](https://symfony.com/doc/current/configuration/secrets.html) or in the.env.local` file, which should not be committed to the git repository.

You do not need to set variables for the smtp server, redis server and relatorio server, as they are generated automatically by the symfony server, from the docker compose services.

The required variables are:

  • the ADMIN_PASSWORD;
  • the OVHCLOUD_DSN variable;
ADMIN_PASSWORD

You can generate a hashed and salted admin password using the command: symfony console security:hash-password <your password> 'Symfony\Component\Security\Core\User\User'

Then, you can either:

  • add this password to the .env.local file, you must escape the character $: if the generated password is $2y$13$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm, your .env.local file will be:
   ADMIN_PASSWORD=\$2y\$13\$iyvJLuT4YEa6iWXyQV4/N.hNHpNG8kXlYDkkt5MkYy4FXcSwYAwmm
   # note: if you copy-paste the line above, the password will be "admin".
  • add the generated password to the secrets manager (note: you must add the generated hashed password to the secrets env, not the password in clear text).
OVHCLOUD_DSN and sending SMS messages

This is a temporary dependency, for ensuring compatibility for previous behaviour.

You can set it to null://null if you do not plan to use sending SMS.

OVHCLOUD_DSN=null://null

If you plan to do it, you can configure the notifier component `as described in the symfony documentation.

Some environment variables are available for the JWT authentication bundle in the .env file.

Prepare database, messenger queue, and other configuration

To continue the installation process, you will have to run migrations:

   # start databases and other services
   docker compose up -d
   # the first start, it may last some seconds, you can check with docker compose ps
   # run migrations
   symfony console doctrine:migrations:migrate
   # setup messenger
   symfony console messenger:setup-transports
   # prepare some views
   symfony console chill:db:sync-views
   # load languages data
   symfony console chill:main:languages:populate
   # generate jwt token, required for some api features (webdav access, ...)
   symfony console lexik:jwt:generate-keypair

If you encounter this error:

No transport supports the given Messenger DSN.

Please check that you installed the package symfony/amqp-messenger.

Start your web server locally

At this step, Chill will be ready to be served locally, but without any configuration. You can run the project locally using the `local symfony server ](https://symfony.com/doc/current/setup/symfony_server.html):

   # see the whole possibilities at https://symfony.com/doc/current/setup/symfony_server.html
   symfony server:start -d

If you need to test the instance with accounts and some basic configuration, please install the fixtures (see below).

Add capabilities for dev

If you need to add custom bundles, you can develop them in the src/ directory, like for any other symfony project. You can rely on the whole chill framework, meaning there is no need to add them to the original chill-bundles.

You will require some bundles to have the following development tools:

  • add fixtures
  • add profiler and debug bundle

Install fixtures

   # generate fixtures for chill
   symfony composer require --dev doctrine/doctrine-fixtures-bundle nelmio/alice
   # now, you can generate fixtures (this will reset your database)
   symfony console doctrine:fixtures:load

This will generate user accounts, centers, and some basic configuration.

The accounts created are: center a_social, center b_social, center a_direction, ...

The full list is visible in the "users" table: docker compose exec database psql -U app -c "SELECT username FROM users".

The password is always password.

The fixtures are not fully functional. See the `corresponding issue ](https://gitlab.com/Chill-Projet/chill-bundles/-/issues/280).

Add web profiler and debugger

   symfony composer require --dev symfony/web-profiler-bundle symfony/debug-bundle

Working on chill bundles

If you plan to improve the chill-bundles repository, that's great!

It would be better to follow the instruction about development . But if those features are deeply linked to some dev you made in the app, it can be easier to develop within the [vendor/` directory.

You will have to download chill-bundles as a git repository (and not as an archive, which is barely editable).

In your composer.json file, add these lines:

    {
        "config": {
   +        "preferred-install": {
   +            "chill-project/chill-bundles": "source",
                "*": "dist"
   +         }
        }

Then, run symfony composer reinstall chill-project/chill-bundles to re-install the package from source.

Update

In order to update your app, you must update dependencies:

  • for chill-bundles, you can set the last version ](https://gitlab.com/Chill-Projet/chill-bundles/-/releases) manually in the [composer.json file, or set the version to ^3.0.0 and run symfony composer update regularly
  • run composer update and npm update to maintain your dependencies up-to-date.

After each update, you must update your database schema:

   symfony console doctrine:migrations:migrate
   symfony console chill:db:sync-views

Commit and share your project

If multiple developers work on a project, you can commit your symfony project and share it with other people.

When another developer clones your project, they will have to:

  • run symfony composer install and npm install to install the same dependencies as the initial developer;
  • run npm run build to compile assets;
  • copy any possible variables from the .env.local files;
  • start the docker compose stack, using docker compose, and run migrations, set up transports, and prepare chill db views (see the corresponding command above)

Operations

Build assets

run those commands:

   # for production (or in dev, when you don't need to work on your assets and need some speed)
   npm run build
   # in dev, when you want to reload the assets on each changes
   npm run watch

How to execute the console ?

   # start the console with all required variables
   symfony console
   # you can add your command after that:
   symfony console list

How to generate documents

Documents are generated asynchronously by consuming messages.

You must generate them using a dedicated process:

symfony console messenger:consume async priority

To avoid memory issues, we encourage you to also use the --limit parameter of the command.

How to read emails sent by the program ?

In development, there is a built-in "mail catcher". Open it with symfony open:local:webmail

How to run cron-jobs ?

Some commands must be executed in cron jobs . To execute them:

symfony console chill:cron-job:execute

What about materialized views ?

There are some materialized views in chill, to speed up some complex computations in the database.

In order to refresh them, run a cron job or refresh them manually in your database.

This applies to view_chill_main_address_reference, which backs the address search: it is not refreshed automatically, so addresses imported since the last manual refresh will not be found. Switching the address search to Meilisearch (below) removes that maintenance task.

Searching addresses with Meilisearch (optional)

By default the address reference search reads the view_chill_main_address_reference materialized view. You may instead run it on Meilisearch, which reindexes itself after every address import, tolerates typos, and ignores case and accents.

It is optional: without any configuration Chill keeps using the database.

  1. Run a Meilisearch server and point Chill at it:
MEILISEARCH_URL=http://meilisearch:7700
MEILISEARCH_MASTER_KEY=<your key>
# Only when several Chill instances share one Meilisearch server — without
# distinct prefixes, a rebuild from one instance wipes the others' indexes.
MEILISEARCH_INDEX_PREFIX=
  1. Select the driver in config/packages/chill.yaml:
chill_main:
    search:
        address_reference:
            driver: 'meilisearch'

This is a compile-time setting (it selects a service alias), so it cannot be driven by an environment variable, and the cache must be cleared afterwards.

  1. Build the indexes once:
php bin/console chill:search:index-address-reference

Afterwards the indexes are rebuilt automatically at the end of every address import, with a daily cron job as a safety net. Rebuilds are written to a temporary index and swapped in, so searches keep working throughout.

To go back, set driver to db and refresh the materialized view — it is never dropped.

Troubleshooting

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

Build assets, see above.

Go to 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 it in a private container registry.

In production, you must set these variables:

  • APP_ENV to prod
  • APP_DEBUG to false

There are security issues if you keep the same variables as for production.

Going further