Domain Specific Language¶
Floto uses a domain specific language (DSL) to describe and configure systems. This language is embedded in JavaScript, allowing system descriptions to take full advantage of all language features.
Basic structure¶
A system description consist of three main components:
- Hosts - virtual or physical machines
- Images - abstract container classes
- Containers - concrete container instances
Each of these components is declared via a function taking its name and a definition.
-
host(name, definition)¶ Declare a host
Parameters: - name – the host’s name
- definiton – the host’s definition
-
image(name, definition)¶ Declare an abstract container image
Parameters: - name – the image name
- definiton – the image definition
The image definition contains one field named build, which is a function running a series of build steps (see below).
-
container(name, definition)¶ Declare a concrete container
Parameters: - name – the container name
- definiton – the container definition
The container definition contains the following fields:
- host - the host to run this container on
- image - the image to base this container on
- prepare (optional) - a preparation function, used to distributed configuration information before the actual containers are built
- configure - a configuration function, which may contain further build steps to configure the container
Build steps¶
In an image’s build function, and a container’s configure function, the following function may be invoked to perform certain steps during the container build process. These steps translate directly to Dockerfile build steps.
-
from(rootImage)¶ Use a root image as image base. (Only for images)
This function translates directly into a Docker FROM instruction. This function must be invoked first in every build definition.
Parameters: rootImage – the root image name in a docker registry
-
run(command)¶ Run command during the build step. This function translates directly into a Docker RUN instruction.
Parameters: command – the command to execute
-
env(key, value)¶ Set an environment variable This function translates directly into a Docker ENV instruction.
Parameters: - key – the environment key to set
- value – the environment value to set
-
workdir(workingDirectory)¶ Set an environment variable This function translates directly into a Docker WORKDIR instruction.
Parameters: workingDirectory – the working directory to use
-
volume(path, name, options)¶ Create a data volume This function creates a volume on the host system using the name, which is mounted at path in the container. The volume is persisted and survives container redeploys
Parameters: - path – the target path inside the container
- name – the name to use for this volume, must be unique for each container
- options – additional options
-
mount(hostPath, containerPath)¶ Mount a directory inside the container This function allows sharing data between containers on the same host
Parameters: - hostPath – the path on the host system
- containerPath – the target path inside the container
-
user(user)¶ Executes all following run and cmd commands with the given user instead of root
Parameters: user – name or id of the user which will run the commands
-
addTemplate(templatePath, destinationPath, templateConfig)¶ Use a file as template and copy it to the image
Parameters: - templatePath – path to the Freemarker template file in the system running floto
- destinationPath – the destination path in the image
- templateConfig – an object used to fill in template parameters
-
addFile(filePath, destinationPath)¶ Copy a file to the image
Parameters: - filePath – path to the file in the system running floto
- destinationPath – the destination path in the image
-
cmd(command)¶ Set the command to run when starting a container.
This only translates indirectly to the Docker RUN instruction. In particular, the command is wrapped to allow restarts and propagate SIGTERM and SIGKILL signals, as well as document exit codes
Parameters: command – the command to run when the container is started