---
title: "Deployment with Composer"
canonical: "https://kb.uconn.edu/space/IKB/26616725604/Deployment%20with%20Composer"
format: markdown
---
This article will review the requirements and steps included in deployment of Aurora plugins and themes using [the Composer dependency management tool.](https://getcomposer.org/doc/00-intro.md) 

### Composer Basics

Composer is used by PHP projects to ensure all dependencies – whether development or production – are installed and easily accessed within the project directory. Dependencies are organized inside a central `composer.json` file that details the project and declares what and how the project should install its requirements. In normal use cases, these dependencies are installed to a `/vendor` directory that gets required via an `autoload.php` file. With Aurora, Composer installs plugins and themes to their respective directories within the `wp-content` directory utilizing the `composer/installers` [package](https://github.com/composer/installers). 

### Primary Composer File

At the time of writing, the primary Composer file for Aurora deployment can be found in [its repo within the AUR project on Bitbucket](https://bitbucket.org/uconnbitbucket/primary-composer-json/src/master/). This repo contains the requisite `composer.json` file that lists all of the possible plugins and themes that are used by Aurora. **In order for the deployment to install a given dependency, it needs to be included in this file. **

#### Adding to the Composer File

First, the repo of the dependency should be included in the `repositories` section by following the existing trend. Specifically, a new JSON object can be added inside the section that looks like below

```
        {
            "type": "vcs",
            "url": "{repo url}"
        },
```

where `vcs` stands for “Version Control System” and the `url` links to the SSH git address of the repo in Bitbucket. Now that the repo itself is added, the version of the plugin should be added to the `require` section under that using the name and version of the Composer project listed in that repo (more info on this below). 

### Preparing Repo For Composer

Each plugin/theme that is required by Composer needs its own `composer.json` file in the root directory so Composer knows the name and version of the project. This should contain (at a minimum) the following information.

```
{
    "name": "aurora/{name of plugin/theme}",
    "type": "wordpress-plugin / wordpress-theme",
    "version" : "{current version}"
}
```

The `name` listed here should match the requirement in the primary Composer file and the `type` should indicate whether this repo contains a plugin or theme. This type will determine where the repo gets installed when Aurora is deployed, so it must be correct. 

The `version` should match the current version tag of the repo, discussed below. 

#### Commit Tags & Versioning

It is important to keep the Composer version of the plugin up to date with the most recent commit tag so that the Composer deployment uses the most current version of the dependency. A commit tag can be created either via [git commands](https://git-scm.com/book/en/v2/Git-Basics-Tagging) or through the Bitbucket UI when viewing a commit. To do this, just click the desired commit and then “Create tag” on the righthand side. 

![image-20240111-141141.png](media://409c1ba4-70f4-4a0a-9d0b-cd20db8ff9a4)

Enter the “Tag Name” and ensure this versioning matches the one listed in the repo’s Composer file. The commit tag names should always be a version number, i.e. “1.0.0”.  When updates are made to a repo, the following should be done to ensure those changes will be reflected in the next deployment.

1. Commit the changes to the repo and tag the commit appropriately with the next version
2. Update the version in the repo’s `composer.json` file with the new version
3. Update the primary Composer JSON file to include the new versioning of the repo that was changed

#### Alternative to Above

If the deployment should *always* include the most recent version, the `composer.json` file can instead use a branch name to always include the most recent version of that branch. For example, the following JSON snippet requires the `ucomm/caster` `master` branch, making versioning no longer required. 

```
        "ucomm/castor": "dev-master",
```

This can be used elsewhere in the `require` section if a version/update history is not needed for the plugin/theme of that repo.

### Deploying Using Pipelines

Before deploying with Composer, the server needs a user with SSH access and proper permissions for the directory to which Wordpress will be installed. The server and user then need to be included as either [deployment or repo variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/), depending on how they will be used.

#### Building Composer Lock File

To install dependencies, Composer must generate a `composer.lock` file that it will use to install the exact versions of packages outlined in `composer.json`. This build process should likely be separated into its own pipeline like it is in [the primary-composer-json pipelines.](https://bitbucket.org/uconnbitbucket/primary-composer-json/src/master/bitbucket-pipelines.yml) This pipeline starts with a PHP 7.4.3. image before running.

```
  composer update -vvv --no-install --no-dev --no-interaction
```

This will cause Composer to check all dependencies/repos and ensure that the packages that are required are accessible and that the versioning required is available in that repo. The `--no-install` flag means nothing will be installed; the dependencies will be checked and the lock file will be generated. After the generation, the `composer.lock` file gets committed to the repo so everything is up to date. 

#### Server Install

The pipelines directive for installing to a server might look something like this:

```
    test-deploy:
        - step:
            deployment: test
            # scp composer.lock file to server
            script:
              - pipe: atlassian/scp-deploy:1.4.1
                variables:
                  USER: ${DEPLOY_USER}
                  SERVER: ${DEPLOY_SERVER}
                  REMOTE_PATH: ${DEPLOY_PATH}
                  LOCAL_PATH: '${BITBUCKET_CLONE_DIR}/composer.*'
                  SSH_KEY: $SSH_KEY
                  DEBUG: 'true'
                  EXTRA_ARGS: ['-o', 'ServerAliveInterval=10']
                # cd to proper deploy path
              - 'echo "cd ${DEPLOY_PATH}" > build.sh'
                # run "composer install" to install into proper directories  
              - 'echo "composer install -vvv --no-dev" >> build.sh'
              - pipe: atlassian/ssh-run:0.7.0
                variables:
                  SSH_USER: ${DEPLOY_USER}
                  SERVER: ${DEPLOY_SERVER}
                  SSH_KEY: $SSH_KEY
                  DEBUG: 'true'
                  MODE: 'script'
                  COMMAND: 'build.sh'
```

The above uses the following variables:

- DEPLOY_USER : the user with proper permissions outlined above
- DEPLOY_SERVER : the hostname of the server being deployed to
- DEPLOY_PATH : the path on the server to the directory above the Wordpress install
- SSH_KEY : key used to SSH to the remote server

This approach places the following instructions into a bash script, SSHs to the server, and runs the script. This script will 

- change directory to the proper install path
- run `composer install` to install all the dependencies of the project into their proper locations. The `no-dev` flag means Composer will skip developer dependencies when installing, since it is assumed this is a production release and will not be used for development. If this is not your intended use case, you may want to remove that flag

#### Rolling Back

To roll back an update, just re-deploy a previous build. Because each build makes its own branch, just select the desired build branch to be deployed from the pipelines dropdown. 

![image-20240117-152205.png](media://1d8fdb57-d61d-49e8-9ab6-5d282b0b9498)

This deployment will overwrite the existing contents and revert plugins and themes to the state they were for that build.

#### Steps to Deploy

If you wish to update a package and deploy it, follow the steps below.

1. Make sure there is an updated `composer.json` file in the repo
  1. Also be sure that there is a commit tag that matches the versioning in the JSON file
2. Update the `composer.json` file in the Primary Composer JSON repo and push the changes
3. Navigate to the Pipelines page of the Primary Composer JSON repo and select the master branch, then the `custom: create-composer-lock` pipeline. This will update all packages, generate a new lock file, and push it to a new branch.
  1. Fix any errors at this step, such as erroneous versioning
4. Next select Pipelines again, then the branch you’d like to deploy (their servers are 5 hours ahead of EST), and finally where you’d like to deploy it. For instance, test0 would use the `custom: test0-deploy` pipeline
  1. Check for any errors that occur and fix them, restarting if necessary