Pipeline Configuration file

ReadyMage supports user defined configuration file that can inject various actions into different points of build/deploy pipeline or customize existing pipeline logic.

Used terms

Vanilla Magento theme - a theme which uses Magento built in mechanisms of theme server-side compilation. For example Magento/Luma.

How to use

Add the readymage.yaml file to Magento 2 root folder. It's the folder which contains base Magento 2composer.* files.

├── 📁 app
├── 📄 composer.json
├── 📄 composer.lock
└── 📄 readymage.yaml

Examples

Default

readymage.yaml

schema_version: 1.0.0
environments:
- name: readymage-test
  build:
    themes:
      all: 
	area: all
	languages: [ 'en_US' ]
	scandipwa/theme:
     area: frontend
	playbook: scandipwa
	directory: scandipwa
	languages: [ 'en_US' ]

Scenario: You always want to generate static files for all available themes.

Build speed optimized

readymage.yaml

schema_version: 1.0.0
environments:
- name: readymage-test
  build:
    themes:
      Magento/backend:
        area: adminhtml
        languages: [ 'en_US' ]
      scandipwa/theme:
        area: frontend
        playbook: scandipwa
        directory: scandipwa
        languages: [ 'en_US' ]

Scenario: You know which exact themes are used in the website and need static file generation, thus saving time on the build phase by not generating files for themes that are not going to be used.

Using post build hook

readymage.yaml

schema_version: 1.0.0
environments:
- name: readymage-test
  build:
    hooks:
      post_build:
      - copy:
          app/etc/config.php: scandipwa/config-copy.php
          scandipwa/config-copy.php: scandipwa/config-copy2.php
          scandipwa/config-copy2.php: scandipwa/config-copy-move.php
      - move:
          scandipwa/config-copy-move.php: scandipwa/config-move.php
      - symlink:
          scandipwa/config-symlink.php: scandipwa/config-copy.php
          scandipwa/config-symlink-persistent.php: persistent:config-symlink-perst.php

Scenario: You need to execute some actions after automated build phase has completed.

Using post deploy hook

schema_version: 1.0.0
environments:
- name: readymage-test
  build:
    ...
  deploy:
    hooks:
      post_deploy:
        - php:
            command: bin/magento indexer:reindex
        - curl:
            directory: /mnt/
            filename: <filename>
            url: <download-link>

Scenario: You need to execute some actions after deployment has completed.

Notes:

1. directory should be and absolute path that refers to the /mnt directory to be able to access the downloaded file from all pods.

2. Indentation is important. You have to ensure that the key-value pairs are valid if the YAML file is converted to JSON format. For instance, here's how it looks now

{
  "deploy": {
    "hooks": {
      "post_deploy": [
        {
          "php": {
            "command": "bin/magento indexer:reindex"
          }
        },
        {
          "curl": {
            "directory": "/mnt/",
            "filename": "<filename>",
            "url": "<download-link>"
          }
        }
      ]
    }
  }
}

Compiling with custom playbook

readymage.yaml

schema_version: 1.0.0
playbooks:
  test-book:
  - npm:
      command: ci
  - npm:
      command: run build
      env_vars:
        BUILD_MODE: magento
environments:
- name: readymage-test
  build:
    themes:
      Magento/backend:
        area: adminhtml
        languages: [ 'en_US' ]
      scandipwa/theme:
        area: frontend
        playbook: test-book
        directory: scandipwa
        languages: [ 'en_US' ]

Scenario: You want to compile your custom theme during the build phase.

Compiling vanilla Magento 2 themes

readymage.yaml

schema_version: 1.0.0
environments:
- name: readymage-test
  build:
    themes:
      Magento/luma:
        area: frontend
        languages: [ 'en_US', 'en_GB', 'lv_LV' ]
      Magento/blank:
        area: frontend
        languages: [ 'en_US', 'en_GB', 'lv_LV' ]
      Magento/backend:
        area: adminhtml
        languages: [ 'en_US' ]

Scenario: You want to compile default vanilla Magento 2 themes.

Compiling PWA Studio

readymage.yaml

schema_version: 1.0.0
playbooks:
  pwastudio:
  - npm:
      command: ci
      env_vars:
        NODE_ENV: development
  - npm:
      command: run build
      env_vars:
        MAGENTO_BACKEND_URL: https://test.readymage.com
        MAGENTO_BACKEND_EDITION: CE
        CHECKOUT_BRAINTREE_TOKEN: sandbox_8yrzsvtm_s2bg8fs563crhqzk
environments:
- name: readymage-test
  build:
    themes:
      Magento/backend:
        area: adminhtml
        languages: [ 'en_US' ]
      Magento/Luma:
        playbook: pwastudio
        area: frontend
        directory: pwastudio
        languages: ['en_US']

Scenario: You want to compile custom PWA Studio based theme.

Schema

By default, ReadyMage will attempt to validate configuration file before running its directives. If its invalid, the build will automatically fail with a relevant error about which parts of the schema are invalid or failed to be ran.

schema_version

Required. Specifies which schema version is used in the configuration file. Allowed values: 1.0.0

environments

Optional. Array of environment specific configurations

If there are no themes specified for the environment, all available Magento themes will be built for all areas, with the default language of en_US or, if specified, languages defined in config.php

• name

  Required. Environment full name.

• build

  Optional. Nested dictionary containing build specific configurations.

  • themes

    Optional. Dictionary of environment themes. Themes directive allows to specify which of themes should be built. This includes theme compilation and locale specific static file generation.

    • {theme}

      Theme ID <Vendor>/<theme> as defined in registration.php. Use all to generate static files for all Magento themes.

      • area

        Optional. Allowed values: all, frontend, adminhtml. If not defined, will fallback to all

      • languages

        Optional. Allowed values: array of strings. If not defined, will fallback to locales specified in config.php or if none found - to en_US

      • playbook

        Optional. Specifies which of the playbooks should be called during theme compilation. Ignored if theme ID is set to all

      • directory

        Required if playbook field is set. Specifies in which directory the theme is located at. Ignored if theme ID is set to all

  • hooks Optional. Hooks are way to inject custom logic around automated actions (e.g. build). For example if you need to swap config.php file for specific environment before the build. Allowed values: pre_build, post_build. To customize theme compilation and static content file generation logic, use playbook and theme directives instead of using the hooks.

    • pre_build This hook is run before automated build phase. Can contain only actions. Any actions here will permanently disable build cache until all of the actions are removed. It will result in permanently increased build times.
    • post_build This hook is run after automated build phase. Can contain only actions.
• deploy Optional. Nested dictionary containing deploy specific configurations.

  • hooks Optional. Hooks in this context offer a way to execute the needed commands throughout the deployment.

    • post_deploy This hook runs after the deployment has completed successfully. Available commands are php and curl only.

playbooks

Optional. Dictionary of playbooks.

A playbook is set of actions that are called on the theme build/compilation step. It’s invoked during the build pipeline before automated setup:static-content:deploy. To customize static-content deployment, use themes directive.

Playbooks can only contain actions. All the actions defined inside a playbook will be executed in sequentially manner.

Example

...
playbooks:
  my-playbook:
  - npm:
      command: ci
      directory: some_directory
  - npm:
      command: build
      directory: some_directory
      env_vars:
        BUILD_MODE: magento
   - copy:
       app/etc/config.php: app/etc/config2.php
       app/etc/config2.php: app/etc/config3.php
...

Out of the box ReadyMage provides several playbooks, alongside with the possibility of defining fully custom playbooks.

scandipwa, scandipwa_npm

Curated, builtin playbook which is actively maintained and test against 3.x and higher ScandiPWA themes. The approximation of the curated playbook can be expressed using following actions:

playbooks:
  scandipwa_npm_aprox:
  - npm:
      command: ci
      directory: scandipwa
  - npm:
      command: build
      directory: scandipwa
      env_vars:
        BUILD_MODE: magento

scandipwa_yarn

Curated, builtin playbook which is actively maintained and test against 3.x and higher ScandiPWA themes. The approximation of the curated playbook can be expressed using following actions:

playbooks:
  scandipwa_yarn_aprox:
  - yarn:
      command: install --immutable --immutable-cache --check-cache
      directory: scandipwa
  - yarn:
      command: build
      directory: scandipwa
      env_vars:
        BUILD_MODE: magento

Custom

To create custom theme build/compilation logic which falls outside the curated playbooks, simply create a custom playbook where all of the necessary build actions can be defined. This can be accomplished by defining a set of actions grouped inside the playbook that will be responsible for theme compilation. The resulting playbook will be available on any environments themes playbook field.

To build vanilla Magento themes, there is no need to specify playbook.

actions

Actions are generic, cherry-picked commands that are executed in pre-defined places inside the deployment pipeline. Actions can only be used inside playbooks or hooks.

• copy Copies from source to destination. The path is relative to the Magento installation directory. Will overwrite file/directory if it exists at destination.

  • {source}: {destination}

Example

...
- copy:
    app/etc/config.php: scandipwa/config.php
...

• move Moves from source to destination. The path is relative to the Magento installation directory. Will overwrite the file/directory if it exists at destination.

  • {source}: {destination}

Example

...
- move:
    app/etc/config.php: scandipwa/config.php
...

• symlink

  Creates symbolic link at the path pointing to the target. The path is relative to the Magento installation directory. The target is relative to the Magento installation directory, unless prefiexed with persistent: Will overwrite the file/directory if it exists at path.

  • {path}: {target} Use persistent: prefix in target to set a symlink persistent and shared directory.

Example

...
- symlink:
    app/test.xml: app/design/frontend/Ricards/test.xml
    app/test2.xml: persistent:test.xml
...

• composer

  Runs custom composer v1 or v2 commands. Use only if you have additional non-magento composer installations inside the project that have to be initialized after the main build.

  • command - Required.

  • version - Required. Allowed values: 1, 2

  • directory - Optional. If not defined, will fallback to theme directory.

Composer state should be always managed by composer.json and composer.lock files instead of configuration file actions!

• npm

  • command - Required.

  • directory - Optional. If not defined, will fallback to theme directory.

  • env_vars - Optional. Nested field, contains all environmental variables that should be passed to the command

Example

...
- npm:
    command: run build
    directory: scandipwa
    env_vars:
      BUILD_MODE: magento
...

• yarn

  • command - Required.

  • directory - Optional. If not defined, will fallback to theme directory.

  • env_vars - Optional. Nested field, contains all environmental variables that should be passed to the command

Example

...
- yarn:
    command: run build
    directory: scandipwa 
    env_vars: 
      BUILD_MODE: magento
...

• php (available on post_deploy hooks only)

  • command - Required.

  • directory - Optional. If not defined, will fallback to the root directory /var/www/public/.

Example

...
- php:
    command: bin/magento indexer:reindex
...

curl (available on post_deploy hooks only)

• command - Required.

• directory - Required. Must specify an absolute path to the /mnt/ directory.

• filename - Required. Must specify the name of the downloaded file.

Example

...
- curl:
    directory: /mnt/
    filename: <filename>
    url: <download-link>
...

Schema migrations

Migration guide from 0.x.x to 1.0.0