> For the complete documentation index, see [llms.txt](https://docs.elentra.org/technical/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elentra.org/technical/developers/elentra-deployment.md).
# Elentra Deployment
As of Elentra ME 1.19, the recommended deployment strategy for deploying Elentra to servers is to use a PHP-based deployment tool called [Deployer](https://deployer.org). The Elentra Deployment Tool v2.0.0 recipe is based off of Deployer v6.8.0, which comes pre-installed with the Elentra Developer Docker environment and can easily be [installed on host workstations or CI/CD servers](https://deployer.org/docs/installation.html).
## Obtaining Elentra Deployment Tool
To obtain the standard Elentra Deployment Tool template, you can either:
1. If your local `elentra-developer` Docker environment is up to date, then the template already exists on your computer in the `~/Documents/elentra-developers/resources/templates/deployer/v6` directory. If you're not up to date, simply pull down the latest commits from the `master` branch.
2. Alternatively, you can always download the latest from our [elentra-developer GitHub repository](https://github.com/ElentraProject/elentra-developer/tree/master/resources/templates/deployer/v6).
## Configuration Variables
The following describes the default available deployment variables.
| Variable | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `application` | Application Name (e.g.,`uni-elentra-1x-me`) |
| `packagist_token` | Institutional Packagist.com Composer token |
| `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` | Branded Edition Elentra JS 2.x Git repository location. |
| `branch_ejs` | The default deployment branch (e.g., `master`) within your 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` | If you have a Branded Edition Elentra API with your implementation of Elentra then please set this to `true`. Default value is `false`. |
| `allow_anonymous_stats` | It is not recommended to change this value. Default value is `false`. |
| `build_directory` | Local build directory where repositories are stored before deployment. Default value is `/tmp`. |
| `clear_paths` | Array of files or directories removed from host(s) after deployment. Default value is `www-root/setup`. |
| `default_stage` | Default stage to be deployed with dep deploy. Default value is `staging`. |
| `enable_restart_supervisor` | Restart supervisord during the deployment process. Requires appropriate permissions. Default value is `true`. |
| `exclude_paths` | Exclude any files or directories in Elentra's .deployignore from deployment upload. Default value is `true`. |
| `git_tty` | Allocate tty for git clone. Default value is `false`. |
| `keep_releases` | Number of previous deployments to keep on the server. Default value is `10`. |
## Host Configuration
{% 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 %}
### Single Server
This section illustrates a single server that has multiple Apache virtual hosts defined, which are used for both staging and production.
```
// Staging Server
host('elentra.med.university.edu/staging')
->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('elentra.med.university.edu/production')
->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();
```
### Single Staging Server, Multiple Production Servers
This section illustrates a single staging server and multiple separate production server hosts.
{% hint style="success" %}
Tip: When deploying to multiple production servers, you should use the `-p` or `--parallel` flag to deploy to multiple servers at the same time: `dep deploy production -p`
Deployer also supports host ranges (e.g., `elentra[01:05].med.university.edu`).
{% endhint %}
```
// 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();
```
## Deployment Commands
{% hint style="info" %}
Deployer deployment commands are typically executed from within your Elentra Developer Docker Environment within the `/var/www/vhosts/uni-elentra-1x-me/deployment` directory, but can also be executed by your CI/CD server to automate the deployment process.
{% endhint %}
### Commonly Used Commands
| Deployer | Notes | | |
| ----------------------- | ------------------------------------------------------------------------------------ | -- | ---------------------------------------------------------- |
| `dep deploy staging` | | | |
| `dep deploy production` | Add -p flag to speed up multi-server deployments.
Add -v | vv | vvv flag to increase the verbosity of messages.
|
| `dep rollback staging` | | | |
| `dep ssh hostname` | Connect via SSH to the specified host. | | |
### Command Reference
```
Options:
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
-f, --file[=FILE] Specify Deployer file
--tag=TAG Tag to deploy
--revision=REVISION Revision to deploy
--branch=BRANCH Branch to deploy
--first-run Skips deployment steps not required during initial deployment
--force-build Deletes the local build directories and forces a new build
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
autocomplete Install command line autocompletion capabilities
build Build all required application components
cleanup Cleaning up old releases
deploy Deploy Elentra ME to host(s)
help Displays help for a command
init Initialize deployer in your project
list Lists commands
rollback Rollback to previous release
run Run any arbitrary command on hosts
self-update Updates deployer.phar to the latest version
ssh Connect to host through ssh
build
build:clean Remove all build directories
build:ejs2 Local: Build Elentra JS 2.x, if required
build:ejs2:clean Local: Remove Elentra JS 2.x local build directory
build:me Local: Build Elentra ME
build:me:clean Local: Remove Elentra ME local build directory
build:prerequisites Local: Test for build prerequisites
config
config:current Show current paths
config:dump Print host configuration
config:hosts Print all hosts
debug
debug:task Display the task-tree for a given task
deploy
deploy:clear_paths Cleaning up files and/or directories
deploy:copy_dirs Copy directories
deploy:lock Lock deploy
deploy:migrate Once: Run database migrations (on first host in stage only)
deploy:prepare Preparing host for deploy
deploy:release Prepare release. Clean up unfinished releases and prepare next release
deploy:shared Creating symlinks for shared files and dirs
deploy:symlink Creating symlink to release
deploy:unlock Unlock deploy
deploy:writable Make writable dirs
finalize
finalize:clear_cache Clear the PHP opcode cache
finalize:restart_supervisor Restart supervisord daemon
```