Module configuration deployment

This document describes possible deployment process which could be used for the application. Workflow can be seen in image below, schema steps are described in following sections.

Configuration files preparation

Let’s say you are configuring modules on your local machine (how to do this please read the modules configuration document). After your are done, you have prepared files in var/configuration/shops/ directory.

Dealing with environment files

Let’s assume you have OXID eShop with PayPal module and you want to deploy your configuration from your development environment to staging environment. All settings in both environments are the same except sOEPayPalUsername and sOEPayPalPassword. So you would need all the time after deployment to change these values as configuration files would be overwritten. To solve this problem, environment feature was introduced.

Environment files overwrite settings which are already described in configuration files located in var/configuration/shops/ directory.

To use this feature you need to create the directory var/configuration/environment and put stripped down contents of var/shops/<shop id>.yaml in there. Here you may configure environment specific values, for example credentials for payment providers.

So to solve the problem described in the beginning of the section follow these steps:

1. On staging environment 1.yaml (assuming it’s main shop) file inside the var/configuration/environment directory.

2. Copy and paste the part of your module settings from var/shops/1.yaml to var/configuration/environment/1.yaml.

3. Write your new values for sOEPayPalUsername and sOEPayPalPassword and save your file.

Environment file var/configuration/environment/1.yaml should look something like this:

modules:
  oepaypal:
    moduleSettings:
      sOEPayPalUsername:
        value: 'staging_environment_username'
      sOEPayPalPassword:
        value: 'staging_environment_password'

New values will get into database as soon as module will be activated.

In case you have 3 environments: testing, staging and production, files structure could look like this:

.
└── var
    └── configuration
        └── shops
           └──1.yaml
           └──2.yaml
           └── ...
        └── environment
           └──1.yaml
           └──production.1.yaml
           └──staging.1.yaml
           └──testing.1.yaml
           └──2.yaml
           └──production.2.yaml
           └──staging.2.yaml
           └──testing.2.yaml
           └── ...

In described files structure you can see that there are multiple files per shop in var/configuration/environment directory. This might be useful when deploying files to some specific environment.

Important

If you have environment configuration files in the OXID eShop you should not save settings via admin backend. If you do this, the environment specific values will be merged into the base configuration and the environment configuration will be renamed to .bak file like 1.yaml.bak. Then your manual changes will be applied to the base configuration and then to the modules. Be aware that if there is already an environment backup file, it will be overridden if setting will change again.

Next steps would be:

• Upload files to the production server.

• Copy testing, staging or production file on top of main environment file. Example command:

  cp var/configuration/environment/production.1.yaml var/configuration/environment/1.yaml
  

• Apply configuration for all configured modules. More information can be found in following section.

Apply configuration

Each module configuration in the shop configuration yaml file has a configured option and It can have two states:

• true means that the module is prepared for the activation (or already active).

• false means that the module is prepared for the deactivation (or already inactive).

Example of the shop configuration yaml file:

modules:
    oegdproptin:
        id: oegdproptin
        path: oe/gdproptin
        configured: true
        ...
    oevarnish:
        id: oevarnish
        path: oe/varnish
        configured: false
        ...

This option can be set manually by changing configuration file. Also the option will be set to true if you activate a module manually via console or admin backend or to false if you deactivate your module.

To apply configuration use the following command:

vendor/bin/oe-console oe:module:apply-configuration

Provide --shop-id option if you are using an OXID eShop Enterprise Edition and it is only for one shop.

vendor/bin/oe-console oe:module:apply-configuration --shop-id=1

Important

When command is executed module data in configuration files will overwrite data in database.