Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 42 ยท Quality and Production

Deployment and Upgrades

Plan Magento 2.4 deployments and upgrades: default, developer and production modes, di:compile, static content, config.php vs env.php, Composer upgrades and extension checks.

Writing a module is half the job. The other half is getting it onto a server without breaking the store, and doing that again every week. Magento deployments are more involved than a typical PHP application, because the platform generates code (interceptors, factories, proxies), compiles dependency injection metadata, builds static assets for every theme and locale, and keeps a database schema that must match the code. Skip a step and you see white pages, missing styles or "Please upgrade your database" errors.

This lesson explains deploy modes, the usual deployment sequence, the two configuration files that matter, and how to upgrade the platform and extensions with care. Commands here run on a real server, so the examples are read-only, with two small stand-ins that plan a deployment and show configuration precedence.

Deploy modes

Magento has three application modes, shown with bin/magento deploy:mode:show and changed with bin/magento deploy:mode:set <mode>:

Mode Purpose Behaviour
default Not intended for real use Works out of the box, with poorer performance and errors hidden
developer Local development Generates code and static files on demand, shows errors, slowest
production Live stores Uses pre-compiled code and pre-deployed static files, hides errors, fastest

In developer mode you change a template or a di.xml and see the result after a cache clean, because Magento generates what it needs on the fly. In production mode nothing is generated at request time: the generated code and static files must already exist, the web server user typically cannot write to the code folders, and errors go to logs instead of the browser. Switching to production mode on the server often runs the compile and static deploy steps for you, but real pipelines run them explicitly so each step can be checked.

The usual deployment sequence

A common sequence for a Composer-based project, using the Magento CLI, looks like this. Treat it as a pattern, not a recipe, because details differ between versions and hosting setups:

Terminal
# 1. Get the code (from your repository) and install the locked dependencies
composer install --no-dev --optimize-autoloader

# 2. Optional: show a maintenance page for the steps that touch the database
bin/magento maintenance:enable

# 3. Apply module setup: schema, data patches, and import config.php values
bin/magento setup:upgrade --keep-generated

# 4. Compile dependency injection configuration and generated classes
bin/magento setup:di:compile

# 5. Build static assets for each theme and locale you serve
bin/magento setup:static-content:deploy -f en_US de_DE

# 6. Refresh caches, then reopen the store
bin/magento cache:flush
bin/magento maintenance:disable

What each step does:

  • composer install reads composer.lock, so every server gets exactly the versions you tested. Never run composer update on production.
  • setup:upgrade runs declarative schema changes, schema and data patches (see Declarative Schema and Data Patches and Schema Patches), and records module versions. Run it when module code with database changes has been added or updated.
  • setup:di:compile scans every module and writes the generated/ directory: factories, proxies, interceptors for plugins, and merged DI metadata (see Factories, Proxies and Generated Code). If you add a plugin or change a constructor and forget to compile, production uses stale code.
  • setup:static-content:deploy collects CSS, JavaScript, images and templates for each theme and locale into pub/static. It can take a long time on big projects, so many teams build it once in a build step and ship the result.
  • Cache flush makes sure nothing stale survives.
flowchart LR
    A["Code in Git"] --> B["Build: composer install,<br/>di:compile, static deploy"]
    B --> C["Release artifact"]
    C --> D["Upload to a new<br/>release folder"]
    D --> E["setup:upgrade if<br/>the database changes"]
    E --> F["Switch the symlink<br/>to the new release"]
    F --> G["Flush caches, warm up"]

A build pipeline prepares everything once, and the server only receives a ready release and switches to it.

Towards zero downtime

The sequence above puts the store in maintenance mode while it runs. To reduce or remove downtime, teams usually build outside the live server (in CI), upload the result to a new release directory, and switch a symlink such as current to it in one atomic step, keeping shared folders like pub/media, var and app/etc/env.php outside the release. The hard part is the database: if the new code runs a schema change, the old code still serving requests must tolerate it. Keep migrations backward compatible (add columns before using them, remove them in a later release), and run setup:upgrade only when something actually changed. Managed platforms such as Adobe Commerce on cloud have their own build and deploy hooks that follow the same idea. Check your host's documentation for the exact process.

PHP A deploy planner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

config.php and env.php

Two files in app/etc/ hold deployment configuration, and they have different jobs.

app/etc/config.php is shared by all environments and is committed to Git. It lists every module and whether it is enabled ('Acme_Badge' => 1), and can hold dumped system configuration, themes and scope definitions after bin/magento app:config:dump. A committed config.php means every environment runs the same set of modules, and app:config:import applies its settings during deployment.

app/etc/env.php is specific to one environment and must not be committed. It contains secrets and environment details: database credentials, the encryption crypt key, the admin URL frontName, cache and session backends (Redis hosts), the MAGE_MODE and similar items. Each server has its own copy, and in release-based deployments it lives in a shared folder.

Values set in these files, or in environment variables named like CONFIG__DEFAULT__GENERAL__STORE_INFORMATION__NAME, override what an admin saved in the database for the same path, and the admin shows those fields as locked. That lets you pin production settings such as payment sandbox flags or API URLs per environment instead of relying on someone clicking in the admin. The exact precedence rules and supported variable formats vary slightly between versions, so read the documentation for yours. The stand-in below uses a simple layered lookup in the same spirit.

PHP Which value wins?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The sandbox flag saved as 1 in the database is overridden by the environment variable on this server, and the old base URL in the database never wins over the deployment file.

Upgrading Magento and extensions

Upgrades are risky mostly because of customisations and third-party code. A careful process:

  1. Read the release notes for the target version: supported PHP, database and search engine versions, deprecations, and known issues. A new Magento release can require a newer PHP or OpenSearch than your server has.
  2. Upgrade on a copy first. Restore production data and media to a staging environment and run the whole procedure there.
  3. Update composer.json. For example, change the version constraint of the Magento product package (Open Source or Adobe Commerce), then run composer update locally, never on production. Commit the changed composer.lock.
  4. Check every extension. Look for versions that declare compatibility with the new Magento and PHP versions in their composer.json require section and release notes. Update, replace or remove those that do not. Ask the vendor about paid extensions before upgrading.
  5. Run setup:upgrade, compile, and deploy static content on staging, then run your test suite and a manual checkout.
  6. Check your own code. Run PHP static analysis and your unit and integration tests, and look for deprecated APIs your modules call. Plugins on methods that changed signature are the usual breakers.
  7. Schedule the production run, take database and file backups first, and have a rollback plan: a previous release folder or a database snapshot.

Security patches follow the same route but should be applied quickly. Keep your project close to the latest patch of a supported version, since upgrading across many versions at once is the most painful kind.

Keep deployment commands in a script or CI pipeline, not in people's memory. A pipeline makes every release identical, and the log shows exactly which step failed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which mode generates code and static files on demand and shows errors in the browser?

    Developer mode is built for local work: it generates what it needs at request time and shows errors. Production expects everything to be prepared in advance.
  2. 2. Which command writes factories, proxies and interceptors into the generated directory?

    setup:di:compile scans modules and generates the classes and metadata that production mode relies on.
  3. 3. Which file should be committed to Git and which should not?

    config.php holds the shared module list and dumped settings. env.php holds credentials and per-server details and must stay out of version control.
  4. 4. Why do careful teams run composer update only on a development machine?

    composer install reads the lock file, so production gets exactly the versions that were tested. composer update changes them.
  5. 5. What is the hard part of zero-downtime database changes?

    During a release both old and new code may run against the same database, so migrations are done in compatible steps.

Summary

  • Magento has default, developer and production modes; production needs compiled code and deployed static content.
  • A typical release runs composer install, setup:upgrade (when the schema changes), setup:di:compile, setup:static-content:deploy and a cache flush.
  • Build in CI and switch releases by symlink to approach zero downtime; keep migrations backward compatible.
  • config.php is shared and committed; env.php holds secrets and is per environment. Files and environment variables can override admin values.
  • Upgrade on a copy first, check every extension for compatibility, read the release notes and keep a rollback plan.

Next: Project: A Complete Custom Module