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.

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

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.

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

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

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

---
base_url: https://supervisor.example.com
api_key: 8db7fde4-6a11-462e-ba27-6897b7c9281b

supervisor <command> [options]

supervisor is-healthy

Checks the health of the Supervisor service.

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

• 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

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

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.

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