sloppy.YML Reference

sloppy YML

Configure your Applications with sloppy.yml

Configure your Applications with sloppy.yml

In addition to our sloppy.io JSON format, we also offer you to deploy your apps using the YAML format. 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. While you still need JSON when using the sloppy.io API directly, our YML format is the preferred way when using our CLI as it is pretty similar to the docker-compose format.

In this documentation we’ll walk you through building your applications using the sloppy.yml 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.yml configuration file consists of:

Project Service(s)
Definition of exactly one project. Definition of one or multiple services.

 

Understanding sloppy.io Projects and Services

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. “frontend” or “backend”) or other meaningful entities, like “encoding-service” or “database-service”. Each service itself comprises one or more components, called sloppy.io apps (here apache). Each app 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.yml configuration file by defining a simple project called my-first-project.

version: "v1"
project: "my-first-project"
services:
  frontend:
    apache:
       image: sloppy/apache-php
       domain: "MY-DOMAIN.sloppy.zone"
       ports: 80
       cmd: "/app.sh"

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 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

Application level keys

Application level keys

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

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. The default registry is dockerhub.

image: "wordpress:4.3.1"

or without tags, defaults to latest

image: "wordpress"

or

image: "quay.io/mikemichel/wordpress"

to start an image from quay.io

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 using a CNAME then set the ssl flag in your sloppy.yml:

ssl: true

The certificate will be automatically renewed after 2 month.

Example:

version: "v1"
project: "ymlftw"
services:
  frontend:
    apache:
      image: "sloppy/apache-php"
      instances: 1
      mem: 128
      domain: "mydomain.com"
      ssl: true
      port: 80
      env:
        - MESSAGE: "changed"

Back To Top

networking

domain

(OPTIONAL)

Make your application available under a free *.sloppy.zone or a custom domain name. Learn more about how to configure internal and external domains for your applications.

port 

(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: 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. 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 running your 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 1024 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 (8, 16, 24,..). If the Dockerfile of your image has volumes defined, we add them automatically for you.

Example:

volumes:
- 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

healthchecks

healthchecks

(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:

healthchecks:
- timeout: 10
  interval: 10
  max_consecutive_failures: 3
  path: "/"
  type: "HTTP"
  grace_period_seconds: 3

Learn more about health checks here.

Back To Top

in Documentation