Plugins

A plugin is a bundle of uploads, templates and hooks, filled in with the inputs your project gives it. Dockflow ships two, nginx and systemd, and a project can write its own.

A plugin behaves exactly like the uploads and hooks you write yourself. What it uploads is replaced atomically and put back by a rollback. Its hooks run, fail and roll back like yours.

plugins:
  - use: nginx                      # built-in
    with:
      domain: [shop.example.com, www.shop.example.com]
  - use: ./deploy/plugins/rclone    # the project's own
    id: archives
    with: { remote: "s3:archives" }

• dockflow plugins list shows the built-in plugins and the project's, with their inputs.
• dockflow config show lists the uploads and hooks they add.
• The plan names the plugin of each upload.

The nginx pluginCopy Anchor Link

The nginx plugin writes the nginx vhost that sends your domains to the switch, from your repository. Use it with the external edge, which puts the switch behind the host's nginx:

plugins:
  - use: nginx
    with:
      domain: [shop.example.com, www.shop.example.com]
      tls: true                     # certbot's certificate of the first domain

Each value goes into nginx's configuration as it is, so each is checked first: domains are host names or *. wildcards, upstream is host:port, port a number, max_body_size a size such as 25m, dir and certificate_dir absolute paths, name a file name. Anything else, such as a ; or a space, is refused with config.invalid.

The hook runs as the environment's SSH user, without a terminal. So sudo must not ask for a password for nginx -t and one of the two reloads.

server init --nginx installs nginx and this rule. On a server prepared otherwise, add the rule with sudo visudo -f /etc/sudoers.d/dockflow-nginx, with your SSH user and the paths that command -v nginx systemctl prints:

dockflow ALL=(root) NOPASSWD: /usr/sbin/nginx -t, /usr/bin/systemctl reload nginx

dockflow ALL=(root) NOPASSWD: /usr/sbin/nginx -t, /usr/sbin/nginx -s reload works too.

To get the certificate first, without letting certbot edit the vhost: sudo certbot certonly --nginx -d shop.example.com -d www.shop.example.com.

The systemd pluginCopy Anchor Link

The systemd plugin installs a unit from your repository, rendered as a Jinja template, and enables it:

plugins:
  - use: systemd
    with:
      unit: deploy/rclone-archives.service

• The unit goes to /etc/systemd/system/rclone-archives.service.
• When the unit changed, the plugin runs sudo systemctl daemon-reload, then enable and restart of the unit.
• A failure is a warning: the release stays.
• Inputs: unit (required, a file of the project) and name (default: the file's name). The unit's name, given or taken from the file, must match [A-Za-z0-9@._-]+: it goes into a command run with sudo.
• The SSH user needs sudo without a password for systemctl.

Writing a pluginCopy Anchor Link

A plugin is a directory of your project with a plugin.yml.

• Every other file of the directory (except a .git directory) belongs to the plugin. Paths in the plugin are relative to the directory, and must stay inside it.
• use: names the plugin by its path, which contains a /: ./deploy/plugins/rclone.
• As in dockflow.yml, an unknown key in plugin.yml is an error.

description: An rclone mount of a remote, as a systemd unit
inputs:
  - name: remote
    required: true
    description: the rclone remote, like s3:archives
  - name: mount
    default: /mnt/archives
  - name: read_only
    type: boolean
templates:
  - rclone.service                   # rendered in place
uploads:
  - src: rclone.service
    dest: "/etc/systemd/system/rclone-{{ id }}.service"
    mode: "644"
hooks:
  after_deploy:
    - name: restart the mount
      host: sudo systemctl daemon-reload && sudo systemctl restart rclone-{{ id }}
      if_changed: "/etc/systemd/system/rclone-{{ id }}.service"

[Service]
ExecStart=/usr/bin/rclone mount {{ remote }} {{ mount }}{% if read_only %} --read-only{% endif %}

Input types:

What the plugin sees:

• The string values of templates, uploads and hooks in plugin.yml are Jinja templates too. They are rendered with the inputs, id, the built-in variables and the environment's vars, never the secrets. Mapping keys are not rendered. A value that renders to true or false is a boolean again (fatal: "{{ strict }}").
• Template files also see the secrets, as the project's own templates do.
• An undefined variable is an error, so {% if x %} needs x declared as an input.

How plugins combine with the project:

• The plugins' uploads and hooks come before the project's own, in the order of plugins:.
• Each hook is named <id>: <name>.
• Two uses of one plugin need different ids.
• A plugin removed from plugins: leaves its uploaded files on the server, as an upload removed from uploads: does.