Mason JSON
- Mason JSON Reference
- 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
Name | Type | Required | Description |
---|---|---|---|
key | string | yes | A key is eventually mapped back to an environment variable. |
value | string | yes | A default value. |
description | string | no | A human friendly explaination of what the value is for. |
required | bool | no | A bool indicating whether a value is required. Default: true |
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"]
},
}