There needs to be one file in your repo called valist.yml that specifies how to run your application. You can also include Dockerfiles for building static websites or for running your own web server.
The configuration file has a structure that is very similar to that of docker-compose.yml. However, it is more simplified and has more functionality to run and automate the setup of your staging environments efficiently.
The file must be in the root of the code repository's directory.
Here is an example of the configuration of a Nodejs backend using MongoDB. It also includes steps to load data to use for the staging environment. All these configuration options will be described later.
services:backend:path: backendpublic: trueport: 5000cmd: node /app.jsdepends_on:- mongomongo:image: mongo:4.0steps:- name: mongodumppath: mongodumpout: /dumpcache: true- name: loadservice: mongocopy:- mongodump:/cmd: mongorestore /dump
Here is an example of the configuration of a web application that is built with Angular that is build using a custom Dockerfile. The runtime "static" is used so you don't need to worry about including your own web server.
services:app:runtime: staticdockerfile: ./valist.Dockerfiledist: /app/dist/sample-appindex: index.htmlcmd: ng build --prod
The configuration file has the following sections.
Services – A map of services used to run your application. This may include several backends, databases, etc. The key is the name of the service which is used to identify it and to refer to it.
Steps – An ordered list of steps to run to setup your staging environment. This is often used to fill the database with some data. The output of a step can be stored in a directory which can be used by other steps. Steps provide other steps with data that can be cached so they don't need to be run for every commit.
Property | Required | Description | Type | Default |
runtime | no | A type of runtime for running the service. Either "docker" or "static". | string | docker |
path | no | Where the code is stored for this service. | string | ./ |
image | yes if runtime is docker and no dockerfile | A Docker image used to run your service. This is used if there is no Dockerfile specified. | string | |
dockerfile | yes if runtime is docker and no image and can not be found at default path. | A path to the service's Dockerfile relative to the specified path option. This is used if no image option is specified. | string | ./Dockerfile |
dist | no | For static runtimes, this is used to specify where the static assets are located. | string | ./ |
index | no | For static runtimes, you might want to specify which file select when the path / is specified. Normally, index.html is used. | string | index.html |
public | yes if you want it to be reachable on the web | A boolean for exposing this service on the internet. This is by default false so that you don't accidentally expose databases. This could for example be used to expose multiple backends to one client running in a browser. Static runtimes are however by default public. | boolean | false |
port | yes if runtime is docker | A numeric value required for Docker runtimes to that your web server is listening to. When your service is hosted, the port 443 will automatically be mapped to this port. | int | |
cmd | no | You can optionally specify a command used to run your service. This will override what is specified as CMD. | string | |
environment | no | Environment variables included when running your Docker image. | array<string> | |
env_file | no | File paths relative to the path for .env files containing environment variables. This can be used in addition to the environment option. | array<string> | |
depends_on | no | A list of services and steps that need to be run before starting this service. | array<string> | |
A step executes a command either on an existing service or using its own container. To execute the command on an existing container, use the "service" option. The step can have its own container which is done by either specifying an image or by building a new image using code at the specified path with the specified Dockerfile.
Property | Required | Description | Type | Default |
name | yes | An identifier for the step. This can be used to reference the step in other steps or services. | string | |
path | no | Where code is specified for this step. This is not relevant if an already built image is used for this step. | string | ./ |
out | no | A path within the Docker container for where files are located that are meant to be used by other steps. | string | |
cache | no | A boolean for if the output of a step be cached so that it is reused the next build. It is often important to cache this if you are downloading data from your production database which could take a lot of time and put pressure on your production database. | boolean | true |
service | no | A service on which you want to execute a command. | string | |
dockerfile | no | A path to the Dockerfile used to build an image for running this step. This can be used if an existing service is not specified in the service option. | string | ./ |
image | no | An already built image to use to run the step. This can be used if an existing service is not specified in the service option. | string | |
cmd | yes if using a service | A command to run on an existing service or within the container created for this step when specifying a dockerfile or image option. | string | |
copy | no | A list of directories to copy from previous steps. Using the syntax "{service-name}:{container-path"}. Example: "mongodump:/" will copy the out directory from the step called "mongodump" to the root directory of this step's container. | array<string> | |
environment | no | Environment variables included when running your command, | array<string> | |
env_file | no | File paths relative to the path for .env files containing environment variables. This can be used in addition to the environment option. | array<string> | |
depends_on | no | A list of services and steps that need to be run before starting this step. This is not necessary for dependencies that can be found implicitly using in the service or copy options. | array<string> | |