README.md 4.08 KB
Newer Older
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1
# Using Dpl as deployment tool
Douwe Maan's avatar
Douwe Maan committed
2

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
3 4 5
[Dpl](https://github.com/travis-ci/dpl) (dee-pee-ell) is a deploy tool made for
continuous deployment that's developed and used by Travis CI, but can also be
used with GitLab CI.
Douwe Maan's avatar
Douwe Maan committed
6

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
7
>**Note:**
Rosen Stoyanov's avatar
Rosen Stoyanov committed
8
We recommend to use Dpl if you're deploying to any of these services:
9
<https://github.com/travis-ci/dpl#supported-providers>.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
10 11 12 13 14 15 16 17

## 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:
Douwe Maan's avatar
Douwe Maan committed
18 19 20 21 22

```
gem install dpl
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
23 24
This allows you to test all commands from your local terminal, rather than
having to test it on a CI server.
Douwe Maan's avatar
Douwe Maan committed
25 26

If you don't have Ruby installed you can do it on Debian-compatible Linux with:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
27

Douwe Maan's avatar
Douwe Maan committed
28 29 30 31 32 33 34 35 36
```
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.

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`.
37
There's more and all possible parameters can be found here: <https://github.com/travis-ci/dpl#heroku>.
Douwe Maan's avatar
Douwe Maan committed
38

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
39
```yaml
Douwe Maan's avatar
Douwe Maan committed
40
staging:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
41 42
  stage: deploy
  script:
Douwe Maan's avatar
Douwe Maan committed
43 44 45 46 47 48 49 50
  - gem install dpl
  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
```

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.

To use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers).

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
51 52
## Using Dpl with Docker

Douwe Maan's avatar
Douwe Maan committed
53 54 55 56
When you use GitLab Runner you most likely configured it to use your server's shell commands.
This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner).
It also means that most probably in your Docker container you don't have the Ruby runtime installed.
You will have to install it:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
57 58

```yaml
Douwe Maan's avatar
Douwe Maan committed
59
staging:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
60 61
  stage: deploy
  script:
Douwe Maan's avatar
Douwe Maan committed
62 63 64 65 66 67 68 69
  - apt-get update -yq
  - apt-get install -y ruby-dev
  - gem install dpl
  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
  only:
  - master
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
70 71
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.
Douwe Maan's avatar
Douwe Maan committed
72 73
The above example is valid for all Debian-compatible systems.

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
74 75 76 77 78 79 80
## 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.
Douwe Maan's avatar
Douwe Maan committed
81 82
The final `.gitlab-ci.yml` for that setup would look like this:

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
83
```yaml
Douwe Maan's avatar
Douwe Maan committed
84
staging:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
85 86
  stage: deploy
  script:
Douwe Maan's avatar
Douwe Maan committed
87 88 89 90
  - gem install dpl
  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
  only:
  - master
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
91

Douwe Maan's avatar
Douwe Maan committed
92
production:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
93 94
  stage: deploy
  script:
Douwe Maan's avatar
Douwe Maan committed
95 96 97 98 99 100 101
  - gem install dpl
  - dpl --provider=heroku --app=my-app-production --api-key=$HEROKU_PRODUCTION_API_KEY
  only:
  - tags
```

We created two deploy jobs that are executed on different events:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
102

Douwe Maan's avatar
Douwe Maan committed
103
1. `staging` is executed for all commits that were pushed to `master` branch,
Marcel Amirault's avatar
Marcel Amirault committed
104
1. `production` is executed for all pushed tags.
Douwe Maan's avatar
Douwe Maan committed
105 106

We also use two secure variables:
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
107

Douwe Maan's avatar
Douwe Maan committed
108
1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
Marcel Amirault's avatar
Marcel Amirault committed
109
1. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
Douwe Maan's avatar
Douwe Maan committed
110

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
111 112 113
## Storing API keys

Secure Variables can added by going to your project's
114
**Settings ➔ CI / CD ➔ Variables**. The variables that are defined
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
115 116 117 118 119 120 121
in the project settings are sent along with the build script to the Runner.
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):
Douwe Maan's avatar
Douwe Maan committed
122

Marcel Amirault's avatar
Marcel Amirault committed
123 124
1. `$VARIABLE` - use it for non-Windows runners
1. `%VARIABLE%` - use it for Windows Batch runners
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
125 126

Read more about the [CI variables](../../variables/README.md).