2019-06-11 12:39:26 -04:00
---
2020-05-29 14:08:26 -04:00
stage: Release
2020-12-01 10:09:28 -05:00
group: Release
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-06-11 12:39:26 -04:00
type: tutorial
---
2017-03-10 15:36:50 -05:00
# Using Dpl as deployment tool
2015-08-25 21:42:46 -04:00
2020-01-07 22:08:05 -05:00
[Dpl ](https://github.com/travis-ci/dpl ) (pronounced like the letters D-P-L) is a deploy tool made for
2017-03-10 15:36:50 -05:00
continuous deployment that's developed and used by Travis CI, but can also be
2020-03-26 23:07:56 -04:00
used with GitLab CI/CD.
2015-08-25 21:42:46 -04:00
2019-06-11 12:39:26 -04:00
Dpl can be used to deploy to any of the [supported providers ](https://github.com/travis-ci/dpl#supported-providers ).
2017-03-10 15:36:50 -05:00
## Requirements
To use Dpl you need at least Ruby 1.9.3 with ability to install gems.
## Basic usage
Dpl can be installed on any machine with:
2015-08-25 21:42:46 -04:00
2020-02-05 04:08:43 -05:00
```shell
2015-08-25 21:42:46 -04:00
gem install dpl
```
2017-03-10 15:36:50 -05:00
This allows you to test all commands from your local terminal, rather than
having to test it on a CI server.
2015-08-25 21:42:46 -04:00
If you don't have Ruby installed you can do it on Debian-compatible Linux with:
2017-03-10 15:36:50 -05:00
2020-02-05 04:08:43 -05:00
```shell
2015-08-25 21:42:46 -04:00
apt-get update
apt-get install ruby-dev
```
The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more.
To use it simply define provider and any additional parameters required by the provider.
2021-01-27 16:09:12 -05:00
For example if you want to use it to deploy your application to Heroku, you need to specify `heroku` as provider, specify `api_key` and `app` .
2021-01-22 19:08:46 -05:00
All possible parameters can be found in the [Heroku API section ](https://github.com/travis-ci/dpl#heroku-api ).
2015-08-25 21:42:46 -04:00
2017-03-10 15:36:50 -05:00
```yaml
2015-08-25 21:42:46 -04:00
staging:
2017-03-10 15:36:50 -05:00
stage: deploy
script:
2020-07-03 05:08:53 -04:00
- gem install dpl
2021-01-27 16:09:12 -05:00
- dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY
2015-08-25 21:42:46 -04:00
```
2019-09-23 05:06:22 -04:00
In the above example we use Dpl to deploy `my-app-staging` to Heroku server with API key stored in `HEROKU_STAGING_API_KEY` secure variable.
2015-08-25 21:42:46 -04:00
To use different provider take a look at long list of [Supported Providers ](https://github.com/travis-ci/dpl#supported-providers ).
2017-03-10 15:36:50 -05:00
## Using Dpl with Docker
2020-12-17 16:09:57 -05:00
In most cases, you configured [GitLab Runner ](https://docs.gitlab.com/runner/ ) to use your server's shell commands.
2020-06-10 14:09:15 -04:00
This means that all commands are run in the context of local user (e.g. `gitlab_runner` or `gitlab_ci_multi_runner` ).
2015-08-25 21:42:46 -04:00
It also means that most probably in your Docker container you don't have the Ruby runtime installed.
2020-12-17 16:09:57 -05:00
You must install it:
2017-03-10 15:36:50 -05:00
```yaml
2015-08-25 21:42:46 -04:00
staging:
2017-03-10 15:36:50 -05:00
stage: deploy
script:
2020-07-03 05:08:53 -04:00
- apt-get update -yq
- apt-get install -y ruby-dev
- gem install dpl
2021-01-27 16:09:12 -05:00
- dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY
2015-08-25 21:42:46 -04:00
only:
2020-07-03 05:08:53 -04:00
- master
2015-08-25 21:42:46 -04:00
```
2017-03-10 15:36:50 -05:00
The first line `apt-get update -yq` updates the list of available packages,
where second `apt-get install -y ruby-dev` installs the Ruby runtime on system.
2015-08-25 21:42:46 -04:00
The above example is valid for all Debian-compatible systems.
2017-03-10 15:36:50 -05:00
## Usage in staging and production
It's pretty common in the development workflow to have staging (development) and
production environments
Let's consider the following example: we would like to deploy the `master`
branch to `staging` and all tags to the `production` environment.
2015-08-25 21:42:46 -04:00
The final `.gitlab-ci.yml` for that setup would look like this:
2017-03-10 15:36:50 -05:00
```yaml
2015-08-25 21:42:46 -04:00
staging:
2017-03-10 15:36:50 -05:00
stage: deploy
script:
2020-07-03 05:08:53 -04:00
- gem install dpl
2021-01-27 16:09:12 -05:00
- dpl --provider=heroku --app=my-app-staging --api_key=$HEROKU_STAGING_API_KEY
2015-08-25 21:42:46 -04:00
only:
2020-07-03 05:08:53 -04:00
- master
2017-03-10 15:36:50 -05:00
2015-08-25 21:42:46 -04:00
production:
2017-03-10 15:36:50 -05:00
stage: deploy
script:
2020-07-03 05:08:53 -04:00
- gem install dpl
2021-01-27 16:09:12 -05:00
- dpl --provider=heroku --app=my-app-production --api_key=$HEROKU_PRODUCTION_API_KEY
2015-08-25 21:42:46 -04:00
only:
2020-07-03 05:08:53 -04:00
- tags
2015-08-25 21:42:46 -04:00
```
We created two deploy jobs that are executed on different events:
2017-03-10 15:36:50 -05:00
2015-08-25 21:42:46 -04:00
1. `staging` is executed for all commits that were pushed to `master` branch,
2018-11-11 18:43:25 -05:00
1. `production` is executed for all pushed tags.
2015-08-25 21:42:46 -04:00
We also use two secure variables:
2017-03-10 15:36:50 -05:00
2015-08-25 21:42:46 -04:00
1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
2018-11-11 18:43:25 -05:00
1. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
2015-08-25 21:42:46 -04:00
2017-03-10 15:36:50 -05:00
## Storing API keys
2020-12-17 16:09:57 -05:00
To add secure variables, navigate to your project's
2020-12-01 13:09:42 -05:00
**Settings > CI / CD > Variables**. The variables that are defined
2020-09-12 05:09:53 -04:00
in the project settings are sent along with the build script to the runner.
2017-03-10 15:36:50 -05:00
The secure variables are stored out of the repository. Never store secrets in
your project's `.gitlab-ci.yml` . It is also important that the secret's value
is hidden in the job log.
You access added variable by prefixing it's name with `$` (on non-Windows runners)
or `%` (for Windows Batch runners):
2015-08-25 21:42:46 -04:00
2018-11-11 18:43:25 -05:00
1. `$VARIABLE` - use it for non-Windows runners
1. `%VARIABLE%` - use it for Windows Batch runners
2017-03-10 15:36:50 -05:00
Read more about the [CI variables ](../../variables/README.md ).