Technical details
This topic discusses technical implementation details about pipeline deployment in Commerce 2.2 and later. Improvements can be divided into the following areas:
This topic also discusses the recommended workflow for pipeline deployment and provides some examples to help you understand how it works.
Before you get started, review the Prerequisites for your development, build, and production systems.
Configuration management
To enable you to synchronize and maintain the configuration of your development and production systems, use the following override scheme.
As the diagram shows, the configuration values are used in the following order:
- Environment variables, if they exist, override all other values.
- From the shared configuration files
env.php
andconfig.php
. Values inenv.php
override values inconfig.php
. - From values stored in the database.
- If no value exists in any of those sources, the default value or NULL is used.
Manage the shared configuration
The shared configuration is stored in app/etc/config.php
, which should be in source control.
Set the shared configuration in the Admin in your development (or Adobe Commerce on cloud infrastructure integration) system and write the configuration to config.php
using the magento app:config:dump
command.
Manage the system-specific configuration
The system-specific configuration is stored in app/etc/env.php
, which should not be in source control.
Set the system-specific configuration in the Admin in your development (or Adobe Commerce on cloud infrastructure integration) system and write the configuration to env.php
using the magento app:config:dump
command.
This command also writes sensitive settings to env.php
.
Manage the sensitive configuration
The sensitive configuration is also stored in app/etc/env.php
.
You can manage the sensitive configuration in any of the following ways:
- Environment variables
- Save the sensitive configuration in
env.php
on your production system using themagento config:set:sensitive
command
Configuration settings locked in the Admin
Any configuration settings in config.php
or env.php
are locked in the Admin; that is, those settings cannot be changed in the Admin.
Use the magento config:set
or magento config:set --lock
command to change the settings in the config.php
or env.php
files.
The Commerce Admin
The Admin exhibits the following behavior while in production mode:
-
You cannot enable or disable cache types in the Admin
-
Developer settings are unavailable (Stores > Settings > Configuration > Advanced > Developer), including:
-
Minify CSS, JavaScript, and HTML
-
Merge CSS and JavaScript
-
Server-side or client-side LESS compilation
-
Inline translations
-
As discussed previously, any configuration setting in
config.php
orenv.php
is locked and cannot be edited in the Admin. -
You can change the Admin locale only to languages used by deployed themes
The following figure shows an example of the Account Setting > Interface Locale list in the Admin showing only two deployed locales:
-
-
You cannot change locale configurations for any scope using the Admin.
We recommend making these changes before switching to Production mode.
You can still configure the locale using environment variables or the
config:set
CLI command with the pathgeneral/locale/code
.
Install and remove cron
In version 2.2 for the first time, we help you set up your cron job by providing the magento cron:install
command. This command sets up a crontab as the user who runs the command.
Also, you can remove the crontab using the magento cron:remove
command.
Recommended pipeline deployment workflow
The following diagram shows how we recommend you use pipeline deployment to manage the configuration.
Development system
On your development system, you make configuration changes in the Admin and generate the shared configuration, app/etc/config.php
and the system-specific configuration, app/etc/env.php
. Check Commerce code and the shared configuration into source control and push it to the build server.
You should also install extensions and customize Commerce code on the development system.
On your development system:
-
Set the configuration in the Admin.
-
Use the
magento app:config:dump
command to write the configuration to the file system.app/etc/config.php
is the shared configuration, which contains all settings except sensitive and system-specific settings. This file should be in source control.app/etc/env.php
is the system-specific configuration, which contains settings that are unique to a particular system (for example, hostnames and port numbers). This file should not be in source control.
-
Add your modified code and the shared configuration to source control.
-
To remove generated php code and static assets files while in development, run the following commands:
code language-bash rm -r var/view_preprocessed/* rm -r pub/static/*/* rm -r generated/*/*
After running the commands to clear the assets, Commerce generates working files.
.htacces
s file in the generated
or pub
folder may cause issues.Build system
The build system compiles code and generates static view files for themes registered in Commerce. It does not need a connection to the Commerce database; it needs only the Commerce codebase.
On your build system:
- Pull the shared configuration file from source control.
- Use the
magento setup:di:compile
command to compile code. - Use the
magento setup:static-content:deploy -f
command to update static file view files. - Check the updates into source control.
Production system
On your production system (that is, your live store) you pull generated assets and code updates from source control and set system-specific and sensitive configuration settings using the command line or environment variables.
On your production system:
- Start maintenance mode.
- Pull code and configuration updates from source control.
- If you use Adobe Commerce, stop queue workers.
- Use the
magento app:config:import
command to import configuration changes in the production system. - If you installed components that changed the database schema, run
magento setup:upgrade --keep-generated
to update the database schema and data, preserving generated static files. - To set system-specific settings, use either the
magento config:set
command or environment variables. - To set sensitive settings, use either the
magento config:sensitive:set
command or environment variables. - Clean (also referred to as flush) the cache.
- End maintenance mode.
Configuration management commands
We provide the following commands to help you manage the configuration:
-
magento app:config:dump
to write Admin configuration settings toconfig.php
andenv.php
(except for sensitive settings) -
magento config:set
to set the values of system-specific settings on the production system.Use the optional
--lock
option to lock the option in the Admin (that is, make the setting uneditable). If a setting is already locked, use the--lock
option to change the setting. -
magento config:sensitive:set
to set the values of sensitive settings on the production system. -
magento app:config:import
to import configuration changes fromconfig.php
andenv.php
to the production system.
Configuration management examples
This section shows examples of managing the configuration so you can see how changes are made to config.php
and env.php
.
Change the default locale
This section shows the change made to config.php
when you change the default weight unit using the Admin (Stores > Settings > Configuration > General > General > Locale Options).
After you make the change in the Admin, run bin/magento app:config:dump
to write the value to config.php
. The value is written to the general
array under locale
as the following snippet from config.php
shows:
'general' =>
array (
'locale' =>
array (
'code' => 'en_US',
'timezone' => 'America/Chicago',
'weight_unit' => 'kgs'
)
)
Change several configuration settings
This section discusses making the following configuration changes:
- Adding a website, store, and store view (Stores > Settings > All Stores)
- Changing the default email domain (Stores > Settings > Configuration > Customers > Customer Configuration)
- Setting the PayPal API Username and API password (Stores > Settings > Configuration > Sales > Payment Methods > PayPal > Required PayPal Settings)
After you make the change in the Admin, run bin/magento app:config:dump
on your development system. This time, not all of your changes are written to config.php
; in fact, only the website, store, and store view are written to that file as the following snippets show.
config.php
config.php
contains:
- Changes to the website, store, and store view.
- Non-system-specific search engine settings
- Non-sensitive PayPal settings
- Comments that inform you of sensitive settings that were omitted from
config.php
websites
array:
'new' =>
array (
'website_id' => '2',
'code' => 'new',
'name' => 'New website',
'sort_order' => '0',
'default_group_id' => '2',
'is_default' => '0',
),
groups
array:
2 =>
array (
'group_id' => '2',
'website_id' => '2',
'code' => 'newstore',
'name' => 'New store',
'root_category_id' => '2',
'default_store_id' => '2',
),
stores
array:
'newview' =>
array (
'store_id' => '2',
'code' => 'newview',
'website_id' => '2',
'group_id' => '2',
'name' => 'New store view',
'sort_order' => '0',
'is_active' => '1',
),
payment
array:
'payment' =>
array (
'paypal_express' =>
array (
'active' => '0',
'in_context' => '0',
'title' => 'PayPal Express Checkout',
'sort_order' => NULL,
'payment_action' => 'Authorization',
'visible_on_product' => '1',
'visible_on_cart' => '1',
'allowspecific' => '0',
'verify_peer' => '1',
'line_items_enabled' => '1',
'transfer_shipping_options' => '0',
'solution_type' => 'Mark',
'require_billing_address' => '0',
'allow_ba_signup' => 'never',
'skip_order_review_step' => '1',
),
env.php
The default email domain system-specific configuration setting is written to app/etc/env.php
.
The PayPal settings are written to neither file because the bin/magento app:config:dump
command does not write sensitive settings. You must set the PayPal settings on the production system using the following commands:
bin/magento config:sensitive:set paypal/wpp/api_username <username>
bin/magento config:sensitive:set paypal/wpp/api_password <password>