Mason JSON

• Mason JSON Reference
  • Name
  • Description
  • Keywords
  • Website
  • Repository
  • Type
  • Mason Version
  • Image
  • Command
  • Entrypoint
  • Scale
  • Memory
  • CPU
  • Privileged
  • Ports
  • Environment
  • Labels
  • Volumes
  • Links
  • Questions
  • Registries
  • Targets
• Example Application Mason JSON
• Example Service Mason JSON
• Example Load Balancer Mason JSON

Mason JSON Reference

The Mason JSON is a JSON Schema for defining services, networks and volumes in Codemason. The Schema is deliberately and heavily modelled off the docker-compose.yml file.

Although it's very similar, it also adds functionality beyond what is capable with a standard docker-compose.yml file.

Additional capabilities include:

• Questions - accept user input
• Registries - connect to private registries
• Standard format makes programmatically dealing with container orchestration a breeze

Name

[string, required] A simple name for this application, service or instance

Description

[string, optional] A short description of what your application, service or instance is

Keywords

[array, optional] Array of keywords related to this application

Website

[string, optional] Link to the projects website

Repository

[string, optional] Link to the repository containing the related source code

Type

[string, required] Describes the type of Mason JSON we are dealing with. Currently application, service and loadbalancer are they only available types.

{
    "type": "service",
}

Mason Version

[string, required] Identifies how your Mason JSON should be parsed.

{
    "masonVersion": "v1", 
}

Image

[string, optional] Specify the Docker image to start the container from. This provides the framework and runtime support for your applications.

{
    "image": "codemasonhq/php",
}

Command

[string|array, optional] The command that will run to launch and run your application. Our official images are have the default run command baked in, which is used if this parameter is left empty. However, the command option is available if you'd like to get your hands dirty.

{
    "command": "apache2 -D FOREGROUND",  
}

Entrypoint

[string, optional] Set the entrypoint for your container. The entrypoint is prefixed to any command you run through the container.

{
  "entrypoint": "command param1 param2",
}

Scale

[integer, optional] Set the number of containers to spin up.

{
  "scale": 1,
}

Memory

[string, optional] Set the memory limit for the container in mb.

{
  "memory": "128",
}

CPU

[string, optional] The value of shares of the CPU available to the container.

{
  "cpu": "04",
}

Privileged

[bool, optional] Grant extended privileges to the container.

{
  "privileged": false,
}

Ports

[array, optional] Define the ports to expose. You may specify specific ports (HostPort:ContainerPort) or just specify the container port and a random host port will be allocated.

{
    "ports": [
        "5432",
    ],
}

Environment

[object, optional] Set environment variables.

{
    "environment": {
        "POSTGRES_USER": "admin",
        "POSTGRES_PASSWORD": "mypass",
        "POSTGRES_DB": "test"
    }   
}

Labels

Set labels. [object, optional]

{
  "labels": {
    "com.example.foo": "bar"
  }
}

Volumes

[array, optional] Declare volumes to mount.

{
  "volumes": [
    "./data/mysql:/var/lib/mysql:rw"
  ]
}

Links

[array, optional] Define links to other services. Define a link in the following format, application/service. You can even provide an alias for links, application/service:alias.

{
    "links": [
        "pebble/postgres:database",
    ],
}

Questions

[array, optional]

Parameters

Example

{
    "questions": [
        {
            "key": "POSTGRES_USER", 
            "value": "admin",
            "description": "This variable will create the specified user with superuser power",
            "required": true,
        },
        {
            "key": "POSTGRES_PASSWORD", 
            "value": "",
            "description": "This environment variable sets the superuser password for PostgreSQL",
            "required": true,
        },
        {
            "key": "POSTGRES_DB", 
            "value": "",
            "description": "Default database that is created. If empty, then the value of POSTGRES_USER will be used.",
            "required": false,
        },
    ],
}

Registries

[array, optional] Through Mason JSON, you can also access your private registries and do awesome things privately.

Example

{
    "registries": [
        {
            "address": "registry.example.com",
            "email": "[email protected]",
            "username": "foo",
            "password": "bar123"
        }
    ],
}

Targets

[array, optional] An array containing targets for your Load Balancer.

[
    {
        "source": {
            "protocol": "http",
            "port": 80,
            "hostname": "pebble.mason.ci",
            "path": "/my-path",
        },
        "target": {
            "service": "pebble/web",
            "port": 80,
        }
    }
]

Application Mason JSON

Mason JSON is so powerful, you can use it to define the architecture of your entire application. To do this, simply define the services your application requires. Services accept the same schema as defined in this reference document.

Example

In this example, we are creating a simple PHP application and connecting it with a PostgreSQL database.

{
    "name": "pebble",
    "description": "A demo app",
    "keywords": ["codemason", "demo", "php"],
    "repository": "https://github.com/benmag/pebble",
    "masonVersion": "v1",
    "services": [
        {
            "name": "web",
            "description": "Web server",
            "image": "registry.mason.ci/benmag/pebble",
            "links": [
                "postgres"
            ]
        },
        {
            "name": "postgres",
            "description": "Object relational database",
            "image": "postgres",
            "ports": [
                "5432",
            ],
            "environment": {
                "POSTGRES_USER": "admin",
                "POSTGRES_PASSWORD": "mypass",
                "POSTGRES_DB": "test"
            },
        }
    ],
    "loadbalancer": {
        "name": "lb",
        "ports": [
            "80:80"
        ],
        "targets": [
            {
                "source": {
                    "protocol": "http",
                    "port": 80,
                    "hostname": "pebble.mason.ci",
                },
                "target": {
                    "service": "pebble/web",
                    "port": 80,
                }
            },
        ]
    }
}

Service Mason JSON

You can also just define a single service in a similar fashion with one minor additional requirement. You must define it's type as a service (type: "service").

Example

{
    "name": "postgres",
    "description": "Object relational database",
    "image": "postgres",
    "type": "service",
    "masonVersion": "v1",
    "ports": [
        "5432",
    ],
    "environment": {
        "POSTGRES_USER": "admin",
        "POSTGRES_PASSWORD": "mypass",
        "POSTGRES_DB": "test"
    },

    "questions": [
        {
            "key": "POSTGRES_USER", 
            "value": "admin",
            "description": "This variable will create the specified user with superuser power",
            "required": true,
        },
        {
            "key": "POSTGRES_PASSWORD", 
            "value": "",
            "description": "This environment variable sets the superuser password for PostgreSQL",
            "required": true,
        },
        {
            "key": "POSTGRES_DB", 
            "value": "",
            "description": "Default database that is created. If empty, then the value of POSTGRES_USER will be used.",
            "required": false,
        },
    ],
}

Load Balancer JSON

You can even define a Load Balancer in Mason JSON.

{
    "name": "lb",
    "description": "My Load Balancer",
    "type": "loadbalancer",
    "masonVersion": "v1",
    "targets": [
        {
            "source": {
                "protocol": "http",
                "port": 80,
                "hostname": "pebble.mason.ci",
            },
            "target": {
                "service": "pebble/web",
                "port": 80,
            }
        },
    ],
    "certificates": {
        "default": "1c1",
        "additional": ["1c2", "1c3"]
    },
}