Raised: $0
0% of monthly goal Help us cross the finish line!
Goal: $12,000
Raised: $0 Goal: $12,000
0% of monthly goal Help us cross the finish line!
Sponsor DDEV

If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.

add-on registry last commit

ddev-amezmo

ddev-amezmo is a DDEV integration for CMS and framework applications hosted on Amezmo. It downloads a selected Amezmo environment’s database and persistent storage files into a local DDEV project, uploads local data to a selected environment, and copies data between configured Amezmo environments. It never deploys application code.

Production and staging profiles are installed independently. Drupal, WordPress, and custom application adapters are supported.

Status and scope

This add-on supports one MySQL-compatible database and one persistent storage directory per environment on macOS, Linux, and WSL2. Guided setup uses the Amezmo API to discover environment configuration. Multiple databases or storage mounts, Redis, Solr, workers, cron, environment-variable recreation, deployments, and native Windows are out of scope. The automated suite uses mocked SSH and does not prove compatibility with a live Amezmo account.

Prerequisites

The add-on honors ~/.ssh/config, IdentityFile, SSH agents, and normal known_hosts verification. It never disables host-key checking. If your key is available only through DDEV’s agent, run ddev auth ssh.

Install

ddev config
ddev add-on get sdubois/ddev-amezmo

For a local checkout:

ddev add-on get /absolute/path/to/ddev-amezmo

Installation creates production and staging profiles under .ddev/providers/ and .ddev/amezmo/environments/. Start the guided setup to discover environment details through the bundled amezmo-cli:

ddev amezmo cli auth login
ddev amezmo configure

The wizard asks you to select an Amezmo instance and then configures every environment returned for it, normally production and staging. Each environment gets independent API-derived defaults for the instance ID, application type, SSH endpoint, application root, site URI, and remote storage directory. The wizard asks for the remaining settings, shows one summary before writing anything, backs up existing profiles, and creates DDEV providers for newly discovered environment names.

Configure an environment

The guided setup is recommended. For manual setup, set these values independently in .ddev/amezmo/environments/production.env and staging.env, then remove their #ddev-generated markers so upgrades preserve your settings:

export AMEZMO_ENVIRONMENT=production
export AMEZMO_INSTANCE_ID=3503
export AMEZMO_AUTO_TRUST_SSH_IP=true
export AMEZMO_APP_TYPE=drupal
export AMEZMO_SSH_HOST=your-amezmo-host
export AMEZMO_SSH_PORT=12345
# Optional override; omit or leave empty to use deployer.
export AMEZMO_SSH_USER=
export AMEZMO_REMOTE_APP_ROOT=/webroot/current
# Optional override; omit or leave empty to use Amezmo's app_domain URL.
export AMEZMO_SITE_URI=
export AMEZMO_REMOTE_FILES_PATH=/webroot/storage
export AMEZMO_LOCAL_FILES_PATH=web/sites/default/files

Use the SSH endpoint, application root, and persistent storage paths for that exact Amezmo environment. AMEZMO_SSH_USER is optional and defaults to deployer. AMEZMO_SITE_URI is an optional HTTP or HTTPS URL override for Drush, such as a custom production or staging domain. When it is unset or empty, the add-on reads the selected environment’s app_domain from Amezmo and uses its HTTPS URL. This fallback requires an authenticated bundled amezmo-cli; an explicit override does not. AMEZMO_SITE_URI is separate from AMEZMO_SSH_HOST, which must remain the Amezmo SSH endpoint. Amezmo normally stores persistent data under /webroot/storage; staging environments can have a different storage root. Do not derive staging values from production. See the configuration reference for all settings and adapter examples.

When upgrading a customized Drupal profile created by version 0.2.1 or earlier, remove AMEZMO_DRUSH_ALIAS. Add AMEZMO_SITE_URI only when you need to override Amezmo’s default application URL. The add-on now runs Drush directly in the Amezmo application release and no longer reads a local Drush site-alias file.

When AMEZMO_AUTO_TRUST_SSH_IP=true (the generated default), a failed SSH access check discovers the current public IP, reads the selected environment’s existing trusted SSH IPs with the bundled amezmo-cli, and asks for confirmation before appending the current IP and retrying the connection. Set AMEZMO_INSTANCE_ID to the Amezmo instance ID for each profile. The CLI must have an API key configured (AMEZMO_API_KEY or its normal config file). Existing trusted IPs are preserved. Set the switch to false to disable this behavior.

ddev restart
ddev amezmo doctor production
ddev amezmo pull production
ddev amezmo push staging
ddev amezmo copy --from production --to staging --db --files
ddev amezmo drush staging cache:rebuild
ddev amezmo cli whoami

Useful options include --skip-db, --skip-files, and -y:

ddev amezmo doctor staging
ddev amezmo pull staging --skip-db

doctor is read-only. A download can replace the local database and copy sensitive persistent storage files from Amezmo, so back up local work and follow your organization’s data-handling rules.

For Drupal projects, run any Drush command against the site-local Drush installation in a configured Amezmo environment:

ddev amezmo drush staging status
ddev amezmo drush production config:get system.site
ddev amezmo drush staging user:login --uid=1

The add-on checks SSH access, changes to AMEZMO_REMOTE_APP_ROOT, and passes either the configured AMEZMO_SITE_URI override or Amezmo’s default application URL, followed by the command and arguments, to the environment’s vendor/bin/drush. It does not require a local Drush installation or drush/sites/self.site.yml. Set AMEZMO_REMOTE_CLI_PATH when remote Drush is installed elsewhere. Drush commands can change remote data or configuration; review the selected environment and command before running mutating operations.

push uploads the local database and persistent storage files to the selected Amezmo environment. DDEV displays a confirmation prompt, and the add-on prints an additional warning identifying the Amezmo target. Review the environment, local data, and paths carefully; uploading to production can overwrite important data. File uploads overwrite matching files but do not delete files already in the Amezmo environment. Database uploads replace the target database contents through the selected application CLI. Use --skip-db or --skip-files when only one asset type should be transferred.

Copy between Amezmo environments

Use copy when the source and target are both configured Amezmo environments. Select the database, persistent files, or both explicitly:

ddev amezmo copy --from production --to staging --db
ddev amezmo copy --from production --to staging --files
ddev amezmo copy --from production --to staging --db --files

The command displays the source, target, and selected data, then requires you to type the target environment name. Use -y only when the direction has already been verified or for non-interactive operation. Source and target must be different and use the same application adapter. Copying into an environment named production is blocked unless --allow-production-target is also supplied.

Database copies do not import into the local DDEV database. Before replacement, the command downloads and validates a backup of the target database under .ddev/.downloads/amezmo-backups/. It then downloads the source export to a temporary directory and validates its gzip stream. For Drupal, only after both files pass validation, site-local Drush clears every table from the target database before the source is imported. If that import fails, the command clears any partial import, automatically restores the validated target backup, reports whether restoration succeeded, and still exits nonzero. The temporary source export is removed after the command exits; the target backup is retained.

Because rsync cannot transfer directly between two remote endpoints, file copies download into a temporary host directory and then upload to the target. Matching target files are overwritten, unmatched target files are not deleted, and the temporary directory is removed after the command exits. Ensure the host has enough free space for the selected database, files, and retained backup.

A production database may contain real users, sessions, credentials, queued mail, and notification state. Run the application’s staging sanitization and cache-rebuild procedures after copying. The add-on does not alter copied application data automatically.

The add-on also bundles the pinned amezmo-cli v0.1.0-beta.1 release for Amezmo API operations:

ddev amezmo cli whoami
ddev amezmo cli environments list INSTANCE_ID
ddev amezmo cli deployments get INSTANCE_ID DEPLOYMENT_ID

These commands require PHP 8.3 or newer on the host. The API CLI manages Amezmo resources; it does not replace this add-on’s database or persistent-storage transfers.

Drupal database downloads, health checks, and arbitrary commands use vendor/bin/drush in the Amezmo application release by default. Drupal uploads ask drush sql:connect for the native database-client command and stream the validated SQL export directly into that client, avoiding the slower sql:cli stdin path. WordPress database operations use wp. Set AMEZMO_REMOTE_CLI_PATH in the environment profile when the application CLI is elsewhere. Custom adapters must set AMEZMO_REMOTE_DB_IMPORT_COMMAND; the command receives the uncompressed SQL export on standard input.

Documentation

The detailed reference is in the GitHub Wiki:

Development

shellcheck amezmo/amezmo commands/host/amezmo tests/*.bash
bats tests/test.bats
ddev add-on get "$PWD"

CI validates YAML, ShellCheck, Bats, and local installation when Docker is available.

If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.