npm package: @hugojosefson/docker-git-inventory
Description: Extract Docker Stack's running services' versions, pushing named refs to git repos
Author: Hugo Josefson
Latest version: 2.0.2

# docker-inventory-git

[![Build Status](https://travis-ci.org/hugojosefson/docker-git-inventory.svg?branch=master)](https://travis-ci.org/hugojosefson/docker-git-inventory)
[![npm page](https://img.shields.io/npm/v/@hugojosefson/docker-git-inventory.svg)](https://npmjs.com/package/@hugojosefson/docker-git-inventory)
[![License MIT](https://img.shields.io/npm/l/@hugojosefson/docker-git-inventory.svg)](https://tldrlegal.com/license/mit-license)
[![SemVer 2.0.0](https://img.shields.io/badge/SemVer-2.0.0-lightgrey.svg)](https://semver.org/spec/v2.0.0.html)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

## 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](https://github.com/nvm-sh/nvm#readme):

```bash
nvm install stable
```

## Usage

### Get an inventory

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

### Start an HTTP API server

```bash
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](http://jsonlines.org/).

```bash
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

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### inventoryHandlers

#### pushRefsHandlers

#### defaultRemoteRef

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

##### Parameters

- `prefix`
  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
  prefix for the remoteRef (optional, default `'refs/deployed/'`)

Returns **(function ({milieu, serviceName, url}):
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**
function for calculating a reasonable remoteRef

#### defaultServiceToPush

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

##### Parameters

- `defaultArgs` **{username:
  ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
  password:
  ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
  url:
  ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
  ref:
  ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
  remoteRef:
  ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))}**
  for example {username, password} (optional, default `{}`)

Returns **function ({serviceName:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
labels: {GIT_URL:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
GIT_COMMIT:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
milieu:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))}}?):
{ref:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
url:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)),
remoteRef:
([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
|
[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))}**

#### inventory

Takes an inventory of currently running Docker stacks.

Returns **Highland.Stream<{stack:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
taskId:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
image:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
serviceId:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
serviceNameLong:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
serviceName:
[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String),
labels:
[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{username,
  password, url, ref, remoteRef}> |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**

  - `options.username`
    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
    username for git authentication
  - `options.password`
    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
    password for authentication
  - `options.url`
    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
    git repo url
  - `options.ref`
    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
    the commit to push
  - `options.remoteRef`
    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
    name of the remote ref, for example refs/deployed/stage

Returns
**[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<void>**
resolves when done