Skip to content

Latest commit

 

History

History
306 lines (210 loc) · 9.56 KB

technical.md

File metadata and controls

306 lines (210 loc) · 9.56 KB
Raw

Install

Requirements

  • git
  • make
  • docker >= 18.06
  • docker-compose >= 1.23

Linux and OS X

git clone git@github.com:crf-devs/resop.git && cd resop
make

Windows

  • Install WSL2
  • Enable Docker support for WSL2
  • Checkout project directly within WSL, using a native windows directory as a project root will cause massive performances issues and issues with watchers ( i.e : yarn encore ).
  • Run Linux build steps from WSL

Note : PHPStorm do not currently provide a good native integration, with WSL2, you will mainly need to open the directory from WSL directory, usually the name is \wsl$\ located at same level at c/. See : IDEABKL-7908 and IDEA-171510

Without Docker

Disclaimer: This method is not recommended, please prefer the Docker way if you can.

If you don't want to use the provided Docker stack (such a weird idea, but why not), you can easily run the stack as in old times, with you own php & node & prostgres services

Requirements

  • PHP 7.4
  • Node >= 13, Yarn >= 1.22
  • PostgreSQL 11
  • Symfony CLI

Install

Create a .env.local file and set the database url:

DATABASE_URL=postgresql://<USER>:<PASSWORD>@<HOST>/<DB>?serverVersion=11&charset=utf8

From the Makefile, copy & run the following tasks commands manualy (you must remove the bin/tools or bin/node-tools prefix):

  • vendors
  • webpack-build-dev
  • init-db

Then, you can serve the project:

symfony server:start

If you want to watch JS & CSS changes, run:

yarn encore dev --watch

That's it :) If you need any other command, you can look for it in the Makefile.

With Vagrant + VirtualBox

If you want to run the stack with Vagrant, you can have a look to this PR in order to find a working config.

Run

After the make command, go to http://resop.vcap.me:7500/, or https://resop.vcap.me:7583/ for https (self signed certificate).

If you want to run a symfony or a php command: bin/tools <command>, example: bin/tools bin/console

Run : after a first install

You don't need to build all the stack every time. If there is no new vendor, you can simply run:

# If you want to start the stack and reset the DB
make start

# If you want to start the stack whithout reseting the DB
make start-preserve-db

Access

The project is using a Traefik proxy in order to allow access to all the HTTP services of the project. This service is listening on the 7500 port of the host. The *.vcap.me domain names are binded on localhost. In order to use them offline, you only have to add a 127.0.0.1 adminer.vcap.me resop.vcap.me traefik.vcap.me line on your /etc/hosts file.

Stack

Caution: the traefik proxy will only serve healthy containers. The api container can be unaccessible before the first healthcheck (5s).

Database

A PostgreSQL server is provided by the docker-compose file, as well as an adminer web interface.

  postgres:
    environment:
      - POSTGRES_DB=resop
      - POSTGRES_USER=resop
      - POSTGRES_PASSWORD=postgrespwd

Web interface

If you want to access the data, the easiest way is to use the adminer service from your browser.

Host port binding

If you need to access the DB from your host, you must uncomment the following lines in your docker-compose.override.yml file:

services:
  # ...
  postgres:
    # ...
    ports:
      - '5432:5432'

Then, run docker-compose up -d postgres. The DB is now available on the localhost:5432 port!

Fixtures

If you want to load huge amount of data, for example to test the performances, run the following command in the fpm container:

bin/tools sh -c "APP_NB_USERS=15 APP_NB_AVAILABILITIES=6 bin/console doctrine:fixtures:load --purge-with-truncate --no-interaction"
  • APP_NB_USERS: number of users per organization (default: 10)
  • APP_NB_AVAILABILITIES: number of days on which generating availabilities per user (default: 3)

HTTPS

The nginx container is available over HTTPS. This url must be used in order to use Facebook, Gmaps, camera...

Before commiting

Please always run the following commands before commiting, or the CI won't be happy ;-)

make fix-cs
make test

Hint: you can run make fix-cs-php instead of make fix-cs if you are one of those backend devs who don't touch any css or js file.

Tests

make test # Run all tests except coverage
make test-cs # php-cs-fixer + phpcs + twig & yaml & js & scss lint
make test-advanced # phpstan
make test-behat # behat
make test-unit # phpunit
make test-coverage # phpunit + behat

PHP

Tools & commands

As the php-fpm docker container doesn't contain any dev tool as composer, all dev commands must be run on the tools container. For example:

bin/tools composer
bin/tools bin/console cache:clear
bin/tools # to open a shell on the tools container

Blackfire

In order to profile the php app with Blackfire, you need to have a Blackfire account, then:

  • Uncomment the blackfire service in the docker-compose.override.yml file
  • Uncomment the blackfire env var for the fpm service in the docker-compose.override.yml file
  • Add your credentials in the docker-compose.override.yml file
  • docker-compose up -d --build --force-recreate fpm blackfire
  • That's it, you can profile the app!

Node

A node container is available in order to run yarn commands for webpack encore:

bin/node-tools yarn encore dev

webpack-build-dev
make webpack-watch-dev

Built docker images

Every time a new commit is pushed onto master, the following Docker images are built:

Every time a new release is created, the following Docker images are built:

Usage in production

This is an example of docker-compose.yml file with parameters you should use for production:

services:
  resop:
    image: crfdevs/resop:release-latest
    environment:
      - INIT_DB=true # Run migrations on start
      - DANGEROUSLY_LOAD_FIXTURES=false # Reset DB and load fixtures on start
      - "DATABASE_URL=postgresql://<USER>:<PASSWORD>@<URL>/<DB>?serverVersion=11&charset=utf8"

The image exposes a :80 port.

If you want to initialize the DB with production data, run the following command into the container:

bin/console app:load-organizations

Usage in production with nginx and fpm separated containers

If you want to have one image for nginx and an other one for fpm (one process per container), you can update the build workflow:

jobs:
    build:
        steps:
          # - Checkout and generate version variables

            -   name: Build the Docker images
                run: |
                    docker build -t ${CI_REGISTRY_IMAGE}:fpm-${CI_COMMIT_REF_SLUG} -f docker/php-flex/Dockerfile --target withsources-fpm --build-arg BUILD_TAG=${BUILD_TAG} .
                    docker run --rm -v $(pwd):/host ${CI_REGISTRY_IMAGE}:fpm-${CI_COMMIT_REF_SLUG} mv -f /srv/public/build /host/public
                    docker build -t ${CI_REGISTRY_IMAGE}:nginx-${CI_COMMIT_REF_SLUG} -f docker/nginx/Dockerfile --target withsources .

            -   name: Push the new Docker image
                run: |
                    docker push ${CI_REGISTRY_IMAGE}:fpm-${CI_COMMIT_REF_SLUG}
                    docker push ${CI_REGISTRY_IMAGE}:nginx-${CI_COMMIT_REF_SLUG}

Then, you can use the two images:

services:
  nginx:
    image: crfdevs/resop:nginx-0.1
    depends_on:
      - fpm
    environment:
      - "FPM_ENDPOINT=fpm:9000"

  fpm:
    image: crfdevs/resop:npm-0.1
    environment:
      - INIT_DB=true # Run migrations on start
      - DANGEROUSLY_LOAD_FIXTURES=false # Reset DB and load fixtures on start
      - "DATABASE_URL=postgresql://<USER>:<PASSWORD>@<URL>/<DB>?serverVersion=11&charset=utf8"

Override the default configuration and/or translation

The project includes its default configuration and translations.

To override the default configuration, create the config/config.yaml file and override any parameter you want:

# config/config.yaml
parameters:
  app.slot_interval: '+4 hours'
  app.locale: it # to change the default locale

To override the default translations, create the config/translations/messages.fr.yaml file and set any translation you want:

# config/translations/messages.fr.yaml
project:
  description: Description de votre projet
  name: Nom de votre projet

To translate the project in another language than french, update the default locale from the configuration file, and create the translation file: config/translations/messages.it.yaml.