Shepherd

Shepherd implements an orchestrator tool useful for provision development platforms using Docker.

Note: Should a bug be found and not expected to be related with known issues, one should feel encouraged to file a new issue.

Key Concepts

Shepherd utilizes two types of images:

1. Docker Images
2. Environment Images

Docker Images

Classic stateless images containing executables.

Environment Images

Environment images capture a snapshot of a specific reference platform at a given point in time. These images are more comprehensive, including:

• Database State: The complete state of the database is embedded within the environment image, allowing it to be immediately consumed by the corresponding database Docker image with no additional processing required.

• Service Deployments: The snapshot can also include the deployment state of services which are ready for immediate use upon consumption.

All of this state information is packaged into a tar.gz archive, which can be optionally stored in a shared repository for easy access and distribution among developers.

Once an environment image is pulled and imported into shepherd, the corresponding environment state will evolve privately.

Requirements

OS & System Services

• Linux platforms

  • Ubuntu 22.04 LTS
  • Ubuntu 24.04 LTS

• Windows platforms

  • Windows 10/11
    • WSL
    • Ubuntu 22.04 LTS
    • Ubuntu 24.04 LTS
    • Docker

Installation

Note: It is highly recommended to use the tool having NOPASSWD option set for sudo.

To set the NOPASSWD option, execute:

sudo visudo

Add the following line replacing $USER with the actual username.

$USER ALL=(ALL) NOPASSWD:ALL

Note: If you do not have the NOPASSWD option set for sudo, you must prepend commands with sudo to run them with the necessary permissions.

Install the latest tool's version with the following command.

sh -c "$(curl -sfL ftp://to-change/shp/shpdctli.sh)"

Use VER env variable to install the desired tool's version.

VER=0.0.0 sh -c "$(curl -sfL ftp://to-change/shp/shpdctli.sh)"

Quick Start

Once installed, query the environment registry for available images:

$ shpdctl reg list

Environment        Size
-----------        ----
Env-Tag-1          7.22    (G)
Env-Tag-2          671.25  (M)
Env-Tag-3          53.78   (M)
...

Pull an environment:

shpdctl --checkout env pull Env-Tag-2

Start it:

shpdctl env up

Stop it:

shpdctl env halt

Consuming Environment Images

An environment image is typically created once, then pushed to the registry, where it can be pulled and consumed countless times by any developer. This ensures uniformity across different instances and reduces setup time.

Refer to documentation for Consuming Environment Images.

Authoring Environment Images

For creating, maintaining and pushing environment images to the registry refer to Authoring Environment Images.

Full Commands and Options Documentation

Refer to the specific documentation for the currently supported commands and options of shpdctl.

Database Service's Documentation

Refer to the specific documentation for currently supported database services:

1. Oracle
2. Postgres

Developer Instructions

See our development instructions.