Updating Craft CMS

# Update your local development environment first

Your local development environment is where changes are applied and tested first. Please update your local Craft CMS installation first and apply updates by deploying as a second step. That way you make sure that your environments are in sync.

The config/general.php file we use in our setup guide sets allowUpdates to false: this prevents plugin and Craft core updates from the Craft Control Panel in the production environment. Keep your environments in sync and always update locally first; avoid updates and plugin installations directly on the remote environment.

Here are the options to update Craft CMS and Craft plugins. Also see the official Craft CMS update documentation↗.

# A) Update Craft using the Control Panel - simple

1. Login to the Craft CMS Control Panel of your local Craft installation
2. Go to Utilities > Updates
3. Click the "Update all" button

This will update your local development environment to the latest versions of Craft CMS as well as all plugins. After testing changes, deploy updates to your production App (see below).

# B) Update Craft using the Craft CLI - advanced

Run the following command in the terminal on your computer locally in the root folder of the Craft project:

./craft update all

This will update Craft, as well as all dependencies. For a dry run just type ./craft update, that will list the available updates.

# Deploying Craft updates

Once you've tested updates locally, deploy them to fortrabbit by pushing changes via Git or running migrations on the remote environment. Here are your options:

# A) Deploying updates with Git

1. Add and commit the local changes (composer.json, composer.lock, project.yaml …)
2. Deploy the changes by git push to trigger deployment

During the Git deployment composer install will likely run automatically. This way your local Composer changes get applied on the remote.

# B) Uploading updates with SSH/SFTP based workflows

Continuous development with an SFTP workflow is a hassle. One strategy is to upload the changed files from local to the App. Another strategy is to re-run the very same steps that have been done locally on the App itself.

# Database migrations

Updating Craft often requires running database migrations to update table structure and apply configuration changes. These run automatically when updating locally, but must be applied separately to your fortrabbit environment. Essential Craft CMS settings are stored in project.yaml and synced via project-config/apply.

Here are your options to run migrations:

# A) Database migrations as a build step (recommended)

When you have chosen Craft CMS in the software preset while creating the environment, the following two commands are part of your deployment build steps.

php craft project-config/sync
php craft migrate/all

# B) Craft Copy and Craft auto-migrate

We have also created a little auto-migrate package - see it on GitHub↗ - which triggers migrate/all and project-config/sync every time composer install runs, which means it runs every time you deploy using git.

# Install the package (locally)
$ composer require fortrabbit/craft-auto-migrate

With that in place, every time you deploy your code, database and project config changes will be applied. If no changes are required, nothing happens, so it is safe to run all the time. Just make sure to test your upgrades and migrations locally first. The package is also a dependency of our Craft Copy↗ deployment tool plugin. When Craft Copy is installed, it will always run on git push, which is equivalent to running ./craft copy/code/up—one of the commands the plugin provides.

# C) Trigger a database migration by visiting the Control Panel URL

After applying updates on your fortrabbit Craft App, you might see a "Service unavailable" message. Visit the control panel URL {{app-env-id}}.frbit.app/admin (or whatever you have set) and you might see a message saying that database changes need to be applied. Click the "apply" button to run the migration manually.

# D) Manually run database migrations on the App via Craft CLI

You can trigger the changes via the Craft CLI in the terminal via SSH:

# After being logged in to the environment
php craft migrate/all
php craft project-config/apply