Common Container Configuration Format

The Common Container Configuration Format (cccf) is an attempt at creating a standard container configuration format, in JSON.

It describes containers, their properties and the relationship between them. This repository will include a JSON schema validator for the cccf.

The format is extensible so other modules can expand it's capabilities and semantics.

DISCLAIMER WORK IN PROGRESS

Example

{
    "id"      : "app",                 // Container Id
    "image"   : "megacorp/webapp",     // Image path
    "cmd"     : "python server.py",    // Command to run        (optional)
    "ports"   : ["80:80","53:53/udp"], // List of port mappings (optional)
    "env"     : ["FOO=BAR"],           // Environment variables (optional)
    "volumes" : ["/tmp:/tmp"],         // Container volumes     (optional)
}

Id

The id, app in the example, is the container identifier. It can be any arbitrary string. No spaces.

Image

The image, megacorp/webapp in the example, is URI to the container image. It can be any valid URI, relative or full.

Cmd

The cmd, python server.py in the example, is the command to execute when running the container. It can be an arbitrary string.

Ports

The ports, ["80:80"] in the example, is a list of port mappings. A port mapping is defined using a string with two ports separated by a colon: "host-port:container-port" where host-port references a port on the host running the container, and the container-port references a port inside the running container. Since version 3.2.0 cccf also support specifying the protocol; ["53:53/udp"]. The two supported protocols are tcp and udp.

Env

The env, ["FOO=BAR"] in the example, is a list of environment variables. An evironment variable is defined using a string with a key and a value separated by a equals sign: "key=value".

Volumes

The volumes, ["/tmp:/tmp"] in the example, is a list of volumes to mount inside the container. There are two different ways to specify a volume:

"/host/path:/container/path"  // Mounts a specified path on the host to the specified path in the container
"/host/path"                  // Mounts a specified path on the host to the same path in the container

Install the module

npm install cccf 

API

validate(containers)

The main use-case for this module is to validate container configs.

var cccf       = require('cccf')
var container  = require('./container.json')
var containers = require('./containers.json')

try {
  cccf.validate(container)
  cccf.validate(containers)
} catch(e) {
  console.log(e instanceof cccf.exception, e.trace)
}

random(num, opts)

Generate random container configs. Useful for testing etc.

var cccf = require('cccf')
var containers = cccf.random(5, { host: { hostname: 'yolo' }})

schema

The cccf json schema.

exception

The cccf exception throws if bad config.

Ecosystem

Some modules using cccf

• cccf-scale - Scale up a cccf config
• cccf-diff - Diff two cccf configs
• cccf-scheduler - Schedule containers
• cccf-docker-instructions - cccf and cccf-docker -> docker cli instructions

Changelog

3.3.0

• Added support for generating random containers

3.2.0

• Support for port protocols tcp and udp
• Removed docs for expose (planning to remove it in next major)

3.1.0

• Loosened the regex for env. I'm gonna need some help with the regexes :-P Feel free to HALP!

3.0.0

• Throwing exceptions instead of returning err. Makes for better composition. If no err, validate returns the passed config (in input format).

2.1.0

• Added cccf/example.json and cccf/example-multiple.json for easier example require from other modules

2.0.0

• Removed the validateMultiple API and rather do a quick instanceof Array verification for validate

1.0.1

NB! Moved from common-container-configuration-format to cccf.

• Updates for package move

1.0.0

• Initial release