Supervisor Client

The Supervisor Client is a Ruby library and CLI tool that provides easy access to the Supervisor - The Docker GitOps service, enabling you to manage stacks with GitOps strategies. This library wraps the Supervisor API and allows to create, update, control, and query stacks directly from Ruby applications or the command line.

Installation

To install the Supervisor Client, add this line to your application's Gemfile:

gem 'supervisor'

Then, execute:

bundle install

Or install it directly:

gem install supervisor

Or install from source:

git clone https://github.com/tschaefer/supervisor-client
cd supervisor-client
rake install

Configuration

Before using the library, configure the base_url and api_key:

require 'supervisor'

Supervisor.configure do |config|
  config.base_url = 'https://supervisor.example.com'
  config.api_key = '8db7fde4-6a11-462e-ba27-6897b7c9281b'
end

After configuration, you can call any of the provided API methods directly.

Usage

Once configured, interact with the Supervisor API using the following methods:

Supervisor.create_stack(params)                 # Creates a new stack
Supervisor.list_stacks                          # Lists all stacks
Supervisor.show_stack(stack_uuid)               # Shows details of a specific stack
Supervisor.stack_stats(stack_uuid)              # Retrieves statistics for a stack
Supervisor.update_stack(stack_uuid, params)     # Updates an existing stack
Supervisor.delete_stack(stack_uuid)             # Deletes a specified stack
Supervisor.control_stack(stack_uuid, command)   # Controls (start, stop) a stack
Supervisore.stack_last_log_entry(stack_uuid)    # Retrieves the last log entry for a stack
Supervisor.stack_logs(stack_uuid) { block }     # Retrieves logs for a stack (Server-sent events)
Supervisor.health_check                         # Checks the health of the service

CLI Usage

The supervisor CLI provides easy command-line access to Supervisor API actions.

Configuration

Before using the CLI, configure the Supervisor base URI and API token by creating a configuration file at ~/.supervisor:

---
api:
    uri: https://supervisor.example.com
    token: 8db7fde4-6a11-462e-ba27-6897b7c9281b

Command Reference

supervisor <command> [options]

Health Check

supervisor is-healthy

Checks the health of the Supervisor service.

Deployment Management

The command deploy installs and sets up a containerized Supervisor service on a vanilla Linux machine by provisioning the docker service and deploying the application proxy Traefik.

Default Traefik docker command

docker run \
    --detach --restart always --name traefik \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume /var/lib/traefik:/etc/traefik \
    --network supervisor \
    --publish 80:80 --publish 443:443 \
    traefik:v3.2.1 \
    --providers.docker.exposedbydefault="false" \
    --entrypoints.web.address=":80" \
    --entrypoints.websecure.address=":443" \
    --certificatesresolvers.letsencrypt.acme.email="[email protected]" \
    --certificatesresolvers.letsencrypt.acme.storage="/etc/traefik/certs.d/acme.json" \
    --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint="web"

Default Supervisor docker command

docker run \
    --detach --restart always --name supervisor \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume /var/lib/supervisor:/rails/storage \
    --network supervisor \
    --label traefik.enable="true" \
    --label traefik.http.routers.supervisor.tls="true" \
    --label traefik.http.routers.supervisor.tls.certresolver="letsencrypt" \
    --label traefik.http.routers.supervisor.rule="Host(\"supervisor.example.com\")" \
    --label traefik.http.routers.supervisor.entrypoints="websecure" \
    --env SECRET_KEY_BASE="601f72235d8ea11db69e678f9...1a" \
    --env SUPERVISOR_API_KEY="8db7fde4-6a11-462e-ba27-6897b7c9281b" \
    ghcr.io/tschaefer/supervisor:main

Default docker network command

docker network create \
    --attachable true \
    --ipv6=true \
    --driver=bridge \
    --opt com.docker.network.container_iface_prefix=supervisor
    supervisor

Prerequisites are super-user privileges, a valid DNS record for the Supervisor service and the above mentioned configuration file.

While setup the necessary certificate is requested from Let's Encrypt via HTTP-challenge.

supervisor deploy --host [email protected]

The provisioning of docker can be skipped wit the option --skip-docker as well as the installation of Traefik with the option --skip-traefik. For a more informative output use --verbose - beware, sensible information will be exposed.

The deployment is customizable by configuration in the root under deploy.

deploy:

    # Network settings
    network:

        # The name of the network to create, defaults to supervisor
        name: supervisor
        # Additional options to pass to the network create command
        options:
            ipv6: false
            opt: com.docker.network.driver.mtu=1500

    # Traefik settings
    traefik:

        # The Traefik image to use, defaults to traefik:v3.2.1
        image: traefik:v3.2.0

        # Additional arguments to pass to the Traefik container
        args:
            configfile: /etc/traefik/traefik.yml

        # Additional environment variables to pass to the Traefik container
        env:
            CF_API_EMAIL: [email protected]
            CF_DNS_API_TOKEN: YSsfAH-d1q57j2D7T41ptAfM

    # Supervisor settings
    supervisor:

        # The Supervisor image to use, defaults to ghcr.io/tschaefer/supervisor:main
        image: ghcr.io/tschaefer/supervisor:latest

        # Additional labels to apply to the Supervisor container
        labels:
            traefik.http.routers.supervisor.tls.certresolver: cloudflare

        # Additional environment variables to pass to the Supervisor container
        env: {}

Custom hooks scripts can be run before and after certain deployment steps.

• post-docker-setup
• pre-traefik-deploy
• post-traefik-deploy
• pre-supervisor-deploy
• post-supervisor-deploy

Example:

#!/usr/bin/env sh

# pre-traefik-deploy hook script

cat <<EOF> /var/lib/traefik/traefik.yml
---
certificatesresolvers:
  cloudflare:
    acme:
      email: [email protected]
      storage: /etc/traefik/certs.d/cloudflare.json
      dnschallenge:
        provider: cloudflare
EOF

The hook filename must be the hook name without any extension. The path to the hooks directory can be configured in the root under hooks.

hooks: /path/to/hooks

The Supervisor service can be redeployed with the command redeploy.

supervisor redeploy --host machine.example.com

Optionally, Traefik can be redeployed with the option --with-traefik.

Stack Management

The stacks commands provide a variety of operations for managing stacks.

Available Stack Commands

Subcommand	Description
create	Creates a new stack using a YAML manifest file.
update	Updates an existing stack with a new manifest file.
control	Controls (start, stop) a stack.
delete	Deletes a specified stack.
show	Shows details of a specified stack.
stats	Retrieves statistics for a stack.
list	Lists all stacks in Supervisor.
control	Controls (start, stop, rest) a stack.
log	Retrieves log for a stack.

Command Options

• create and update: Both require the --manifest-file FILE option to specify a YAML manifest file describing the stack. The optional --decrypt option uses sops to decrypt inline attributes in the YAML file.

  • Example:

    supervisor create --manifest-file stack.yaml --decrypt

• update: In addition to --manifest-file FILE, update requires the parameter STACK-UUID for the stack to update.

  • Example:

    supervisor update --manifest-file stack.yaml STACK-UUID

• show, stats, delete: Each of these subcommands requires the parameter STACK-UUID for the stack to operate on.

  • Example:

    supervisor show STACK-UUID
    supervisor stats STACK-UUID
    supervisor delete STACK-UUID

• show: By default, sensitive data in the output is filtered. Use the --unfiltered option to disable filtering.

  • Example:

    supervisor show STACK-UUID --unfiltered

• show, stats, list: These subcommands output information in a table format by default. Use the --json option to output data in JSON format.

  • Example:

    supervisor list --json

Bash Completion

The repository includes a bash completion script for the supervisor CLI. For usage copy the etc/bash/completion file to your bash completion directory.

cp etc/bash/completion /etc/bash_completion.d/supervisor

Manifest File

The manifest file, specified by --manifest-file FILE, is a YAML file that defines a stack’s configuration. Here’s an example:

name: whoami
git_repository: https://github.com/tschaefer/infrastructure
git_username: tschaefer
git_token: github_pat_...FFF
git_reference: refs/heads/main
compose_file: lib/stack/whoami/docker-compose.yml
compose_includes:
  - lib/stack/whoami/includes/traefik.yml
  - lib/stack/whoami/includes/network.yml
compose_variables:
  NETWORK_IPV4_WHOAMI: 172.18.100.111
  NETWORK_ID: core
strategy: polling
polling_interval: 300
signature_header: nil
signature_secret: nil

• name: Unique name for the stack.
• git_repository: URL to the git repository with the stack's docker-compose.yml file.
• git_username and git_token: (Optional) Authentication details for the repository.
• compose_file: Path to the primary docker-compose.yml file in the repository.
• compose_includes: List of additional Compose files to be included.
• compose_variables: Variables to be passed to the Compose file.
• strategy: GitOps strategy (polling or webhook).
• polling_interval: (For polling strategy) Interval, in seconds, for polling the repository.
• signature_header and signature_secret: (For webhook strategy) Signature details.

License

This project is licensed under the MIT License. See the LICENSE file for details.