sloppy.JSON Reference

sloppy JSON

Configure your Applications with sloppy.json

Configure your Applications with sloppy.json

UPDATE: While you still need JSON when using the sloppy.io API directly, our YML format is the prefered way when using our CLI as it is pretty similar to the docker-compose format.

The projects and multi-container applications you are hosting with sloppy.io are defined using a simple configuration file in JSON format. We call it sloppy.json. This configuration file provides a basic structure to build your Dockerized applications. Think of it as a Docker Compose file with a few unique add-ons that allow for container orchestration, web hosting, health checks and much more. In this documentation we’ll walk you through building your applications using the sloppy.json file format; and explain every single configuration option in detail.

Basic structure

To enable you to orchestrate even the most complex projects with numerous containers, the basic structure of the sloppy.json configuration file consists of:

Project Service(s) App(s)
Definition of exactly one project. Definition of one or multiple services. Within each service, one or multiple apps (think: Docker containers).

Understanding sloppy.io Projects, Services and Apps

A sloppy.io project, for example a “web shop”, is a group of one or more sloppy.io services. These form logical units in your project describing technical services (e.g. “front-end” or “back-end”) or other meaningful entities, like “encoding-service” or “database-service”. Each service itself comprises one or more components, called sloppy.io apps. Each app has its own name (id) and represents a single Docker container referencing its own image. These images can be one of the many public images from the Docker Hub or can be built by yourself. Here is a simple example, illustrating the basic structure of a sloppy.json configuration file by defining a simple project called my-first-project. It consists of one single service named my-first-service, which contains only one app called my-first-app.

{
  "project": "my-first-project",
  "services": [
    {
      "id": "my-first-service",
      "apps": [
        {
          "id": "my-first-app",
          "domain": {
            "uri": "MY-DOMAIN.sloppy.zone"
          },
          "image": "sloppy/apache-php",
          "cmd": "/app.sh",
          "port_mappings": [
            {
              "container_port": 80
            }
          ]  
        }  
      ]
    }
  ]
}

For more examples please visit us on GitHub.

Back To Top

Project level keys

Project level keys

On the project level, both the project’s name (id) and the services keys are required.

KEY EXPLANATION

project

This is the name of the project. You can reference it in CLI commands like sloppy show, sloppy logs or sloppy delete.

The project name needs to be unique within the environment you’re deploying it to. An attempt to create an application with the same name twice within one environment will result in an error message. The name can only include lower case alphanumeric characters and a ‘-‘.

REQUIRED

services

This key contains the array of service definitions included in this project.

REQUIRED

Back To Top

Service level keys

Service level keys

On the project level, both the service’s name (id) and the apps keys are required.

KEY EXPLANATION

id

This is the name of the service. You can reference it in CLI commands like sloppy show, sloppy logs or sloppy delete. The service name needs to be unique within its parent project. The name can only include lower case alphanumeric characters and a ‘-‘.

REQUIRED

apps

This key contains the array of application definitions included in a service.

REQUIRED

Back To Top

Application level keys

Application level keys

On the application level, there are several keys available as indicated below:

Back To Top

id


id

(REQUIRED)

This is the name of the application (or Docker container, if you will). You can reference it in CLI commands like sloppy show, sloppy logs or sloppy delete.
The app name needs to be unique within the service/project you’re deploying it to. An attempt to create an application with the same name twice within one environment will result in an error message. The name can only include lower case alphanumeric characters and a ‘-‘.

Back To Top

image

image

(REQUIRED)

This is the image from the Docker Hub or quay.io which you want to run in the sloppy.io cloud. Using tags is the preferred way to reference a docker image. You really should use them to control what version of an image you’re running.

{"image": "wordpress:4.3.1"}

or without tags, defaults to latest

{"image": "wordpress"}

or

{"image": "quay.io/mikemichel/wordpress"}

Back To Top

cmd

cmd

(OPTIONAL)

Optional key, if present, expects as value of a string. This string will be passed as argument when your app is started, like the arguments you pass to docker run. The effect of these arguments depends on how the container is set up. Please refer to the Dockerfile documentation, especially on the CMD and ENTRYPOINT directives.

{"cmd": "./start.sh"}

Back To Top

ssl (beta feature)

ssl (beta feature)

(OPTIONAL)

Make your application available via HTTPS and a free ssl cert from letsencrypt.org. If you have an app with a custom domain you can easy create a ssl cert for you app using sloppy.io.

Make sure your domain points to our loadbalancer then set the ssl flag in your sloppy.json:

 { "ssl": true }

The certificate will be automatically renewed after 2 month.

JSON example:


{
    "project": "oh-hai",
    "services": [
        {
            "id": "frontend",
            "apps": [
                {
                    "id": "apache",
                    "domain": {
                        "uri": "test1.mmbash.de test2.mmbash.de"
                    },
                    "mem": 256,
                    "ssl": true,
                    "image": "sloppy/apache-php",
                    "instances": 1,
                    "port_mappings": [
                        {
                            "container_port": 80
                        }
                    ],
                    "env": {
                        "MESSAGE": "sloppy.io rulez!"
                    }
                }
            ]
        }
    ]
}

Back To Top

networking

domain

(OPTIONAL)

Make your application available via HTTP through port 80 (the HTTP default port) under a free my-domain.sloppy.io or a custom domain name. Learn more about how to configure internal and external domains for your applications.

port mappings

(OPTIONAL)

This key expects the port number to be exposed for this application. Every container port will be mapped outside to 80/443. Think of:

docker run -it -p 80:4000 -p 443:4000 ...

Please note: With our shared hosting plans you can only expose HTTP, and not TCP ports like 22 or 3306. For now, you can only expose one port per app.

If you are running several apps within one project, you do not need to expose ports between apps (e.g. exposing the mysql port to the apache container).

The following example exposes port 4000. From outside the service will be reachable at port 80 and 443:

{"port_mappings":[
  {
    "container_port": 4000
  }
]}

Back To Top

env

env

(OPTIONAL)

This is a definition of environment variables. These variables will be available within the running docker containers, similar to executing docker run -e. Entries must be of type string. Also refer to the documentation of each Docker image to learn which environment variables it supports.

Example:

{"env": {
   "FIRST_VARIABLE": "first",
   "SECOND_VARIABLE": "second",
   "NUMERIC_VARIABLE": "123",
   "MYSQL_ROOT_PASSWORD": "secr3t",
   "MYSQL_USER": "username",
   "MYSQL_PASSWORD": "password",
   "MYSQL_DATABASE": "db-name"
}}

Back To Top

performance

instances

(OPTIONAL)

This is the number of instances simultaneously running on the application, by default it’s 1. The following has the app running on 3 instances:

{"instances": 3}

mem

(OPTIONAL)

This key defines how much memory (in MiB) is allocated to the application. It defaults to 512MiB. Entries must be of type integer. The following example attributes 512 MiB to the app:

{"mem": 1024}

Back To Top

volumes

volumes

(OPTIONAL)

This is a definition of volumes. Using the variables you can set the path of the container as well as the size. The volume size have to be a multiple of 8.

Example:

{"volumes":[ 
  {
    "container_path":"/var/lib/mysql",
    "size": "8GB"
  }
 ]
}

Learn more about volumes here.

Back To Top

dependencies

dependencies

(OPTIONAL)

This key is containing an array of dependency objects, which are used to define dependencies between apps (containers). Dependencies make sure that the services are started in the appropriate order.

Learn more about dependencies here.

Back To Top

health_checks

health_checks

(OPTIONAL)

This is a definition of an array of health checks for your app. The sloppy.io platform will test the app and if the app turned unhealthy it will be restarted automatically.

Example:

{"health_checks":[  
  {  
    "timeout_seconds":10,
    "interval_seconds":10,
    "max_consecutive_failures":3,
    "path":"/",
    "type":"HTTP",
    "grace_period_seconds":3
  }
]}

Learn more about health checks here.

Back To Top

in Documentation