cadf876d37
This also documents a review app workflow, and hints towards future extensions of the platform. Closes #2975 [ci skip]
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# Deploying with Gitlab CI
|
|
|
|
Gitlab-CI can be used to automatically deploy a Dokku application using the [ilyasemenov/gitlab-ci-git-push image](https://github.com/IlyaSemenov/gitlab-ci-git-push) docker image.
|
|
|
|
## Prerequisites
|
|
|
|
Make sure you have a Gitlab account and a Dokku project hosted on Gitlab. This method works whether if you are using buildpacks or Dockerfile.
|
|
|
|
Make sure you have set up an app on the remote machine following [these instructions](http://dokku.viewdocs.io/dokku/deployment/application-deployment/) and can successfully deploy to it from the local machine.
|
|
|
|
## Deploy automatically to production
|
|
|
|
### Add a secret variable
|
|
|
|
Browse to the repository in question and visit the following path: `the Gitlab project > Settings > CI/CD.`
|
|
|
|
Click on `Secret variables > Expand` and fill in the blanks.
|
|
|
|
- Key: `SSH_PRIVATE_KEY`
|
|
- Value: paste in an SSH private key registered in Dokku:
|
|
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
...
|
|
-----END RSA PRIVATE KEY-----
|
|
|
|
- Environment scope: `production` (This make sure that `SSH_PRIVATE_KEY` is not available on merge requests or tests)
|
|
- Protected: Do not check this checkbox unless you know what you are doing
|
|
|
|
### Add CI script
|
|
|
|
Create a file named `.gitlab-ci.yml` at the root directory of the repository with the following contents:
|
|
|
|
```yaml
|
|
stages:
|
|
- deploy
|
|
|
|
variables:
|
|
APP_NAME: node-js-app
|
|
|
|
deploy:
|
|
image: ilyasemenov/gitlab-ci-git-push
|
|
stage: deploy
|
|
environment:
|
|
name: production
|
|
url: https://$APP_NAME.dokku.me/
|
|
only:
|
|
- master
|
|
script:
|
|
- git-push ssh://dokku@dokku.me:22/$APP_NAME
|
|
```
|
|
|
|
You will need to modify the `APP_NAME` variable to the correct value for your application name.
|
|
|
|
Running `git push origin master` will now trigger a gitlab-ci pipeline that will automatically deploy your application to your Dokku server. Go to your project on Gitlab and visit "Project > Pipelines" to see the deployment log.
|
|
|
|
|
|
## Review Applications
|
|
|
|
One useful feature of gitlab is to be able to create review applications for non-production branches. This allows teams to review changes _before_ they are pushed to production. First, recreate the `SSH_PRIVATE_KEY` secret - do not delete the existing secret - but scoped to the `review/*` environment. This will allow non-production gitlab environments access to the secret.
|
|
|
|
Next, we'll need to create the `review_app` gitlab job in our `.gitlab-ci.yaml`.
|
|
|
|
```yaml
|
|
review_app:
|
|
image: ilyasemenov/gitlab-ci-git-push
|
|
stage: deploy
|
|
environment:
|
|
name: review/$CI_ENVIRONMENT_SLUG
|
|
url: https://$CI_ENVIRONMENT_SLUG.dokku.me/
|
|
on_stop: stop_review_app
|
|
only:
|
|
- branches
|
|
except:
|
|
- master
|
|
script:
|
|
- mkdir -p ~/.ssh && echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
|
|
- ssh-keyscan -H 22 "dokku.me" >> ~/.ssh/known_hosts
|
|
- ssh -t dokku@dokku.me -- apps:clone --ignore-existing --skip-deploy "$APP_NAME" "$CI_ENVIRONMENT_SLUG"
|
|
- git-push ssh://dokku@dokku.me:22/$CI_ENVIRONMENT_SLUG
|
|
```
|
|
|
|
The first two lines ensure that Gitlab can talk to the Dokku server. Next, we take advantage of the `apps:clone` command, and clone the existing application and all of it's configuration to a new location. If the new application already exists, the third line of the `script` step will be ignored. We also ignore the first deploy script to speed up the cloning process. Finally, the fourth line of the `script` step will deploy the code as normal.
|
|
|
|
The above only runs for non-master branches, and will _also_ trigger an `on_stop` job called `stop_review_app`. When the branch is deleted or the code is merged, the `stop_review_app` job will be triggered.
|
|
|
|
```yaml
|
|
stop_review_app:
|
|
image: ilyasemenov/gitlab-ci-git-push
|
|
stage: deploy
|
|
environment:
|
|
name: review/$CI_ENVIRONMENT_SLUG
|
|
action: stop
|
|
when: manual
|
|
script:
|
|
- mkdir -p ~/.ssh && echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
|
|
- ssh-keyscan -H 22 "dokku.me" >> ~/.ssh/known_hosts
|
|
- ssh -t dokku@dokku.me -- --force apps:destroy "$CI_ENVIRONMENT_SLUG"
|
|
```
|
|
|
|
The `stop_review_app` step will delete the temporary application, cleaning up now unused server resources.
|
|
|
|
Going further, the following modifications can be done:
|
|
|
|
- Notify via chat whenever a review application is created/destroyed.
|
|
- Push to a separate, staging server as opposed to a production server.
|
|
- Clone a "staging" application so that review applications do not affect production datasets.
|