docker-inventory-git

Introduction

This is a library and a service for extracting information from a Docker Swarm about currently running services, and pushing custom named refs to git repos. That means you can see the deployment status from your Docker Swarm, in your development git tools.

Prerequisite

Node.js, v13.7.0 or higher, ideally at least v14.0.0.

Recommended to install latest via nvm:

nvm install stable

Usage

Get an inventory

npx --package @hugojosefson/docker-git-inventory docker-git-inventory

Start an HTTP API server

PORT=3000 \
npx --package @hugojosefson/docker-git-inventory docker-git-inventory-server

Push refs to git

The docker-git-inventory-push-refs command takes an inventory on stdin as JSON lines.

curl -s localhost:3000/inventory | \
  USERNAME=mygitusername \
  PASSWORD=mygitpassword \
  npx --package @hugojosefson/docker-git-inventory \
    docker-git-inventory-push-refs

Programmatic access

You can also import the module, and use its exported functions programmatically.

API

inventoryHandlers

pushRefsHandlers

defaultRemoteRef

Reasonable calculation of remoteRef, based on milieu, serviceName and git url.

Parameters

• prefix string prefix for the remoteRef (optional, default 'refs/deployed/')

Returns (function ({milieu, serviceName, url}): string | undefined) function for calculating a reasonable remoteRef

defaultServiceToPush

Reasonable conversion from service (via inventory), to arguments to pushRef.

Parameters

• defaultArgs {username: (string | undefined), password: (string | undefined), url: (string | undefined), ref: (string | undefined), remoteRef: (string | undefined)} for example {username, password} (optional, default {})

Returns function ({serviceName: string, labels: {GIT_URL: (string | undefined), GIT_COMMIT: (string | undefined), milieu: (string | undefined)}}?): {ref: (string | undefined), url: (string | undefined), remoteRef: (string | undefined)}

inventory

Takes an inventory of currently running Docker stacks.

Returns Highland.Stream<{stack: string, taskId: string, image: string, serviceId: string, serviceNameLong: string, serviceName: string, labels: object}> A Highland stream of objects, each describing one service.

inventoryToPushes

Converts a Highland stream of inventory objects, into a stream of argument objects for pushRef.

Parameters

• serviceToPush (function ({stack, taskId, image, serviceId, serviceName, serviceNameLong, labels}): Highland.Stream<{username, password, url, ref, remoteRef}> | Promise<{username, password, url, ref, remoteRef}> | Array<{username, password, url, ref, remoteRef}> | {username, password, url, ref, remoteRef})

Returns function (Highland.Stream<{stack, taskId, image, serviceId, serviceName, serviceNameLong, labels}>): Highland.Stream<{username, password, url, ref, remoteRef}>

app

HTTP API for working with docker-inventory-git.

Parameters

• options object (optional, default {})

  • options.app (Express | Application | IRouter) Express.js Application instance or Router on which to apply paths. (optional, default express())

Returns (Express | Application | IRouter) app, mutated.

pushRef

Pushes a git commit to its repo, with a specific remoteRef.

Parameters

• options object

  • options.username string username for git authentication
  • options.password string password for authentication
  • options.url string git repo url
  • options.ref string the commit to push
  • options.remoteRef string name of the remote ref, for example refs/deployed/stage

Returns Promise<void> resolves when done