Operate Magento

synsmarts builds Magento from your Composer project and deploys the resulting immutable application image. MySQL, Redis, OpenSearch, Nginx, PHP, scheduled jobs, and optional Varnish are managed services around that image.

Prepare the source

A Magento deploy must contain:

• composer.json at the selected source root;
• bin/magento;
• application modules, themes, patches, and configuration required by the release.

Include composer.lock for a reproducible dependency set and commit it when using Git. A build can proceed without it, but dependency resolution can change between otherwise identical deploys.

A Workspace transfer may include the production vendor/ tree. synsmarts reuses it only when it passes four checks:

• Composer’s installed metadata exactly matches every production package in composer.lock;
• the autoloader and package install paths exist inside the source;
• Composer validates manifest/lock consistency;
• the selected PHP runtime satisfies the installed requirements.

Symlinked metadata, or an incomplete or mismatched vendor tree, is discarded and rebuilt with Composer. When the tree passes validation, synsmarts includes vendor/ in the image build even if the source .dockerignore excludes it. Use .deployignore to omit vendor/ from the Workspace snapshot when you want Composer to rebuild dependencies instead.

Caution

Keep auth.json and app/etc/env.php out of Git and out of any Workspace source. Both carry credentials — if either was ever committed, treat the repository history as exposed credential material.

When the selected source doesn’t contain a validated complete vendor/, store your Adobe Commerce Marketplace credentials as the COMPOSER_AUTH build secret under Vars and secrets. Its value is the complete Composer authentication JSON, including the repo.magento.com http-basic public and private keys. A validated complete vendor build doesn’t read or mount Composer credentials.

Understand the build

The platform-managed Magento build performs the production preparation steps, including:

• exact production lock/package/install-path validation and composer check-platform-reqs --no-dev when a complete vendor/ is supplied, or authenticated composer install --no-dev when dependencies must be rebuilt;
• module enablement when app/etc/config.php is absent;
• optimized Composer autoload generation;
• dependency-injection compilation;
• static-content deployment for the configured locales and themes.

Don’t add a second production compilation sequence after deployment. Changes to Composer dependencies, generated code, or static assets belong in the next selected source and build.

Choose the source for each release

Each release explicitly uses Git or Workspace:

• Choose Git when the intended Magento project is a branch, tag, or commit in the connected repository.
• Choose Workspace when the intended project is the current server-side file tree prepared through SSH or another deployment tool.

When a repository is connected, both sources remain available. A Workspace deploy doesn’t commit its files to Git. A later successful Git deploy refreshes non-preserved Workspace code from the built release on a best-effort, non-gating basis and can remove changes that exist only in Workspace. A refresh failure leaves the Git release live and can leave older Workspace code. Make the equivalent repository change when it must survive future Git releases.

Use an exact Git commit SHA when you need a reproducible Git release.

Deploy a release

1. Update the source intended for the release and composer.lock.
2. Confirm either the source contains the complete production vendor/ tree or COMPOSER_AUTH is configured and current.
3. Run Magento tests, static analysis, and dependency checks.
4. Deploy the selected Git revision or prepared Workspace.
5. Follow build, migration classification, migration, rollout, and verification in the deploy detail.
6. Test storefront, admin, checkout, customer login, search, media, cache, and scheduled work.

How Magento database changes are detected

The deploy first decides whether the selected source changed a migration-bearing path.

• A Git deploy compares the currently serving commit with the resolved candidate commit.
• A Workspace deploy compares its Workspace schema fingerprint with the serving Git commit when that baseline is available.
• A Workspace snapshot containing .deployignore can’t produce a trustworthy schema fingerprint because ignored paths could hide migration files. It is treated as unknown rather than code-only.

Migration-bearing paths include composer.json, composer.lock, db_schema.xml, db_schema_whitelist.json, module.xml, app/etc/, Setup/, and Patch/.

When a migration-bearing path changed, synsmarts builds the new image and compares its post-build schema inventory with the serving image. The post-build comparison includes Composer-installed modules under vendor/.

Changes limited to added tables, a nullable or defaulted column, or ordinary indexes can be additive. Drops, renames, existing-column changes, constraint changes, whitelist-only changes, or changed Setup or Patch PHP use breaking treatment. Additive DDL on an existing table estimated above 1,000,000 rows also uses maintenance. Any unavailable or ambiguous static evidence becomes a breaking or unknown candidate. The read-only status probe then decides whether that candidate needs a maintenance window.

For example, this declaration can be additive when the target table is below the live-DDL threshold and the rest of the inventory remains compatible:

app/code/Acme/Module/etc/db_schema.xml

<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <table name="acme_order">
    <column xsi:type="varchar" name="external_reference"
      nullable="true" length="64" comment="External reference"/>
  </table>
</schema>

Before database handling starts, synsmarts takes a pre-migration backup. Additive deploys then pause scheduled work and run the managed migration Job while the previous release keeps serving.

Breaking and unknown candidates first run a separate read-only status probe from the new image. The probe runs before customer notification, the maintenance page, scheduled-work pause, or the real migration Job. A clean schema promotes with no maintenance window or notification. When migration is required or the probe is unavailable, synsmarts sends the notification, enters maintenance, pauses scheduled work, and runs the managed migration Job:

Check Magento database status

bin/magento setup:db:status

If the database isn’t current, the Job runs bin/magento setup:upgrade --keep-generated from the new image and verifies database status again.

• Additive: the old release keeps serving with no planned interruption. If the migration fails, synsmarts doesn’t restore the backup because that would discard live writes.
• Breaking or unknown: a clean status probe promotes without a maintenance window, notification, or real migration Job. A migration-required result or unavailable probe falls through to the notified maintenance window. If that migration fails before promotion, synsmarts restores the pre-migration backup and returns the previous release to service.
• Restore failed: maintenance stays on and support intervention is required.

See How deploys move from code to traffic for the complete classifier and rollback model.

Caution

Run production migrations only through the managed deploy. A manual bin/magento setup:upgrade against production separates database state from the release record and rollback decision.

Use the Magento CLI

The managed SSH shell can run Magento commands from the application directory. Start with read-only checks:

Inspect Magento from the managed shell

bin/magento --version
bin/magento setup:db:status
bin/magento indexer:status
bin/magento cache:status

Use mutating commands only when the action is intended to affect runtime state, not to replace the selected release source or managed migration. In particular:

• change modules, themes, Composer packages, and DI inputs in the source intended for the next release;
• let the deploy build compile generated code and static content;
• let the deploy workflow apply database schema and data patches;
• use the portal’s Varnish purge action for full-page cache invalidation.

Manage scheduled work

Magento depends on scheduled execution for indexing, email, catalog rules, consumers, and other application work. New Magento Apps include a Scheduled Job named magento-cron. It runs magento-cron-runner every minute with Forbid concurrency.

The seeded job is an ordinary customer-owned Scheduled Job. It is visible, editable, pausable, and deletable; counts toward the 50-job limit; and isn’t recreated after deletion. Keep it unless another scheduler fully replaces the same Magento work.

Don’t replace magento-cron-runner with a bare bin/magento cron:run Scheduled Job. Magento starts detached cron groups, and the managed runner waits for those processes to drain before the job is reported complete.

Keep other durable commands and schedules in Scheduled Jobs, then verify the next run and its output after a release.

Useful checks include:

Inspect scheduled Magento work

bin/magento cron:run
bin/magento indexer:status
bin/magento queue:consumers:list

Run cron:run manually only for controlled verification. Avoid defining the same recurring command in more than one scheduler.

See Manage scheduled jobs.

Manage caches and search

• Use Magento cache commands for Magento application cache types.
• Use Purge cache on the Varnish service card to invalidate the managed full-page cache.
• Review Redis settings before changing cache eviction behavior.
• Review OpenSearch version compatibility before selecting a different offered version.
• After catalog or search changes, verify indexer status and a representative storefront search.

See Configure services and Service configuration fields.

Update Magento safely

1. Confirm the target Magento release supports the offered PHP, MySQL, OpenSearch, and Composer dependency versions.
2. Update composer.json, composer.lock, modules, themes, and patches together.
3. Test compilation, static content, schema changes, checkout, admin, cron, indexing, and search outside production.
4. Verify a recent database backup.
5. Deploy one exact Git revision or reviewed Workspace snapshot and review its migration classification.
6. Verify the customer journeys and scheduled work after promotion.

synsmarts updates the managed runtime and services. Magento core, extensions, themes, patches, and their compatibility remain your responsibility.

Troubleshoot a release

• Missing composer.json or bin/magento means the source isn’t a complete Magento project.
• Missing Marketplace credentials means dependency reconstruction was required and COMPOSER_AUTH is absent or doesn’t contain valid repo.magento.com credentials.
• A vendored dependency validation failure means the supplied vendor/ doesn’t exactly represent the production packages in composer.lock; repair the transferred tree or configure Composer credentials so it can be rebuilt.
• app/etc/env.php and auth.json must be removed from whichever source is selected. If either was committed to Git, also treat the repository history as exposed credential material.
• A compile failure should be fixed in the selected Git revision or prepared Workspace, not by changing generated files after the build.
• A schema or data-patch failure should be reviewed in deploy details before retrying.
• A search problem should be separated into indexer state, OpenSearch health, and storefront query behavior.

Use Recover from a failed deploy and Get support when the failing layer is managed by synsmarts.