Deployment Best Practices

While the exact steps you take to deploy Craft CMS will depend on your hosting setup, we recommend these general best practices to encourage smooth, predictable deployments.

Commit Template & Config Changes #

It’s best to limit config and dependency changes to local environments where they can be tested, committing explicit records of those changes to be used by the deployment process:

Be Prepared #

A few precautionary steps can drastically reduce the impact of most human and technical errors:

  • Back up your database at sensible intervals, whether they’re scheduled snapshots or part of the deployment process. Test the backups periodically to be sure they’re reliable and easy to restore.
  • Back up Asset Volumes in case a content editor accidentally hard-deletes any files. (Most cloud storage providers can be configured to enable versioning, and local assets can be included in snapshot backups.)
  • Ensure every deployment environment can pass Craft’s environment check, giving PHP at least 256MB of memory and a 120-second max execution time per Craft’s server requirements.
  • Ensure a developer with Composer knowledge has SSH access to the deployment machine for troubleshooting in case anything goes wrong.

Follow Deployment Steps #

Ideally, deployments would be automated with Buddy, GitHub Actions, Travis CI, or a similar service to work quickly and automatically, avoid human error, and immediately alert you to any issues.

Regardless of how you’re managing deployments, however, it’s important to follow these steps in order:

  1. Pull updated files into place with git pull <your-remote-name> (i.e. origin) and update dependencies by running composer install --no-interaction.
  2. Run php craft migrate/all to run pending Craft, plugin, and/or content migrations.
  3. If you’re using project config to propagate changes between environments, run php craft project-config/apply to have Craft pull in any config changes specified in the project config YAML.
  4. You’ll often need to clear caches as a last step, which can mean PHP’s OPcache or issuing purges for a CDN.

Craft 3.5.8 added on and off console commands for temporarily toggling the project config value for deployments. You can also use the retryDuration setting to set a Retry-After header on “system offline” 503 responses.

If you’ve followed these steps and are encountering problems, see Troubleshooting Failed Updates.