component_info RFC

component_info RFC

Problem

• Configuration and file layout methods and conventions have changed from Symfony 3 to Symfony 4
• Assetic is deprecated
• Transitioning from php56 tot php72

Goals

• Transitioning the Stepup components from php56 with Symfony 3 and assetic to php72 with Symfony 4 and encore while continuing to use the same Stepup-Deploy and Stepup-Build
• Standardise the component layout, build method and installation method so there is a little variation as is practal. I.e. reduce complexity

Solution

Standardise the layout, configuration, installation and build methods and requirements and explicitly specify in the component what these requirements are. In Stepup-Deploy specify for each component whether it uses PHP7.2 or PHP 5.6, and whether it uses the Symfony 3 or Symfony 4 layout. This is relevant for the vhost configuration performed by the app role. Each vhost publishes how it is configured by publisching its configuration on a known URL. This allows Stepup-Build and Stepup-Deploy to be able to handle components with different file layout, build and installation requirements and to verify that the vhost configuration matches the component requirements during a deploy.

The build and deploy configuration of a component is stored in a file called component_info in the root of each component. Stepup-Build and Stepup-Deploy read this file so they know what to do. When the file is not present component dependent defaults are used that match the component requirements of release-17.

The vhost configuration is published at http://<component_vhost_name>/vhost_component_info

component_info specification

component_info is stored in the root of the component. When a new version of a component is releases a component_info MUST be added. The following lines are allowed in this file:

• empty lines (newline only)
• Lines starting with "#" (comments)
• Lines with "parameter=value" in bash format, so no whites pace around the "="

Supported parameters and values are allowed:

• PHP_VERSION=56 (default)
• PHP_VERSION=72
• SYMFONY_VERSION=3 (default for all components except Stepup-WebAuthn and stepup-gssp-exmple)
• SYMFONY_VERSION=4
• ASSETIC=yes (default for GW, SS and RA)
• ASSETIC=no (default for others)
• ENCORE=yes (default for stepup-tiqr, stepup-WebAuthn, stepup-demo-gssp)
• ENCORE=no (default for others)
• COMPOSER_VERSION=1 (default)
• COMPOSER_VERSION=2

Description:

• PHP_VERSION: The PHP version required to run the component
• SYMFONY_VERSION: The symfony version used by the component
• ENCORE: Whether to run yarn encore during build
• ASSETIC: Whether to run composer bootstrap and assetic commands during deploy
• COMPOSER_VERSION: The major version of composer to use during build

PHP_VERSION

The PHP interpreter version to be used to build/install/run the component. "56" or "72".

SYMFONY_VERSION

The Symfony version determines the file layout, configuration method and webserver interface of the component. "3" or "4".

Symfony 3

• console location: /app/console
• document root: /web
• index:
  • production: /web/app.php
  • develop: /web/app_dev.php
• configuration location (for files like certificates, keys and parameters.yml): /app/config/
• cache location: /app/cache

During deploy parameters.yml and configuration files are written by Ansible from a component specific templates in Stepup-Deploy. For each .yml configuration file, a well documented .dist file MUST exist that contains suitable configuration for installing the component.

Symfony 4

• console location: /bin/console
• document root: /public
• index: /public/index.php
• configuration location (for files like certificates, keys and parameters.yml): /config/
• cache location: /var/cache

The component MUST contain /.env with defaults for PRODUCTION and BUILD/INSTALL (i.e. APP_ENV=prod). The parameters in this file MUST be well documented. During deploy /.env.local is written by Ansible from a component specific template in Stepup-Deploy that contains the configuration for the component. The template adds:

• APP_ENV=prod for production install
• APP_ENV=dev for development install

Component specific parameters.yml files and configuration files are added same as for Symfony 3.

Components are build with:

1. SYMFONY_ENV=build; composer install --prefer-dist --ignore-platform-reqs --no-dev --no-interaction --optimize-autoloader
2. frontend processing like yarn encore stuff as specified
3. composer archive --dir=${OUTPUT_DIR} --file=${NAME} --format=tar --no-interaction

You MUST add a archive to your composer.json to exclude and include directories or files in the tarball. See https://getcomposer.org/doc/04-schema.md#archive for details. E.g.

    "archive": {
        "exclude": ["/node_modules", "!/var/bootstrap.php.cache", "!/web/build", "!/web/bundles"]
    }

Components are installed (deployed) in production by:

1. untarring the archive
2. Clear cache: console cache:clear --env=prod --no-dev --no-warmup
3. writing all configuration files, .env files from templates and putting certificates and keys in place
4. Warmup cache: console cache:clear --env=prod --no-dev

http://<vhost_name>/vhost_component_info specification

The results of this URL are configured statically in the vhost configuration and is updated when the app role from the site.yml playbook is run. This URL returns the vhost configuration in JSON format. E.g. {"SYMFONY_VERSION": 3, "PHP_VERSION": 72, "VHOST_NAME": "<vhost_name>"}\n'

PHP_VERSION

The PHP interpreter version to be used to build/install/run the component: "56" or "72"

SYMFONY_VERSION

The Symfony version determines the file layout, configuration method and webserver interface of the component. "3" or "4".

VHOST_NAME

Contains the DNS name of the responding vhost