in your web browser and being your local upgrade review.
{% hint style="success" %}
At this point, providing you're satisfied with your local testing, we would recommend that you push your changes to your `origin` remote.
{% endhint %}
### Part 4: Updating Deployment Strategy
{% hint style="danger" %}
Elentra ME 1.19+ requires a deployment recipe transition from Capistrano v2.15 to Deployer v6.8.0 in order to support the new requirement of a local build step for Elentra JS 2.
{% endhint %}
{% hint style="warning" %}
The following transition instructions are to be used as reference-only, as there may be unique circumstances within your existing Capistrano recipe to be considered.
While these instructions may seem complex, the transition is relatively straightforward. If you open both recipe files (Capistrano's `deploy.rb` and Deployer's `deploy.php`) you will see the same/similar variables, structure, and patterns.
{% endhint %}
{% hint style="success" %}
The full Elentra Deployment Tool documentation is available from within the [Elentra Deployment documentation](https://docs.elentra.org/technical/developers/elentra-deployment) section. It may be helpful to read that in addition to this.
{% endhint %}
#### Part 4 / Step 1: Copy Deployer template files into your Branded Edition repository.
Download the raw `.deployignore` and `deploy.php` files from the [Elentra Developer GitHub Repository](https://github.com/ElentraProject/elentra-developer/tree/master/resources/templates/deployer/v6) and place them in your `~/Sites/uni-elentra-1x-me/deployment` directory alongside the existing Capistrano `Capfile` and `config/deploy.rb` files in the `uni/staging` branch.
#### Part 4 / Step 2: Update the Deployer recipe template with actual values.
Open both the Capistrano ("Cap") `deployment/config/deploy.rb` and the Deployer ("Dep") `deployment/deploy.php` deployment recipes in your editor or IDE. There are a few variables at the top of `deploy.php` that need to be set. The following table describes variable names that must set.
| Capistrano (deploy.rb) | Deployer (deploy.php) | Description |
| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| application | application | Application Name (e.g., `uni-elentra-1x-me`) |
| | packagist\_token | Institutional Packagist.com Composer token |
| repository | repository | Branded Edition Elentra ME Git repository location |
| | branch | The default deployment branch (e.g., `master`) within your Branded Edition Elentra ME Git repository. This value is always overridden by the host configuration section (if present), so it not overly important. |
| | repository\_ejs | Default recommended.
This can be left as-is unless you have a Branded Edition Elentra JS Git repository.
|
| | branch\_ejs | Default recommended.
This can be left as-in unless you have a Branded Edition Elentra JS Git repository. This value is always overridden by the host configuration section (if present), so it not overly important.
|
| | enable\_branded\_api | Default value is false.
If you have a Branded Edition Elentra API with your implementation of Elentra then please set this to true.
|
Once you have set all of the variable names correctly in comparison with the Capistrano recipe, the next step is to translate the hosts configuration. The following section illustrates a single staging server and multiple production server transition.
{% hint style="info" %}
For more documentation related to host configuration options, please see the [Deployer Hosts documentation](https://deployer.org/docs/hosts.html), which is quite extensive.
{% endhint %}
**Example Capistrano (deploy.rb) Recipe**
```
# Elentra ME
task :staging do
server "elentra-staging.med.university.edu", :app, :web, :db, :primary => true
set :user, "staging"
set :branch, "uni/staging"
set :environment, "staging"
set :deploy_to, "/var/www/vhosts/elentra-staging.med.university.edu"
end
task :production do
server "elentra01.med.university.edu", :app, :web, :primary => true
server "elentra02.med.university.edu", :app, :web
set :user, "production"
set :branch, "uni/production"
set :environment, "production"
set :deploy_to, "/var/www/vhosts/elentra.med.university.edu"
end
```
**Example Deployer (deploy.php) Recipe**
```
# Elentra ME
// Staging Server
host('elentra-staging.med.university.edu')
->stage('staging')
->user('staging')
->set('branch', 'uni/staging')
->set('branch_ejs', 'develop')
->set('deploy_path', '/var/www/vhosts/elentra-staging.med.university.edu')
->roles('app')
->forwardAgent();
// Production Server
host('elentra01.med.university.edu', 'elentra02.med.university.edu')
->stage('production')
->user('production')
->set('branch', 'uni/production')
->set('branch_ejs', 'master')
->set('deploy_path', '/var/www/vhosts/elentra.med.university.edu')
->roles('app')
->forwardAgent();
```
#### **Part 4 / Step 3: Review the deployment command crosswalk.**
The typical deployment commands used by institutions are referenced below, but please see the [Elentra Deployment documentation](https://docs.elentra.org/technical/developers/elentra-deployment) for a full list of all commands available.
{% hint style="success" %}
The Deployer deployment strategy transition should require no Apache configuration changes and should be fully backwards compatible with your previous Capistrano recipe.
{% endhint %}
| Capistrano | Deployer |
| ----------------------------- | ----------------------- |
| `cap staging deploy` | `dep deploy staging` |
| `cap production deploy` | `dep deploy production` |
| `cap staging deploy:rollback` | `dep rollback staging` |
### Part 5: Testing on Staging
Providing that you have pushed the changes to your `uni/staging` branch to your `origin` remote, you can now deploy the upgrade to your staging environment from within your Docker container.
1. Log into your local `elentra-developer` Docker container, and change to your `deployment` directory:
```bash
docker exec -it elentra-developer bash
cd /var/www/vhosts/uni-elentra-1x-me/deployment
```
2. Deploy changes to your staging server using the new Deployer deployment recipe:
```bash
dep deploy staging
```
3. Providing the deployment was successful, you should now be able to visit in your web browser to begin a thorough review of your upgraded Branded Edition implementation of Elentra ME.
{% hint style="info" %}
For the most accurate review possible, we would recommend that you have a very recent version of your production databases installed and scrubbed loaded on your staging database server. This is typically achieved using the `scrub.sh` shell script included with the Elentra Platform.
{% endhint %}
### Part 6: Deploy to Production
Providing that you have thoroughly tested your upgraded Branded Edition implementation of Elentra ME on within your staging environment, it is safe to proceed with a production upgrade.
1. From within Sourcetree on your developer workstation, open your existing local Elentra ME Branded Edition (i.e., `uni-elentra-1x-me`) repository.
2. Checkout your `uni/production` branch.
3. Right click on your `uni/staging` branch and click "Merge uni/staging into uni/production". This will merge all of the commits that have gone into creating the upgrade, into your `uni/production` branch.
4. Push the commits in the `uni/production` branch to your `origin` remote. Log into your local `elentra-developer` Docker container, and change to your `deployment` directory:
```bash
docker exec -it elentra-developer bash
cd /var/www/vhosts/uni-elentra-1x-me/deployment
```
5. Deploy changes to your production server using the new Deployer deployment recipe:
```bash
dep deploy production
```
6. Providing the deployment was successful, you should now be able to visit in your web browser and enjoy the fact that you are now running the latest version of Elentra ME.
### **Additional Changes**
### app.json has been moved
As of March 22nd, 2021, the ElentraAPI has been upgraded to Laravel 6, which changes the location of the `app.json` file. If you pull from the release branch, or if you're upgrading for the first time, please run these commands on your servers**.**
```
rm /var/www/vhosts/host.name.edu/storage/app/modules/app.json
ln -s /var/www/vhosts/host.name.edu/current/www-root/core/storage/app/modules/app.json /var/www/vhosts/host.name.edu/storage/app/modules/app.json
```