harbor-compose

A tool for defining and running multi-container Docker applications on Harbor.

With Harbor Compose, you start with a standard Docker Compose file to configure your application’s services. You then add a Harbor Compose file to configure Harbor-specific settings. Then, using a single command, you create and start all the services from your configuration.

Using Harbor Compose is basically a four-step process.

1. Define your app’s environment with a Dockerfile so it can be reproduced anywhere.

2. Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment. You can use the standard Docker Compose commands (like docker-compose build, docker-compose push, docker-compose up, etc.) to build/run/test your Docker app locally.

3. When you're ready to launch your Docker app on Harbor, you define the Harbor-specific parameters in a harbor-compose.yml file.

4. Run harbor-compose up and Harbor Compose will start and run your entire app on a managed barge.

Just like docker-compose, harbor-compose has similar commands for managing the life cycle of your app on Harbor:

• Start and stop services
• Upload environment variables and scale replicas
• View the status of running services
• Stream the log output of running services
• Trigger an image deployment from a public build system (like Circle CI, Travis CI, etc.)

A simple docker-compose.yml might look like this:

version: "2"
services:
  web-app:
    image: quay.io/turner/my-web-app:1.0.0
    ports:
      - "80:5000"
    environment:
      HEALTHCHECK: /hc
      PORT: 5000

A harbor-compose.yml might look like this:

version: "1"
shipments:
  my-web-app:
    env: dev
    barge: digital-sandbox
    containers:
      - web-app    
    replicas: 2
    group: mss
    property: turner
    project: turner
    product: turner

Then to start your application...

$ harbor-compose up

Access your app logs...

$ harbor-compose logs

Get the status of your shipments...

$ harbor-compose ps

To stop your application, remove all running containers and delete your load balancer...

$ harbor-compose down

Compose file reference

See the full harbor-compose.yml reference along with which docker-compose.yml properties are supported by Harbor Compose.

Getting Started

There are currently two installation options for Harbor Compose.

1. Download the latest binary from Github releases.

curl -s get-cli.harbor.turnerlabs.io | sh

2. Run as a docker container

docker run -it --rm -v `pwd`:/work quay.io/turner/harbor-compose up

• or if you want to reuse your session:

docker run -it —rm -v `pwd`:/work -v ${HOME}/.harbor:/root/.harbor quay.io/turner/harbor-compose up

To get started with an existing shipment, you can run the following to generate docker-compose.yml and harbor-compose.yml files, by specifying the shipment name and environment as args. Note that you will be prompted to login if you don't already have a token or if your token has expired. For example:

$ harbor-compose generate my-shipment dev

To create new shipments, you can use the init command to generate new docker-compose.yml and harbor-compose.yml files. init will ask you questions to build your compose files. Note that you use the --yes flag to accept defaults and generate one quickly.

$ harbor-compose init

This will output the files in the current directory. You can then run a bunch of useful commands, for example...

Run your shipment locally in Docker (practically identically to how it runs in Harbor)...

$ docker-compose up

Push your images to a registry.

$ docker-compose push

Scale your shipment by changing the replicas in harbor-compose.yml, or change your environment variables and re-deploy, or deploy a new image, etc....

$ harbor-compose up

Get the status of your shipment(s) using the ps command. With this command you can see the status of each container replica, when it started and the last known state. For example:

$ harbor-compose ps

SHIPMENT:      mss-poc-multi-container   
ENVIRONMENT:   dev                       
STATUS:        Running                   
CONTAINERS:    2                         
REPLICAS:      2

ID        IMAGE                                                        STATUS    STARTED      RESTARTS   LAST STATE              
ab97cef   quay.io/turner/mss-poc-multi-container:1.0.0    running   1 week ago   1          terminated 1 week ago   
873a390   quay.io/turner/mss-poc-multi-container2:1.0.0   running   1 week ago   1          terminated 1 week ago   
73fad42   quay.io/turner/mss-poc-multi-container:1.0.0    running   5 days ago   2          terminated 5 days ago   
db93650   quay.io/turner/mss-poc-multi-container2:1.0.0   running   5 days ago   2          terminated 5 days ago   

You can also manage multiple shipments using Harbor Compose by listing them in your harbor-compose.yml file. This is particularly useful if you have a web/worker, or microservices type application where each shipment can be scaled independently.

Authentication

Some commands (up, down, generate) require authentication and will automatically prompt you for your credentials. A temporary (6 hours) authentication token is stored on your machine so that you don't have to login when running each command. If you want to logout and remove the authentication token, you can run the logout command. You can also explicitly login by running the login command.

CI/CD

See the CI/CD doc.