craft-copy
Craft Copy Plugin
This little command line tool helps to speed up common tasks around Craft CMS deployment on fortrabbit. Craft Copy syncs your local development environment with your fortrabbit App — up and down. It conveniently deploys code changes and synchronizes latest images and database entries. This Craft CMS plugin will be installed locally and on the fortrabbit App.
Demos
Here is a video introdcution (1.5 minutes).
Requirements
- A local development environment including: Craft 3|4, PHP 8 and Composer.
-
The following binaries should be executable:
php
,mysqldump
,git
andrsync
- A SSH key installed should with your fortrabbit Account (no password auth so far)
- You need to have an App with fortrabbit
Craft Copy works for Universal Apps and Professional Apps. Asset synchronisation is only available for Universal Apps with local asset volumes.
Installation
Best install Craft Copy in the terminal on your local computer with Composer like so:
# Jump into your local Craft CMS folder cd your/craft-project # Require Craft Copy via Composer composer config platform --unset composer require fortrabbit/craft-copy -W # With the latest version of composer (2.2 or higher) you may see this prompt: # Do you trust "fortrabbit/craft-auto-migrate" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?] # # Confirm with `y` # Install and enable the plugin with Craft CMS php craft plugin/install copy
You will be guided through a form to connect your local App with the App on fortrabbit. Craft Copy is available in the Craft CMS plugin store.
Usage
Craft Copy will always be executed on your local computer in your local development environment.
The optional {stage}
parameter defines which fortrabbit App the command applies to. It is useful when working with multiple fortrabbit Apps as stages. The default parameter is the app name. See multi-staging section below for more.
Some commands are interactive, meaning that you will need to confirm certain potential dangerous operations. You can disable such manual interactions by adding the --interactive=0
flag in most cases. The short alias version is -i=0
.
Setup
# Connect your development environment with your fortrabbit App php craft copy/setup
Get help
# See a list of available commands php craft help copy
Database
# Dump local DB (backup fortrabbit db) and import it to the fortrabbit App php craft copy/db/up {stage} # Dump local DB and import it to the fortrabbit App (useful if the fortrabbit db is broken) php craft copy/db/up {stage} --force # Dump fortrabbit DB and import it locally php craft copy/db/down {stage}
Code
While you can use git push
as well to deploy code by Git to your fortrabbit App, the Craft Copy code commands offer some additional extras: It will check for uncommitted changes and initialize the Git repo if required.
# Push code changes to the fortrabbit App php craft copy/code/up {stage} # Pull code changes from your fortrabbit App php craft copy/code/down {stage}
Asset Volumes
Assets in Craft CMS are media files that are uploaded by editors and managed by the CMS. Assets are getting stored in volumes and are not part of Git.
# Sync up a local volume to fortrabbit App php craft copy/volumes/up {stage} {?volumeHandle} # Sync down a vlume from the fortrabbit App to local php craft copy/volumes/down {stage} {?volumeHandle}
-
The “File System Path” for the Volume setting within the Craft CMS control panel should not be a relative path. You can use the
@webroot
alias. - Remote volumes (S3, Object Storage …) are not supported so far
Options and arguments
- {volumeHandle} is the handle name of your asset volume in Craft CMS
-
To sync all volumes, don’t provide a volumeHandle (and add
-i=0
to avoid questions) -
To test what will actually be synced you can add the
-n
option to trigger a dry-run
Copy all
Often you want to get all the latest content from the App or maybe even push all local changes up to the App. You can use the all command for that:
# Sync database, volumes and git from local to your fortrabbit App php craft copy/all/up # Sync database, volumes and git from your fortrabbit App to local php craft copy/all/down
- This is not including the folder action by default.
Craft Nitro support
Craft Copy supports Craft Nitro – the local development environment for Craft CMS based on Docker.
Some additional setup and a small change to your workflow is required. This is because Nitro containers are lacking the dependencies Craft Copy requires in order to transfer files/data between stages and does not mount your SSH keys from your host machine.
Please note that Craft Nitro is retiring, therefore no new features will be added to the Craft Nitro support by Craft Copy and it will evenatually be removed one day.
Enabling Craft Nitro support
1. Install the Craft Copy plugin in your Nitro container
nitro composer config platform --unset nitro composer require fortrabbit/craft-copy -W nitro craft plugin/install copy
2. Generate the wrapper script
nitro craft copy/nitro/setup
This will create a new shell script in your project root called nitro-craft
. You should check the nitro-craft
file into version control.
When changing the PHP version you are using in Nitro for this site you need to re-generate the script by calling nitro craft copy/nitro/setup
again. This is because Nitro uses different containers for different versions of PHP, and Craft Copy needs to use the same container name for everything to work.
Running Craft Copy commands under Craft Nitro
Just use ./nitro-craft
instead of nitro craft
like so:
# Without Nitro
nitro craft copy/db/up
# With Nitro
./nitro-craft copy/db/up
This works essentially the same way as nitro craft
, but runs in a Docker container that adds the required dependencies and forwards your host’s ssh-agent so that it is available to make git, rsync and mysqldump work. All nitro craft
commands should work when run through ./nitro-craft
, not just Craft Copy commands.
Craft Nitro SSH connection fails
The SSH key you want to use to connect to fortrabbit needs to be added to your SSH agent in macOS, this is how it can be accessed inside the Docker container. SSH keys are automatically added to the agent whenever you use them. But if you have created a custom key only for fortrabbit, then you might have to add it manually to the ssh-agent. Either by connecting once using standard ssh, or using this direct command: ssh-add ~/.ssh/[your-custom-ssh-key-name]
Craft Copy with Craft Nitro requirements
- Craft Nitro 2.x and all it’s requirments (Docker)
- Currently only Mac and Linux hosts are supported. Windows is untested at the moment (sorry!). It probably works under WSL but ssh-agent forwarding may be buggy. PR’s welcome!
Advanced usage
Don’t stop. Read on to fully understand Craft Copy!
Config file
The setup
command creates a configuration file within the Craft /config
folder. The file name pattern is fortrabbit.{stage}.yml
, where {stage}
is how you have defined the fortrabbit App environment in the setup. The default for {stage}
is the App name, commonly this can also be production
. The file is version controlled and can be shared with the team and includes all basic settings, plus some extras, like before/after commands. When using multi-staging a configuration file will be created for each fortrabbit App. Also see the example file.
Automatic migrations
Craft Copy incorporates another package called Craft auto migrate. It makes sure that database migrations will always run when deploying to the fortrabbit App. That means that every time you’ll push code via Git, a database migration will be triggered and changes from project.yml
will be applied right away, without the need to click the apply changes button with the Control Panel.
The other way around, when pulling down changes, a database migration will also run. This is configured via a default after command in the config file.
Multi staging
At fortrabbit you can set…