{"id":30009385,"url":"https://github.com/fortrabbit/craft-copy","last_synced_at":"2025-08-31T12:44:12.293Z","repository":{"id":31666854,"uuid":"128561552","full_name":"fortrabbit/craft-copy","owner":"fortrabbit","description":"Deployment tools for Craft on fortrabbit","archived":false,"fork":false,"pushed_at":"2024-10-15T14:11:33.000Z","size":1929,"stargazers_count":76,"open_issues_count":3,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-28T21:24:02.275Z","etag":null,"topics":["craft","craftcms","craftcms-plugin","fortrabbit"],"latest_commit_sha":null,"homepage":"https://www.fortrabbit.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fortrabbit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-07T19:34:24.000Z","updated_at":"2025-06-10T12:49:53.000Z","dependencies_parsed_at":"2023-01-14T19:31:13.341Z","dependency_job_id":"8d703d9d-3f9a-4470-bd50-9d3dbf54b539","html_url":"https://github.com/fortrabbit/craft-copy","commit_stats":{"total_commits":312,"total_committers":13,"mean_commits":24.0,"dds":"0.21794871794871795","last_synced_commit":"39662221ccc107b7097ecb8ea3bc97a8a644389b"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/fortrabbit/craft-copy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortrabbit%2Fcraft-copy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortrabbit%2Fcraft-copy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortrabbit%2Fcraft-copy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortrabbit%2Fcraft-copy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fortrabbit","download_url":"https://codeload.github.com/fortrabbit/craft-copy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fortrabbit%2Fcraft-copy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272982772,"owners_count":25025984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["craft","craftcms","craftcms-plugin","fortrabbit"],"created_at":"2025-08-05T10:47:06.869Z","updated_at":"2025-08-31T12:44:12.253Z","avatar_url":"https://github.com/fortrabbit.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Craft Copy Plugin \n\nThis little command line tool helps to speed up common tasks around Craft CMS deployment on [fortrabbit](https://www.fortrabbit.com/). 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.\n\n## Demos\n\n![demo](https://github.com/fortrabbit/craft-copy/blob/master/resources/craft-copy-db-up.gif \"Database sync\")\n\n![demo](https://github.com/fortrabbit/craft-copy/blob/master/resources/craft-copy-code-up.gif \"Code sync\")\n\n[Here](https://www.youtube.com/watch?v=h8g5t-X6ya4) is a video introdcution (1.5 minutes).\n\n## Requirements\n\n* A local development environment including: Craft 5 (since version 3), PHP 8 and Composer. \n* The following binaries should be executable: `php`, `mysqldump`, `git` and `rsync`\n* A SSH key installed should with your fortrabbit Account (no password auth so far)\n* You need to have an App with fortrabbit\n\nCraft Copy works for Universal Apps and Professional Apps. Asset synchronisation is only available for Universal Apps with local asset volumes. It's known to work locally with Laravel Herd, Laravel Valet and DDEV.\n\n## Installation\n\nBest install Craft Copy in the terminal on your local computer with Composer like so:\n\n```shell\n# Jump into your local Craft CMS folder\ncd your/craft-project\n\n# Require Craft Copy via Composer\ncomposer config platform --unset\ncomposer require fortrabbit/craft-copy -W\n\n# With the latest version of composer (2.2 or higher) you may see this prompt: \n# 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,?] \n#\n# Confirm with `y`\n\n# Install and enable the plugin with Craft CMS\nphp craft plugin/install copy\n```\n\nYou 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](https://plugins.craftcms.com/copy).\n\n## Usage\n\nCraft Copy will always be executed on your local computer in your local development environment.\n\nThe 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.\n\nSome 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`.\n\n### Setup\n\n```shell\n# Connect your development environment with your fortrabbit App\nphp craft copy/setup\n```\n\n### Get help\n\n```shell\n# See a list of available commands\nphp craft help copy\n```\n\n### Database\n\n```shell\n# Dump local DB (backup fortrabbit db) and import it to the fortrabbit App\nphp craft copy/db/up {stage}\n\n# Dump local DB and import it to the fortrabbit App (useful if the fortrabbit db is broken)\nphp craft copy/db/up {stage}  --force\n\n# Dump fortrabbit DB and import it locally\nphp craft copy/db/down {stage}\n```\n\n### Code\n\nWhile 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.\n\n```shell\n# Push code changes to the fortrabbit App\nphp craft copy/code/up {stage}\n\n# Pull code changes from your fortrabbit App\nphp craft copy/code/down {stage}\n```\n\n#### Options and arguments\n* To prevent a prompt, for instance when running the command in a CI pipeline, you can use `php craft copy/code/up -i=0 -m=\"your commit message\"`.\n\n### Asset Volumes\n\nAssets 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.\n\n```shell\n# Sync up a local volume to fortrabbit App\nphp craft copy/volumes/up {stage} {?volumeHandle}\n\n# Sync down a vlume from the fortrabbit App to local\nphp craft copy/volumes/down {stage} {?volumeHandle}\n```\n\n* 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.\n* Remote volumes (S3, Object Storage …) are not supported so far\n\n#### Options and arguments\n\n* {volumeHandle} is the handle name of your asset volume in Craft CMS\n* To sync all volumes, don't provide a volumeHandle (and add `-i=0` to avoid questions)\n* To test what will actually be synced you can add the `-n` option to trigger a dry-run\n\n### Copy all\n\nOften 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:\n\n```shell\n# Sync database, volumes and git from local to your fortrabbit App\nphp craft copy/all/up\n\n# Sync database, volumes and git from your fortrabbit App to local\nphp craft copy/all/down\n```\n\n* This is not including the folder action by default.\n\n## DDEV support\n\nCraft Copy supports [DDEV](https://ddev.com/). Once you got the container running:\n\n1. `ddev auth ssh` - Copy SSH keys from the host into the container\n2. `ddev ssh` - Login to the container\n3. From their proceed as required\n  \nSee our slighlty old [blog post](https://blog.fortrabbit.com/local-craft-dev-site-ddev-development-tool) on how to set it up together.\n\n## Craft Nitro support (deprecated)\n\n**This feature will be removed with the next major version** since Craft Nitro is retired.\n\n## Advanced usage\n\nDon't stop. Read on to fully understand Craft Copy!\n\n\n### Config file\n\nThe `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](#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](#beforeafter-commands) commands. When using [multi-staging](#multi-staging) a configuration file will be created for each fortrabbit App. Also see the [example file](https://github.com/fortrabbit/craft-copy/blob/master/src/fortrabbit.example.yaml).\n\n### Automatic migrations\n\nCraft Copy incorporates another package called [Craft auto migrate](https://github.com/fortrabbit/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.yaml` will be applied right away, without the need to click the apply changes button with the Control Panel. \n\nThe other way around, when pulling down changes, a database migration will also run. This is configured via a default [after command](#beforeafter-commands) in the [config file](#config-file).\n\n### Project Config\n\nCraft Copy alters the behaviour of the `ProjectConfig` class to prevent Project Config actions in the CP. \nBy default, we `apply` the potential changes during deployment after composer install.\n\n\n### Multi staging\n\nAt fortrabbit you can set up multiple Apps to create multiple environments for your project. See the [multi-staging help article](https://help.fortrabbit.com/multi-staging).\n\n#### Multi staging config\n\nOnce your Apps are in place, you connect your local environment with each App.\n\n```shell\n# Run this command to setup a new deployment configuration for each stage\nphp craft copy/setup\n```\n\nThe setup command creates a [config file](#config-file) for each App.\n\n#### Multi staging usage\n\n```shell\n# Copy code and db down from 'production'\nphp craft copy/code/down production\nphp craft copy/db/down production\n\n# Make changes\n# ...\n\n# Copy code and db up to 'staging'\nphp craft copy/code/up staging\nphp craft copy/db/up staging\n```\n\n### Before/after commands\n\nYou can run any script before or after you run common up/down commands with Craft Copy.\n\n* Place the before/after scripts in your [Craft Copy config file](#config-file). \n* The before/after commands will run on your local machine, not on the fortrabbit App. To run scripts while deploying, consider the Composer `post-install-cmd`.\n\n#### Supported commands\n\n* code/up\n* code/down\n* db/up\n* db/down\n* volumes/up\n* volumes/down\n* folder/up\n* folder/down\n\n#### Before/after example\n\nAutomate your deployment pipeline. Every time you push up new code with `code/up` also minify javascript and css and sync it up as well:\n\n```yml\nbefore:\n  # Before deploying code by Git, please:\n  code/up:\n    # 1. Run your NPM production build\n    - \"npm run prod\"\n    # 2. Sync the results of the build up\n    - \"php craft copy/folder/up production web/build/prod -i=0\"\n```\n\nHere is a full config file example: [config/fortrabbit.example.yaml](https://github.com/fortrabbit/craft-copy/blob/master/src/fortrabbit.example.yaml)\n\n### Database to file\n\nThere is also a command to create a local copy of your database to a file. You can create an `.sql` file and also import back such file into the database. Here is the command:\n\n\n```shell\n# Export DB\nphp craft copy/db/to-file filename\n\n# Import DB\nphp craft copy/db/from-file filename\n# Filename is a required parameter\n```\n\nNote that there are also similar Craft CLI commands for this: `php craft backup/db` and `php craft restore/db`.\n\n### Synchronize folders\n\nYou can also synchronize folders which are not in Git or not an Asset Volume. A common use case is to sync up build artifacts such as minified JS or CSS to your fortrabbit App. This can be coupled with [before/after commands](#beforeafter-commands).\n\n```shell\n# Sync up a folder from local to your fortrabbit App\nphp craft copy/folder/up {stage} {folder}\n\n# Example usage\nphp craft copy/folder/up production web/build\n```\n\n* The `{folder}` is your relative path seen from the craft executable (project root)\n\n\n### Using Craft Copy in Docker environments\n\nYou may want to run Craft Copy within any Docker container. You will need the following dependencies to be installed inside the container: \n\n - mysqldump\n - mysql (client)\n - ssh (client)\n - Access to the SSH keys you saved with your fortrabbit Account - for example like [so](https://medium.com/trabe/use-your-local-ssh-keys-inside-a-docker-container-ea1d117515dc)\n\n## How Craft Copy works\n\nWith fortrabbit you can already use Git to deploy code without any extras or plugins. When deploying code by Git Composer also is getting triggered. Craft Copy enhances on that by adding support for files that are excluded from Git such as assets in volumes, folders and database contents. \n\nCraft Copy can help to bring together the different data types required to run Craft CMS. Each data type is unique, so is the transport layer. Here are more details so you can better understand what's going on behind the scenes:\n\n### Template and dependencies code via Git\n\nCraft Copy offers a light weight Git wrapper. The direction will be in most case `up` (push code), since you will develop locally first and then push changes up to the fortrabbit App. Since Git is transport layer and version history, those changes are non-destructive. You can always roll back.\n\nThe `composer.json` is also managed in Git and when you push a change to that file, Composer will run during deployment on fortrabbit. That's not Craft Copy but a fortrabbit feature. So you don't need to login by SSH and run Composer manually. Also you should not trigger any updates with the Craft CMS Control Panel on the fortrabbit App itself.\n\n### Asset Volumes\n\nAny asset files and folders, including image transformations that can be synced up and down with the volumes command. Here rsync will be used. The transport flags are set to be non-destructive. No files will be deleted and you can safely run this operation in any direction without having to fear any data loss. You might need to keep your assets library clean from time to time. \n\n### Database\n\nThe MySQL database is getting copied over by using `mysqldump`. So it basically will export the current status of the database as an `file.sql` and will replace the other database with that file. In other words: This can be a destructive operation. You need to make sure that any content changes affecting the database, like new entries or editing entries are only done in one environment, either locally or on the fortrabbit App. It can not merge changes, like with assets or code. Good news is, that Craft Copy will always create a snapshot file which you can use to roll back.\n\n#### my.conf file\n\nCraft Copy creates a `my.conf` file. It sets some defaults to ensure maximal compability when working with different MySQL versions. See the [annotated file here](https://github.com/fortrabbit/craft-copy/blob/master/src/.my.cnf.example) and read about SUPER priviliges [here](https://help.fortrabbit.com/mysql-troubleshooting#toc-access-denied-missing-super-privileges).\n\n## Troubleshooting Craft Copy\n\nThe setup is usually straight forward when the [system requirements](#requirements) are fulfilled. However, depending on your local setup, you may run into errors. Many errors are MAMP related and easy to fix:\n\n### Local MySQL connection error\n\n```shell\nphp craft install/plugin copy\n  *** installing copy\n  *** failed to install copy: Craft CMS can’t connect to the database with the credentials in config/db.php.\n```\n\n**Fix:** Ensure \"[Allow network access to MySQL](https://craftcms.stackexchange.com/a/26396/4538)\" is ticked in MAMP.\n\n### The mysqldump command does not exist\n\nThe `mysqldump` client is a command line program to backup mysql databases. It is usually included with MySQL installations. Find out if you can access mysqldump:\n\n```shell\nwhich mysqldump\n  mysqldump not found\n```\n\n**Possible fix:** Add the MAMP bin path to your Bash profile:\n\n```shell\necho 'export PATH=/Applications/MAMP/Library/bin:$PATH' \u003e\u003e~/.bash_profile\n```\n\n### PHP cli version is lower than 7.1\n\nFind out the php version on the command line:\n\n```shell\nphp -v\n  PHP 7.0.8 (cli) (built: Jun 26 2016 12:30:44) ( NTS )\n  Copyright (c) 1997-2016 The PHP Group\n  Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies\n     with Zend OPcache v7.0.8, Copyright (c) 1999-2016, by Zend Technologies\n```\n\n**Fix:** Add MAMP php bin path to your Bash profile:\n\n```shell\necho 'export PATH=/Applications/MAMP/bin/php/php7.2.1/bin:$PATH' \u003e\u003e~/.bash_profile\n```\n\n### Composer version conflict\n\nWhen installing the plugin via Composer you may see an error like this:\n\n```shell\ncomposer require fortrabbit/craft-copy:^1.0.0\n  ./composer.json has been updated\n  Loading composer repositories with package information\n  Updating dependencies (including require-dev)\n  Your requirements could not be resolved to an installable set of packages.\n  \n  Problem 1\n  - Installation request for fortrabbit/craft-copy ^1.0.0 -\u003e satisfiable by fortrabbit/craft-copy[1.0.0].\n  - Conclusion: remove symfony/console v3.3.6\n  - Conclusion: don't install symfony/console v3.3.6\n  - fortrabbit/craft-copy 1.0.0 requires symfony/yaml ^4.1\n  [...]\n   Problem 99\n```\n\n**Fix:** Update all existing dependencies:\n\n```shell\ncomposer config platform --unset\ncomposer update\nphp craft migrate/all\n```\n\n### Composer allow plugin issue\n\nYou see a warning like this when trying to deploy:\n\n```shell\nIn PluginManager.php line 762: fortrabbit/craft-auto-migrate contains a Composer plugin  which is blocked by your allow-plugins config. You may add  it to the list if you consider it safe. You can run \"composer config --no-plugins allow-plugins.fortrabbit/craft-auto-migrate [true|false]\" to enable it (true) or disable it explicitly and suppress this exception (false) See https://getcomposer.org/allow-plugins\n```\n\nThat's a new Composer security policy in action and should only happen when you installed the plugin a while ago.\n\n**Fix:** Configure Composer to allow plugins:\n\n```shell\ncomposer config --no-plugins allow-plugins.fortrabbit/craft-auto-migrate true\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffortrabbit%2Fcraft-copy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffortrabbit%2Fcraft-copy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffortrabbit%2Fcraft-copy/lists"}