The instructions how to build project should be stored in project repository in a .deployer.yml file. This design choice allows configuration versioning and quick setup at the same time.

The deployer file has two main sections, the pipeline and jobs. Pipeline section should contain list of stages with information if certain stage should run automatically. Jobs section should contain list of jobs, containing list of commands required to complete each job.

Please note that Dick the Deployer Worker runs commands by bash inside docker container. Only containers with bash available will work.

image: debian:latest

variables: # list of environment variables injected to each command
  - key: VERSION
    value: 1.2.3
    
pipeline:
  stages:
  - name: first # name of stage
    autorun: true # if the stage should run automatically, default false
  - name: second
    autorun: true

jobs: 
  - stage: first # name of stage this job belongs to
    name: echo foo # name of this job
    requireRepository: true # if the job require sources from repository, default false
    deploy: # list of commands in this job
      - echo foo
  - stage: second
    name: echo bar
    deploy:
      - exit 1

Examples

Example .deployer.yml files are available in examples repository. Please check different branches for different configuration options.

There is an automated deployment for quick installation. You can set various options that should take care of most configurations. However, if you want a full customized install, you can treat the automated deployment script as an example.

Automated deployment will deploy Dick the Deployer using current Docker host.

Note: you must have a Docker available.

Once deployed, the script will output the URL to connect and command required to run some workers.

curl https://dick-the-deployer.github.io/deploy | bash -s

Note: if you get an error “Cannot communicate securely with peer: no common encryption algorithm(s).” you need to specify algorithm manually curl --ciphers ecdhe_ecdsa_aes_256_sha https://dick-the-deployer.github.io/deploy | bash -s

For full usage details:

curl -s https://dick-the-deployer.github.io/deploy | bash -s -- -h

  ACTION: this is the action to use (deploy-web, upgrade-web, remove-web, deploy-workers, upgrade-workers, remove-workers)
  VERSION: version of docker images to use, default latest
  PORT: port to run web, default 8080
  WORKERS: this is the number of workers to create in deploy-workers action
  PREFIX: this is the prefix used by all Dick The Deployer components
  DICK_WEB_ADDRESS: this is the Dick The Deployer Web address used by workers to register in

Note: all variables are optional.

There are also several advanced options not included in full usage, please refer to the script content for details.

Options

To customize the deployment, you can specify the following environment variables.

Action

This controls the action for the script. Available options are:

• deploy-web: Deploy new Dick the Deployer instance
• upgrade-web: Upgrade Dick the Deployer instance.
• remove-web: Remove Dick the Deployer instance. (Some additional steps may be required, as printed by script)
• deploy-workers: Deploy two Workers and link them to Web. DICK_WEB_ADDRESS is required.
• upgrade-workers: Upgrade each available Worker instance.
• remove-workers: Remove each Worker instance.

Version

Version of Dick the Deployer container pulled from registry.

PORT

Port used by Dick the Deployer - Web module.

To notify Dick the Deployer about the changes in repository you can use generic hook. To do so please send POST request to api/hooks endpoint, with json body:

{
    host: 'my-gitlab.example.com'
    path: 'open-source/wizzard'
    ref: 'master'
    sha: '44a5d78fd58cb9d5de4'
    lastMessage: 'Wand support implemented'
}

You can automate this using post-commit hook feature. Docs are avaliable here.

To enable Gitlab integration open your project settings in Gitlab, and then go to Web Hooks page.

As URL use your Dick the Deployer instance address with /api/hooks/gitlab path. Make sure that Trigger Push Events is checked and save the changes.

To enable GitlabCI integration open your project settings in Gitlab, and then go to CI Web Hooks page.

As URL use your Dick the Deployer instance address with /api/hooks/gitlab-ci path.

Dick the Deployer doesn’t pool the repositories for changes. Instead the code repository should send notification using one of available hooks.

Dick the Deployer provides generic endpoint as well as several basic integrations with popular software.

• Generic endpoint
• Gitlab
• Gitlab CI

Dick the Deployer enables parametrization of build scripts using environment variables. Values that should remain secret can be provided using Dick Web by selecting secure option. Those variables will not be visible in build output.

Providing Environment Variables

There are three ways of providing environment variables:

• manually when starting pipeline with options,
• by variables section in .deployer.yml configuration file,
• and finally by project options in Dick Web.

Environment Variables Order

There are several ways of providing environment variables to the job. Variables can be injected by setting them to configuration on Dick the Deployer Web, can be provided via yml file and by setting them when triggering the job manually with options.

Each conflict in variable names is resolved with priorities in descending order as follows:

• most important are variables set manually (or via build hook),
• then variables defined in yml file,
• finally variables configured in project on Dick Web have lowest priority.