Operate OpenMage

An OpenMage App runs OpenMage LTS 20.x, the maintained Magento 1 fork, on the synopmage platform line. synsmarts builds your store’s full file tree into an immutable image on PHP 8.2, 8.3, or 8.4. MySQL, Redis, Nginx, PHP, the origin WAF, and Scheduled Jobs run as managed services around that image.

Choose the PHP version

Select the PHP version when you buy the App. The portal offers the PHP rows the platform publishes for OpenMage: 8.2.35, 8.3.36, and 8.4.27. 8.3.36 is preselected. OpenMage runs on 8.4 but documents warnings there, so 8.3 is the default. The App’s database is Percona Server for MySQL 8.4.10 and its Redis is 7.4.10.

A fresh install puts OpenMage 20.19.0 on the App. To prepare an App for a store you already run, clear Install OpenMage for me at purchase; see Create an App. The purchase offers no demo content for OpenMage.

Sign in to the admin

A fresh install creates one admin account for each Team owner and admin. The login is the part of the email address before @, reduced to letters and digits, and the password is random and never shown. Open /admin/ on the App’s domain, choose Forgot your password?, and enter your email to set one.

The reset email needs the App’s outbound email on. An App bought without the OpenMage install starts with it off; see Manage App email.

Prepare the source

A deploy must contain these files at the source root:

• index.php;
• app/Mage.php;
• cron.php.

The build stops with an error naming the three files when any is missing. The source root is the store’s document root.

When the root carries composer.lock, the build runs composer install --no-dev --optimize-autoloader --no-interaction with Composer 2.10.1. Without composer.lock, it uses the tree as shipped.

When composer.lock names a package from a private Composer repository, store the repository credentials as the COMPOSER_AUTH build secret under Vars and secrets. Its value is the complete Composer authentication JSON. The build mounts it as Composer’s auth.json while dependencies install, and it isn’t copied into the image.

The build leaves app/etc/local.xml, media/, and var/ out of the image. synsmarts renders local.xml and mounts it read-only. media/ and var/ live on the App’s Workspace and are shared by every pod.

Caution

Keep database passwords and other credentials out of Git. The rendered local.xml carries the database, Redis, and crypt/key values; you don’t commit or edit it.

OpenMage requires the PHP ftp extension. The OpenMage images include it.

Manage store settings

The table prefix, admin frontName, install date, and extra PHP entry points are store settings in the App YAML. Read and change them with the CLI, the API, or MCP, as for a Magento 1 App; see Manage Magento 1 store settings.

Nginx sends index.php, api.php, get.php, js/index.php, errors/report.php, errors/404.php, and errors/503.php to PHP. It returns 403 for every other PHP script, cron.php and install.php included, unless you list it as an entry point. /api/rest routes to api.php?type=rest.

Deploy a release

1. Update the source and composer.lock together.
2. Test the store, its extensions, and its setup scripts outside production.
3. Deploy the selected Git revision or prepared Workspace.
4. Follow the build and rollout in the deploy detail.
5. Test the storefront, admin, checkout, customer login, and media.

Before traffic moves, a release Job on the new image applies every pending setup and data script once. The previous release keeps serving while it runs. A failed Job fails the deploy.

Caution

Setup scripts are forward-only. A deploy takes no database backup first, so a script that ran before the Job failed stays applied. Rolling back serves the previous image without a release Job and doesn’t undo applied scripts.

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

Use the managed shell

The managed SSH shell opens in /var/www/html on the Workspace with the App’s PHP version. It includes n98-magerun 3.0.1:

Inspect OpenMage from the managed shell

n98-magerun sys:info
n98-magerun cache:list
n98-magerun index:list

For a database console, run site-mysql. It supplies the App’s connection through a private temporary defaults file and removes that file when the client exits.

The bundled n98-magerun refuses db:console, db:dump, db:import, db:info, and db:query, including their aliases. Those upstream commands put the database password in process arguments. Use site-mysql -e 'SELECT 1' for a query, and contact support for a dump or import.

Manage scheduled work

New OpenMage Apps include two Scheduled Jobs. Each runs every minute with Forbid concurrency:

• openmage-cron-default runs php /var/www/html/cron.php -mdefault;
• openmage-cron-always runs php /var/www/html/cron.php -malways.

They run cron.php in the foreground, so each run’s exit status reaches the job history. On an App created for a migrated store, they start with its first deploy. Keep both. They’re ordinary customer-owned Scheduled Jobs: editable, pausable, deletable, counted toward the 50-job limit, and not recreated after deletion. See Manage scheduled jobs.

Caches and sessions

OpenMage uses two Redis roles: the application cache and sessions. The cache key prefix changes with each release, so a new release never reads the previous release’s cached configuration. Sessions are shared across PHP pods.

Trace requests

OpenMage Apps emit PHP spans. A traced request shows an openmage.dispatch span for the front controller and spans for the page’s blocks, with the MySQL and Redis calls beneath them. See Trace requests.

Update OpenMage safely

Your store code, including the OpenMage version in composer.lock, is yours. synsmarts never upgrades it.

1. Read the OpenMage release notes for the target 20.x release and confirm your extensions support it.
2. Update composer.json, composer.lock, and extensions together.
3. Test setup scripts, checkout, admin, and both cron modes outside production.
4. Verify a recent database backup; the deploy doesn’t take one.
5. Deploy one exact Git revision or reviewed Workspace snapshot.
6. Verify the customer journeys and the next runs of both Scheduled Jobs.

Troubleshoot a release

• The build names index.php, app/Mage.php, and cron.php. The source root isn’t the store’s document root, or the tree is incomplete.
• Composer fails to download a package. A package needs credentials the build doesn’t have; commit the package to the source or serve it from a public repository.
• The release Job fails. Read its output in the deploy detail. The scripts it applied before the failure stay applied; fix the failing script and deploy again.
• The admin URL returns 404. The admin frontName setting differs from the path you opened.
• A custom script returns 403. Add it as a PHP entry point.

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