arhea / harbor-master

🛥️ Harbor Master is a Docker Remote API client written in Node.js

Harbor Master

Harbor Master is a Docker Remote API client written in Node. This client is meant to be a simple wrapper that makes it easy to communicate with your Docker Daemon over the unix socket or http based APIs.

This project is still in active development. This project will be versioned in accordance with the Docker Remote API. For example, if the current Docker Remote API version is 1.32, Harbor Master's version will be 1.32.x.

Table of Contents

• Examples
• Documentation
  • Client
  • API
    • Configs
    • Containers
    • Images
    • Networks
    • Volumes
    • Secrets
    • Swarm
    • Nodes
    • Services
    • Tasks
    • Plugins
    • Systems

Examples

Unix Socket Example

const docker = require('../index');

const client = docker.Client({
  socket: '/var/run/docker.sock'
});

client.info().then((info) => {
  console.log(info);
}).catch((err) => {
  console.error(err);
});

Remote Host Example

const docker = require('../index');

const client = docker.Client({
  host: 'swarm.example.com',
  port: '2375'
});

client.info().then((info) => {
  console.log(info);
}).catch((err) => {
  console.error(err);
});

SSL Configuration

const docker = require('../index');

const client = docker.Client({
  host: 'swarm.example.com',
  port: '2376',
  tls: {
    ca: fs.readFileSync('ca.pem'),
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem'),
    passphrase: 'supersecretpass'
  }
});

client.info().then((info) => {
  console.log(info);
}).catch((err) => {
  console.error(err);
});

API Documentation

docker.Client(options) - Harbor Master Client

• options
  • host - the IP address or Hostname of the Docker server
  • port - the port number the Docker server exposes
  • socket - the unix socket
  • tls
    • cert - contents of the server certificate
    • key - contents of the server certificate key
    • ca - contents of the CA certificate
    • password - the certificate password

Configs

client.configs().list(options) - List Configs

• Docker Documentation
• options
  • filters - map[string][]string to process on the configs list

client.configs().create(model, options) - Create Config

• Docker Documentation
• model - the JSON model that the Docker API consumes
• options

client.configs().inspect(id, options) - Inspect Config

• Docker Documentation
• id - the id or name of the config
• options

client.configs().remove(id, options) - Remove Config

• Docker Documentation
• name - the id of the config
• options

client.configs().update(id, model, options) - Update Config

• Docker Documentation
• id - the id or name of the config
• model - the JSON model that the Docker API consumes
• options
  • version - The version number of the config object being updated. This is required to avoid conflicting writes.

Containers

client.containers().list(options) - List Containers

• Docker Documentation
• options
  • all - default: false Show all containers. Only running containers are shown by default.
  • limit - Show limit last created containers, include non-running ones.
  • since - Show only containers created since Id, include non-running ones.
  • before - Show only containers created before Id, include non-running ones.
  • size - default: false Show the containers sizes
  • filters - map[string][]string to process on the containers list

client.containers().create(model, options) - Create Container

• Docker Documentation
• model - the JSON model that the Docker API consumes
• options
  • name - Assign the specified name to the container. Must match /?[a-zA-Z0-9_-]+.

client.containers().inspect(name, options) - Inspect Container

• Docker Documentation
• name - the name or id of the container
• options
  • size - default: false Show the containers sizes

client.containers().top(name) - List Processes Running Inside a Container

• Docker Documentation
• name - the name or id of the container
• options
  • ps_args - ps arguments to use (e.g., aux), defaults to -ef

client.containers().logs(name, options) - Container Logs

• Docker Documentation
• name - the name or id of the container
• options
  • details - Show extra details provided to logs. default: false
  • follow - return stream. default: false
  • stdout - show stdout log. default: false
  • stderr - show stderr log. default: false
  • since - Specifying a timestamp will only output log-entries since that timestamp. default: false
  • timestamps - print timestamps for every log line default: false
  • tail - Output specified number of lines at the end of logs: all or default: all

client.containers().changes(name, options) - Inspect Container Filesystem Changes

• Docker Documentation
• name - the name or id of the container
• options

client.containers().export(name, options) - Export a Container

• Docker Documentation
• name - the name or id of the container
• options

client.containers().stats(name, options) - Export a Container

• Docker Documentation
• name - the name or id of the container
• options
  • stream - stream statistics default: true

client.containers().resize(name, options) - Resize a container TTY

• Docker Documentation
• name - the name or id of the container
• options
  • h - height
  • w - width

client.containers().start(name, options) - Start a Container

• Docker Documentation
• name - the name or id of the container
• options
  • detachKeys - Override the key sequence for detaching a container. Format is a single character.

client.containers().stop(name, options) - Stop a Container

• Docker Documentation
• name - the name or id of the container
• options
  • t - number of seconds to wait before killing the container

client.containers().restart(name, options) - Restart a Container

• Docker Documentation
• name - the name or id of the container
• options
  • t - number of seconds to wait before killing the container

client.containers().kill(name, options) - Kill a Container

• Docker Documentation
• name - the name or id of the container
• options
  • signal - Signal to send to the container: integer or string like SIGINT. When not set, SIGKILL is assumed and the call waits for the container to exit.

client.containers().update(name, model, options) - Update a Container

• Docker Documentation
• name - the name or id of the container
• model - the JSON model that the Docker API consumes
• options

client.containers().rename(name, options) - Rename a Container

• Docker Documentation
• name - the name or id of the container
• options
  • name - new name for the container

client.containers().pause(name) - Pause a Container

• Docker Documentation
• name - the name or id of the container
• options

client.containers().unpause(name) - Unpause a Container

• Docker Documentation
• name - the name or id of the container
• options

client.containers().attach(name, options) - Attach a Container

• Docker Documentation
• name - the name or id of the container
• options
  • detachKeys - Override the key sequence for detaching a container. Format is a single character
  • logs - return logs default: false
  • stream - return stream default: false
  • stdin - return stdin default: false
  • stdout - return stdout default: false
  • stderr - return stderr default: false

client.containers().unpause(name, options) - Wait a Container

• Docker Documentation
• name - the name or id of the container
• options

client.containers().remove(name, options) - Wait a Container

• Docker Documentation
• name - the name or id of the container
• options
  • v - Remove the volumes associated to the container default: false
  • force - Kill then remove the container default: false

Images

client.images().list(options) - Wait a Container

• Docker Documentation
• options
  • filters - map[string][]string to process on the images list

client.images().build(stream, options, registryAuth) - Build an Image From a Dockerfile

• Docker Documentation
• options +
• registryAuth
  • username
  • password
  • serveraddress

client.images().create(options, registryAuth) - Create Image

• Docker Documentation
• options
  • fromImage
  • fromSrc
  • repo
  • q
  • tag
• registryAuth
  • username
  • password
  • serveraddress

client.images().inspect(name, options) - Inspect an Image

• Docker Documentation
• name - the name or id of the image
• options

client.images().history(name, options) - History of an Image

• Docker Documentation
• name - the name or id of the image
• options

client.images().push(name, options, registryAuth) - Push an Image on the Registry

• Docker Documentation
• name - the name or id of the image
• options
  • tag
• registryAuth
  • username
  • password
  • serveraddress

client.images().tag(name, options) - Tag an Image

• Docker Documentation
• name - the name or id of the image
• options
  • repo
  • tag

client.images().remove(name, options) - Remove of Image

• Docker Documentation
• name - the name or id of the image
• options
  • repo
  • tag

client.images().search(options) - Search Images

• Docker Documentation
• name - the name or id of the image
• options
  • term
  • limit
  • filters

Networks

client.networks().list(options) - List Networks

• Docker Documentation
• options
  • filters - JSON encoded network list filter.

client.networks().create(model, options) - Create a Network

• Docker Documentation
• model - a json model representing the network
• options

client.networks().inspect(id, options) - Inspect a Network

• Docker Documentation
• id - the network id or name
• options

client.networks().remove(id, options) - Remove a Network

• Docker Documentation
• id - the network id or name
• options

client.networks().connect(id, options) - Connect a Container to a Network

• Docker Documentation
• id - the network id or name
• options

client.networks().disconnect(id, options) - Disconnect a Container to a Network

• Docker Documentation
• id - the network id or name
• options

Nodes

client.nodes().list(options) - List Nodes

• Docker Documentation
• id - the node id
• options
  • filters - JSON encoded node list filter.

client.nodes().inspect(id, options) - Inspect a Node

• Docker Documentation
• id - the node id
• options

client.nodes().remove(id, options) - Remove a Node

• Docker Documentation
• id - the node id
• options

client.nodes().update(id, options) - Update A Node

• Docker Documentation
• id - the node id
• options
  • version - The version number of the node object being updated. This is required to avoid conflicting writes.

Plugins

client.plugins().list(options) - List Plugins

• Docker Documentation
• options
  • filters - a JSON encoded value of the filters (a map[string][]string) to process on the services list.

client.plugins().install(options) - Install a Plugin

• Docker Documentation
• options
  • name - Name of the plugin to pull. The name may include a tag or digest. This parameter is required.

client.plugins().inspect(id, options) - Inspect a Plugin

• Docker Documentation
• options

client.plugins().enable(id, options) - Enable a Plugin

• Docker Documentation
• options

client.plugins().disable(id, options) - Disable a Plugin

• Docker Documentation
• options

client.plugins().remove(id, options) - Remove a Plugin

• Docker Documentation
• options

Services

client.services().list(options) - List Services

• Docker Documentation
• options
  • filters - a JSON encoded value of the filters (a map[string][]string) to process on the services list.

client.services().create(options, registryAuth) - Create a Service

• Docker Documentation
• options

client.services().remove(id, options) - Remove a Service

• Docker Documentation
• id - id or name of the service
• options

client.services().inspect(id, options) - Inspect a Service

• Docker Documentation
• id - id or name of the service
• options

client.services().logs(id, options) - Get Service Logs

• Docker Documentation
• id - id or name of the service
• options
  • details - boolean, Show extra details provided to logs.
  • follow - boolean, Return the logs as a stream.
  • stdout - boolean, Return logs from stdout
  • stderr - boolean, Return logs from stderr
  • since - number, Only return logs since this time, as a UNIX timestamp
  • timestamps - boolean, Add timestamps to every log line
  • tail - Only return this number of log lines from the end of the logs. Specify as an integer or all to output all log lines.

client.services().update(id, options, registryAuth) - Update a Service

• Docker Documentation
• id - id or name of the service
• options
  • version - The version number of the service object being updated. This is required to avoid conflicting writes.

Swarm

client.swarm().info(options) - Swarm Info

• Docker Documentation
• options

client.swarm().init(options) - Initialize a Swarm

• Docker Documentation
• options

client.swarm().join(options) - Join a Swarm

• Docker Documentation
• options

client.swarm().leave(options) - Leave a Swarm

• Docker Documentation
• options
  • force - Boolean (false/true). Force leave swarm, even if this is the last manager or that it will break the cluster.

client.swarm().update(options) - Update a Swarm

• Docker Documentation
• options
  • version - The version number of the swarm object being updated. This is required to avoid conflicting writes.
  • rotateWorkerToken - Set to true to rotate the worker join token.
  • rotateManagerToken - Set to true to rotate the manager join token.

Tasks

client.tasks().list(options) - List Services

• Docker Documentation
• options
  • filters - a JSON encoded value of the filters (a map[string][]string) to process on the tasks list.

client.tasks().inspect(id, options) - Inspect a Task

• Docker Documentation
• options

Volumes

client.volumes().list(options) - List Volumes

• Docker Documentation
• options
  • filters - a JSON encoded value of the filters (a map[string][]string) to process on the volumes list.

client.volumes().create(options, registryAuth) - Create a Volume

• Docker Documentation
• id or name of the volume
• options

client.volumes().remove(id, options) - Remove a Volume

• Docker Documentation
• id or name of the volume
• options

client.volumes().inspect(id, options) - Inspect a Volume

• Docker Documentation
• id or name of the volume
• options

Secrets

client.secrets().list(options) - List Secret

• Docker Documentation
• options
  • filters - map[string][]string to process on the secrets list

client.secrets().create(model, options) - Create Secret

• Docker Documentation
• model - the JSON model that the Docker API consumes
• options

client.secrets().inspect(id, options) - Inspect Secret

• Docker Documentation
• id - the id or name of the secret
• options

client.secrets().remove(id, options) - Remove Secret

• Docker Documentation
• name - the id of the secret
• options

client.secrets().update(id, model, options) - Update Secret

• Docker Documentation
• id - the id or name of the secret
• model - the JSON model that the Docker API consumes
• options
  • version - The version number of the secret object being updated. This is required to avoid conflicting writes.

Daemon

client.info() - System Wide Information

• Docker Documentation

client.auth(options) - Authentication Configuration

• Docker Documentation
• options
  • username
  • password
  • serveraddress

client.version() - Version

• Docker Documentation

client.ping() - Ping Daemon

• Docker Documentation

client.events() - Events Stream

• Docker Documentation
• options
  • since - Timestamp. Show all events created since timestamp and then stream
  • until - Timestamp. Show events created until given timestamp and stop streaming
  • filters - value of the filters (a map[string][]string) to process on the event list

harbor-master's Issues

Containers.start response handling

Hello,

thanks for the lib.
i think i found something not working as expected.
if i use the client.containers().start(container.Id); I'm getting a error with status code 204.
As of the docker documentation this is the code for success.
204 no error
304 container already started/stopped

i think they should be added in
harbor-master/lib/endpoints/containers.js
Line: 233
Line: 253
And on line 273 only the code 204 cause ther is no code 304 on restart.

hopefully i'm not wrong.
should i open a PR?

there is a PR#4 with only the code 204 but on more files. maybe this should merged first, and then add 304 to start and stop function?

Best regards

Use named pipes on Windows?

I must admit to being slightly mistified as to how it works, but many systems support "named pipes" (or npipe:// URLs) on windows to bypass HTTPS issues and the need to get certificates for TLS over HTTP.

For example, dockerode will work if you set socketPath to //./pipe/docker_engine, and somehow that works, see: apocas/dockerode#290

Setting path in harbor-master to the same does not work. One fundamental point of my mystification is that I don't actually understand the meaning of the // in docker for windows. It seems to have been a temporary measure in referring to moby paths, that quickly fell out of usage again... except in this one case.

Bug detected and fixed

Hi,

I found a small bug that fires when calling the client.networks().connect() method.
The reason is that the "options" validation schema is missing. To fix this bug you have to add
the following lines to lib/schemas/networks.js

module.exports.connect = {
options: Joi.object()
};

Regards,

Gianluca

Query parameters aren't passed correctly to the Rest interface

The docker docs are pretty bad for optional args to any of the commands but

To filter a service by name in the task API you need a request of the form

curl -v --unix-socket /var/run/docker.sock -X GET http:/v1.32/tasks?filters=%7B%22service%22%3A%7B%22service_name%22%3Atrue%7D%7D

The request library is restructuring the query part of the URI to something like

curl -v --unix-socket /var/run/docker.sock -X GET http:/v1.32/tasks?filters[service[service_name]]=true

I'm using the tasks endpoint with options of

{filters: {service: {"service_name": true}}}