This Ansible role helps install Dokku on Debian/Ubuntu variants. Apart from installing Dokku, it also provides various modules that can be used to interface with dokku from your own Ansible playbooks.
Minimum Ansible Version: 2.2
Supported Platforms
True
boolean
0.0.2
string
dokku.me
string
/root/.ssh/id_rsa.pub
string
dpkg-reconfigure
)True
boolean
present
string
{}
list
- name: postgres
url: https://github.com/dokku/dokku-postgres.git
- name: redis
url: https://github.com/dokku/dokku-redis.git
false
string
null
list
dokku
user. Users should be specified in the following format:- name: Jane Doe
username: jane
ssh_key: JANES_PUBLIC_SSH_KEY
- name: Camilla
username: camilla
ssh_key: CAMILLAS_PUBLIC_SSH_KEY
''
string
dokku_packages_state
instead.true
string
false
string
''
string
dokku_packages_state
instead.''
string
dokku_packages_state
instead.''
string
dokku_packages_state
instead.Manage access control list for a given dokku application
dokku-acl
pluginParameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
state | Choices:
|
Whether the ACLs should be present or absent |
users required |
The list of users who can manage the app |
- name: let leopold manage hello-world
dokku_acl_app:
app: hello-world
users:
- leopold
- name: remove leopold from hello-world
dokku_acl_app:
app: hello-world
users:
- leopold
state: absent
Manage access control list for a given dokku service
dokku-acl
pluginParameter | Choices/Defaults | Comments |
---|---|---|
service required |
The name of the service | |
state | Choices:
|
Whether the ACLs should be present or absent |
type required |
The type of the service | |
users required |
The list of users who can manage the service |
- name: let leopold manage mypostgres postgres service
dokku_acl_service:
service: mypostgres
type: postgres
users:
- leopold
- name: remove leopold from mypostgres postgres service
dokku_acl_service:
service: hello-world
type: postgres
users:
- leopold
state: absent
Create or destroy dokku apps
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
state | Choices:
|
The state of the app |
- name: Create a dokku app
dokku_app:
app: hello-world
- name: Delete that repo
dokku_app:
app: hello-world
state: absent
Manage the builder configuration for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app. This is required only if global is set to False. | |
global | Default: False | If the property being set is global |
property required |
The property to be changed (e.g., build-dir , selected ) |
|
value | The value of the builder property (leave empty to unset) |
- name: Overriding the auto-selected builder
dokku_builder:
app: node-js-app
property: selected
value: dockerfile
- name: Setting the builder to the default value
dokku_builder:
app: node-js-app
property: selected
- name: Changing the build build directory
dokku_builder:
app: monorepo
property: build-dir
value: backend
- name: Overriding the auto-selected builder globally
dokku_builder:
global: true
property: selected
value: herokuish
Manages ssl configuration for an app.
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
cert required |
Path to the ssl certificate | |
key required |
Path to the ssl certificate key | |
state | Choices:
|
The state of the ssl configuration |
- name: Adds an ssl certificate and key to an app
dokku_certs:
app: hello-world
key: /etc/nginx/ssl/hello-world.key
cert: /etc/nginx/ssl/hello-world.crt
- name: Removes an ssl certificate and key from an app
dokku_certs:
app: hello-world
state: absent
Manage the Zero Downtime checks for a dokku app
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
state | Choices:
|
The state of the checks functionality |
- name: Disable the zero downtime deployment
dokku_checks:
app: hello-world
state: absent
- name: Re-enable the zero downtime deployment (enabled by default)
dokku_checks:
app: hello-world
state: present
Clone a git repository and deploy app.
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
build | Default: True | Whether to build the app after cloning. |
repository required |
Git repository url | |
version | Git tree (tag or branch name). If not provided, default branch is used. |
- name: clone a git repository and build app
dokku_clone:
app: example-app
repository: https://github.com/heroku/node-js-getting-started
version: b10a4d7a20a6bbe49655769c526a2b424e0e5d0b
- name: clone specific tag from git repository and build app
dokku_clone:
app: example-app
repository: https://github.com/heroku/node-js-getting-started
version: b10a4d7a20a6bbe49655769c526a2b424e0e5d0b
- name: sync git repository without building app
dokku_clone:
app: example-app
repository: https://github.com/heroku/node-js-getting-started
build: false
Manage environment variables for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
config required |
Default: {} | A map of environment variables where key => value |
restart | Default: True | Whether to restart the application or not. If the task is idempotent then setting restart to true will not perform a restart. |
- name: set KEY=VALUE
dokku_config:
app: hello-world
config:
KEY: VALUE_1
KEY_2: VALUE_2
- name: set KEY=VALUE without restart
dokku_config:
app: hello-world
restart: false
config:
KEY: VALUE_1
KEY_2: VALUE_2
Manage docker-options for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
option required |
A single docker option | |
phase | Choices:
|
The phase in which to set the options |
state | Choices:
|
The state of the docker options |
- name: docker-options:add hello-world deploy
dokku_docker_options:
app: hello-world
phase: deploy
option: "-v /var/run/docker.sock:/var/run/docker.sock"
- name: docker-options:remove hello-world deploy
dokku_docker_options:
app: hello-world
phase: deploy
option: "-v /var/run/docker.sock:/var/run/docker.sock"
state: absent
Manages domains for a given application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app. This is required only if global is set to False. | |
domains required |
A list of domains | |
global | Default: False | Whether to change the global domains or app-specific domains. |
state | Choices:
|
The state of the application's domains |
# Adds domain, inclusive
- name: domains:add hello-world dokku.me
dokku_domains:
app: hello-world
domains:
- dokku.me
# Removes listed domains, but leaves others unchanged
- name: domains:remove hello-world dokku.me
dokku_domains:
app: hello-world
domains:
- dokku.me
state: absent
# Clears all domains
- name: domains:clear hello-world
dokku_domains:
app: hello-world
state: clear
# Enables the VHOST domain
- name: domains:enable hello-world
dokku_domains:
app: hello-world
state: enable
# Disables the VHOST domain
- name: domains:disable hello-world
dokku_domains:
app: hello-world
state: disable
# Sets the domain for the app, clearing all others
- name: domains:set hello-world dokku.me
dokku_domains:
app: hello-world
domains:
- dokku.me
state: set
Manages syncing git code from a remote repository for an app
dokku-git-sync
plugin (commercial)Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
remote | The git remote url to use | |
state | Choices:
|
The state of the git-sync integration |
- name: git-sync:enable hello-world
dokku_git_sync:
app: hello-world
remote: git@github.com:hello-world/hello-world.git
- name: git-sync:disable hello-world
dokku_git_sync:
app: hello-world
state: absent
Manages global ssl configuration.
dokku-global-cert
pluginParameter | Choices/Defaults | Comments |
---|---|---|
cert required |
Path to the ssl certificate | |
key required |
Path to the ssl certificate key | |
state | Choices:
|
The state of the ssl configuration |
- name: Adds an ssl certificate and key
dokku_global_cert:
key: /etc/nginx/ssl/global-hello-world.key
cert: /etc/nginx/ssl/global-hello-world.crt
- name: Removes an ssl certificate and key
dokku_global_cert:
state: absent
Manage HTTP Basic Authentication for a dokku app
dokku-http-auth
pluginParameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
password | The HTTP Auth Password (required for 'present' state) | |
state | Choices:
|
The state of the http-auth plugin |
username | The HTTP Auth Username (required for 'present' state) |
- name: Enable the http-auth plugin
dokku_http_auth:
app: hello-world
state: present
username: samsepi0l
password: hunter2
- name: Disable the http-auth plugin
dokku_http_auth:
app: hello-world
state: absent
Pull Docker image and deploy app
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
build_dir | Specify custom build directory for a custom build context | |
image required |
Docker image | |
user_email | Git user.email for customizing the author's email | |
user_name | Git user.name for customizing the author's name |
- name: Pull and deploy meilisearch
dokku_image:
app: meilisearch
image: getmeili/meilisearch:v0.24.0rc1
- name: Pull and deploy image with custom author
dokku_image:
app: hello-world
user_name: Elliot Alderson
user_email: elliotalderson@protonmail.ch
image: hello-world:latest
- name: Pull and deploy image with custom build dir
dokku_image:
app: hello-world
build_dir: /path/to/build
image: hello-world:latest
Enable or disable the letsencrypt plugin for a dokku app
dokku-letsencrypt
pluginParameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
state | Choices:
|
The state of the letsencrypt plugin |
- name: Enable the letsencrypt plugin
dokku_letsencrypt:
app: hello-world
- name: Disable the letsencrypt plugin
dokku_letsencrypt:
app: hello-world
state: absent
Create or destroy container networks for dokku apps
Parameter | Choices/Defaults | Comments |
---|---|---|
name required |
The name of the network | |
state | Choices:
|
The state of the network |
- name: Create a network
dokku_network:
name: example-network
- name: Delete that network
dokku_network:
name: example-network
state: absent
Set or clear a network property for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app. This is required only if global is set to False. | |
global | Default: False | Whether to change the global network property |
property required |
The network property to be be modified. This can be any property supported by dokku (e.g., initial-network , attach-post-create , attach-post-deploy , bind-all-interfaces , static-web-listener , tld ). |
|
value | The value of the network property (leave empty to unset) |
- name: Associates a network after a container is created but before it is started
dokku_network_property:
app: hello-world
property: attach-post-create
value: example-network
- name: Associates the network at container creation
dokku_network_property:
app: hello-world
property: initial-network
value: example-network
- name: Setting a global network property
dokku_network_property:
global: true
property: attach-post-create
value: example-network
- name: Clearing a network property
dokku_network_property:
app: hello-world
property: attach-post-create
Manage ports for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
mappings required |
A list of port mappings | |
state | Choices:
|
The state of the port mappings |
- name: ports:set hello-world http:80:80
dokku_ports:
app: hello-world
mappings:
- http:80:8080
- name: ports:remove hello-world http:80:80
dokku_ports:
app: hello-world
mappings:
- http:80:8080
state: absent
- name: ports:clear hello-world
dokku_ports:
app: hello-world
state: clear
Enable or disable the proxy for a dokku app
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
state | Choices:
|
The state of the proxy |
- name: Enable the default proxy
dokku_proxy:
app: hello-world
- name: Disable the default proxy
dokku_proxy:
app: hello-world
state: absent
Manage process scaling for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
scale required |
Default: {} | A map of scale values where proctype => qty |
skip_deploy | Default: False | Whether to skip the corresponding deploy or not. If the task is idempotent then leaving skip_deploy as false will not trigger a deploy. |
- name: scale web and worker processes
dokku_ps_scale:
app: hello-world
scale:
web: 4
worker: 4
- name: scale web and worker processes without deploy
dokku_ps_scale:
app: hello-world
skip_deploy: true
scale:
web: 4
worker: 4
Manage the registry configuration for a given dokku application
dokku-registry
pluginParameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
image | Alternative to app name for image repository name | |
password | The registry password (required for 'present' state) | |
server | The registry server hostname (required for 'present' state) | |
state | Choices:
|
The state of the registry integration |
username | The registry username (required for 'present' state) |
- name: registry:enable hello-world
dokku_registry:
app: hello-world
password: password
server: localhost:8080
username: user
- name: registry:enable hello-world with args
dokku_registry:
app: hello-world
image: other-image
password: password
server: localhost:8080
username: user
- name: registry:disable hello-world
dokku_registry:
app: hello-world
state: absent
Manage resource limits for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
clear_before | Choices:
|
Clear all resource limits before applying |
process_type | The process type selector | |
resources | The Resource type and quantity (required when state=present) | |
state | Choices:
|
The state of the resource limits |
- name: Limit CPU and memory of a dokku app
dokku_resource_limit:
app: hello-world
resources:
cpu: 100
memory: 100
- name: name: Limit resources per process type of a dokku app
dokku_resource_limit:
app: hello-world
process_type: web
resources:
cpu: 100
memory: 100
- name: Clear limits before applying new limits
dokku_resource_limit:
app: hello-world
state: present
clear_before: True
resources:
cpu: 100
memory: 100
- name: Remove all resource limits
dokku_resource_limit:
app: hello-world
state: absent
Manage resource reservations for a given dokku application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
clear_before | Choices:
|
Clear all reserves before apply |
process_type | The process type selector | |
resources | The Resource type and quantity (required when state=present) | |
state | Choices:
|
The state of the resource reservations |
- name: Reserve CPU and memory for a dokku app
dokku_resource_reserve:
app: hello-world
resources:
cpu: 100
memory: 100
- name: Create a reservation per process type of a dokku app
dokku_resource_reserve:
app: hello-world
process_type: web
resources:
cpu: 100
memory: 100
- name: Clear all reservations before applying
dokku_resource_reserve:
app: hello-world
state: present
clear_before: True
resources:
cpu: 100
memory: 100
- name: Remove all resource reservations
dokku_resource_reserve:
app: hello-world
state: absent
Creates a given service
Parameter | Choices/Defaults | Comments |
---|---|---|
name required |
The name of the service | |
service required |
The type of service to create |
- name: redis:create default
dokku_service_create:
name: default
service: redis
- name: postgres:create default
dokku_service_create:
name: default
service: postgres
- name: postgres:create default with custom image
environment:
POSTGRES_IMAGE: postgis/postgis
POSTGRES_IMAGE_VERSION: 13-master
dokku_service_create:
name: default
service: postgres
Links and unlinks a given service to an application
Parameter | Choices/Defaults | Comments |
---|---|---|
app required |
The name of the app | |
name required |
The name of the service | |
service required |
The type of service to link | |
state | Choices:
|
The state of the service link |
- name: redis:link default hello-world
dokku_service_link:
app: hello-world
name: default
service: redis
- name: postgres:link default hello-world
dokku_service_link:
app: hello-world
name: default
service: postgres
- name: redis:unlink default hello-world
dokku_service_link:
app: hello-world
name: default
service: redis
state: absent
Manage storage for dokku applications
Parameter | Choices/Defaults | Comments |
---|---|---|
app | The name of the app | |
create_host_dir | Default: False | Whether to create the host directory or not |
group | Default: 32767 | A group or gid that should own the created folder |
mounts | Default: [] | A list of mounts to create, colon (:) delimited, in the format: host_dir:container_dir |
state | Choices:
|
The state of the service link |
user | Default: 32767 | A user or uid that should own the created folder |
- name: mount a path
dokku_storage:
app: hello-world
mounts:
- /var/lib/dokku/data/storage/hello-world:/data
- name: mount a path and create the host_dir directory
dokku_storage:
app: hello-world
mounts:
- /var/lib/dokku/data/storage/hello-world:/data
create_host_dir: true
- name: unmount a path
dokku_storage:
app: hello-world
mounts:
- /var/lib/dokku/data/storage/hello-world:/data
state: absent
- name: unmount a path and destroy the host_dir directory (and contents)
dokku_storage:
app: hello-world
mounts:
- /var/lib/dokku/data/storage/hello-world:/data
destroy_host_dir: true
state: absent
---
- hosts: all
roles:
- dokku_bot.ansible_dokku
---
- hosts: all
roles:
- dokku_bot.ansible_dokku
vars:
dokku_plugins:
- name: clone
url: https://github.com/crisward/dokku-clone.git
- name: postgres
url: https://github.com/dokku/dokku-postgres.git
---
- hosts: all
roles:
- dokku_bot.ansible_dokku
tasks:
- name: dokku apps:create inflector
dokku_app:
app: inflector
- name: dokku clone inflector
dokku_clone:
app: inflector
repository: https://github.com/cakephp/inflector.cakephp.org
---
- hosts: all
roles:
- dokku_bot.ansible_dokku
- geerlingguy.swap
vars:
# If you are running dokku on a small VPS, you'll most likely
# need some swap to ensure you don't run out of RAM during deploys
swap_file_size_mb: '2048'
dokku_version: 0.19.13
dokku_users:
- name: yourname
username: yourname
ssh_key: "{{lookup('file', '~/.ssh/id_rsa.pub')}}"
dokku_plugins:
- name: clone
url: https://github.com/crisward/dokku-clone.git
- name: letsencrypt
url: https://github.com/dokku/dokku-letsencrypt.git
tasks:
- name: create app
dokku_app:
# change this name in your template!
app: &appname appname
- name: environment configuration
dokku_config:
app: *appname
config:
# specify port so `domains` can setup the port mapping properly
PORT: "5000"
- name: git clone
# note you'll need to add a deployment key to the GH repo if it's private!
dokku_clone:
app: *appname
repository: git@github.com:heroku/python-getting-started.git
- name: add domain
dokku_domains:
app: *appname
domains:
- example.com
- name: add letsencrypt
dokku_letsencrypt:
app: *appname
See CONTRIBUTING.md.
MIT License
See LICENSE.md for further details.