Merge branch 'dpl-doc' into 'master'

Added documentation about the use of Dpl

Please review.

1. Is that clear how to use Dpl?
2. Where the examples should be stored?
3. What should be else added? Maybe example for different provider?

See merge request !170

5 files changed, 240 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index 8307276..c44ef03 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -6,6 +6,7 @@
 + [Update](update/README.md)
 + [Runners](runners/README.md)
 + [Builds Configuration](builds_configuration/README.md)
++ [Deployment](deployment/README.md)
 + [Permissions](permissions/README.md) User permissions
 + [Rake Tasks](raketasks/README.md) Backup and restore take tasks
 + [Migrating to packaged CI](migration_to_omnibus/README.md)
diff --git a/doc/deployment/README.md b/doc/deployment/README.md
new file mode 100644
index 0000000..ffd841c
--- /dev/null
+++ b/doc/deployment/README.md
@@ -0,0 +1,98 @@
+## Using Dpl as deployment tool
+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. 
+
+**We recommend to use Dpl, if you're deploying to any of these of these services: https://github.com/travis-ci/dpl#supported-providers**.
+
+### Requirements
+To use Dpl you need at least Ruby 1.8.7 with ability to install gems.
+
+### Basic usage
+The Dpl can be installed on any machine with:
+```
+gem install dpl
+```
+
+This allows you to test all commands from your shell, rather than having to test it on a CI server.
+
+If you don't have Ruby installed you can do it on Debian-compatible Linux with:
+```
+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`.
+There's more and all possible parameters can be found here: https://github.com/travis-ci/dpl#heroku
+
+```
+staging:
+  type: deploy
+  - 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).
+
+### Using Dpl with Docker
+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:
+```
+staging:
+  type: deploy
+  - 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
+```
+
+The first line `apt-get update -yq` updates the list of available packages, where second `apt-get install -y ruby-dev` install `Ruby` runtime on system.
+The above example is valid for all Debian-compatible systems.
+
+### Usage in staging and production
+It's pretty common in developer workflow to have staging (development) and production environment.
+If we consider above example: we would like to deploy `master` branch to `staging` and `all tags` to `production` environment.
+The final `.gitlab-ci.yml` for that setup would look like this:
+
+```
+staging:
+  type: deploy
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+  
+production:
+  type: deploy
+  - 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:
+1. `staging` is executed for all commits that were pushed to `master` branch,
+2. `production` is executed for all pushed tags.
+
+We also use two secure variables:
+1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
+2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
+
+### Storing API keys
+In GitLab CI 7.12 a new feature was introduced: Secure Variables.
+Secure Variables can added by going to `Project > Variables > Add Variable`. 
+**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
+The variables that are defined in the project settings are send along with the build script to the runner.
+The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml.
+It is also important that secret's value is hidden in the build log.
+
+You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners):
+1. `$SECRET_VARIABLE` - use it for non-Windows runners
+2. `%SECRET_VARIABLE%` - use it for Windows Batch runners
diff --git a/doc/examples/README.md b/doc/examples/README.md
index 444d68b..23e9740 100644
--- a/doc/examples/README.md
+++ b/doc/examples/README.md
@@ -35,6 +35,8 @@ CI_PROJECT_DIR
 + [Build script for Omniauth LDAP](build-script-for-omniauth-ldap.md)
 + [Build script GitLab CE](build_script_gitlab_ce.md)
 + [Build script for Sencha deploy PhoneGapBuild](build_script_sencha_deploy_phonegapbuild.md)
++ [Test and deploy Ruby Application to Heroku](test-and-deploy-ruby-application-to-heroku.md)
++ [Test and deploy Python Application to Heroku](test-and-deploy-python-application-to-heroku.md)
 
 # Configuring runner examples
 
diff --git a/doc/examples/test-and-deploy-python-application-to-heroku.md b/doc/examples/test-and-deploy-python-application-to-heroku.md
new file mode 100644
index 0000000..859adf5
--- /dev/null
+++ b/doc/examples/test-and-deploy-python-application-to-heroku.md
@@ -0,0 +1,72 @@
+## Test and Deploy a python application
+This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
+
+You can checkout the example [source](https://gitlab.com/ayufan/python-getting-started) and check [CI status](https://ci.gitlab.com/projects/4080).
+
+### Configure project
+This is what the `.gitlab-ci.yml` file looks like for this project:
+```yaml
+test:
+  script:
+  # this configures django application to use attached postgres database that is run on `postgres` host
+  - export DATABASE_URL=postgres://postgres:@postgres:5432/python-test-app
+  - apt-get update -qy
+  - apt-get install -y python-dev python-pip
+  - pip install -r requirements.txt
+  - python manage.py test
+
+staging:
+  type: deploy
+  script:
+  - apt-get update -qy
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-python-test-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+
+production:
+  type: deploy
+  script:
+  - apt-get update -qy
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-python-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY
+  only:
+  - tags
+```
+
+This project has three jobs:
+1. `test` - used to test rails application,
+2. `staging` - used to automatically deploy staging environment every push to `master` branch
+3. `production` - used to automatically deploy production environmnet for every created tag
+
+### Store API keys
+You'll need to create two variables in `Project > Variables`:
+1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
+2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
+
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
+
+### Create Heroku application
+For each of your environments, you'll need to create a new Heroku application.
+You can do this through the [Dashboard](https://dashboard.heroku.com/).
+
+### Create runner
+First install [Docker Engine](https://docs.docker.com/installation/).
+To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). 
+You can use public runners available on `ci.gitlab.com`, but you can register your own:
+```
+gitlab-ci-multi-runner register \
+  --non-interactive \
+  --url "https://ci.gitlab.com/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "python-3.2" \
+  --executor "docker" \
+  --docker-image python:3.2 \
+  --docker-postgres latest
+```
+
+With the command above, you create a runner that uses [python:3.2](https://registry.hub.docker.com/u/library/python/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+
+To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
diff --git a/doc/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/examples/test-and-deploy-ruby-application-to-heroku.md
new file mode 100644
index 0000000..36376bd
--- /dev/null
+++ b/doc/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -0,0 +1,67 @@
+## Test and Deploy a ruby application
+This example will guide you how to run tests in your Ruby application and deploy it automatiacally as Heroku application.
+
+You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://ci.gitlab.com/projects/4050).
+
+### Configure project
+This is what the `.gitlab-ci.yml` file looks like for this project:
+```yaml
+test:
+  script:
+  - apt-get update -qy
+  - apt-get install -y nodejs
+  - bundle install --path /cache
+  - bundle exec rake db:create RAILS_ENV=test
+  - bundle exec rake test
+
+staging:
+  type: deploy
+  script:
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-ruby-test-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+
+production:
+  type: deploy
+  script:
+  - gem install dpl
+  - dpl --provider=heroku --app=gitlab-ci-ruby-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY
+  only:
+  - tags
+```
+
+This project has three jobs:
+1. `test` - used to test rails application,
+2. `staging` - used to automatically deploy staging environment every push to `master` branch
+3. `production` - used to automatically deploy production environmnet for every created tag
+
+### Store API keys
+You'll need to create two variables in `Project > Variables`:
+1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
+2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
+
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
+
+### Create Heroku application
+For each of your environments, you'll need to create a new Heroku application.
+You can do this through the [Dashboard](https://dashboard.heroku.com/).
+
+### Create runner
+First install [Docker Engine](https://docs.docker.com/installation/).
+To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner).
+You can use public runners available on `ci.gitlab.com`, but you can register your own:
+```
+gitlab-ci-multi-runner register \
+  --non-interactive \
+  --url "https://ci.gitlab.com/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "ruby-2.1" \
+  --executor "docker" \
+  --docker-image python:2.1 \
+  --docker-postgres latest
+```
+
+With the command above, you create a runner that uses [ruby:2.1](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+
+To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.