Configuration file

All the app specific configuration you need to run your app with automated deployments for testing.

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.

valist.yml

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: backend
public: true
port: 5000
cmd: node /app.js
depends_on:
- mongo
mongo:
image: mongo:4.0
steps:
- name: mongodump
path: mongodump
out: /dump
cache: true
- name: load
service: mongo
copy:
- 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: static
dockerfile: ./valist.Dockerfile
dist: /app/dist/sample-app
index: index.html
cmd: ng build --prod

Configuration options

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.

Service options

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>

Step options

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>