This page contains a reference for each directive which can appear in a Layerfile.
For a more introductory reference, see the documentation home
ARTIFACT [PRIVATE/PUBLIC] [file/directory...]
ARTIFACT instruction allows you to download files from the virtual machine running the test.
ARTIFACT PUBLIC built/file.jarto create a download link to the built jar file
ARTIFACT PRIVATE /var/log/buildlogto create a download link to the logs for the run
BUTTON instruction allows you to block the progress of a run until the button is pressed.
- Commonly used for deployment:
BUTTON would you like to deploy?followed by
RUN ./deploy.shwould not deploy unless the button was pressed.
CACHE [cached directories...]
CACHE instruction makes specific files/directories be shared across runs, almost always as a performance improvement.
See the tuning performance documentation for more details.
CACHE /var/cache/aptto speed up
RUN apt-get update
CACHE ~/.cache/go-buildto speed up
RUN go install
CACHE ~/.npm ~/.next/cache ~/.yarn/cacheto speed up
Each LayerCI account gets a fixed amount of cache storage, and we periodically delete old or inactive caches.
CHECKPOINT (name) or
CHECKPOINT instruction allows you to control exactly when LayerCI will take snapshots of the pipeline.
On future runs, if no files or instructions have changed since the snapshot was taken, the runner will restore the snapshot instead of repeating work.
CHECKPOINT is not usually required, it’s advised not to use it unless you are using the API or there is measurable performance benefit to doing so.
CHECKPOINT disabledto disable checkpointing from that point onwards
CHECKPOINT deployto create a checkpoint named “deploy”, which can be triggered as a lambda from our api
CHECKPOINTto expliticly take a checkpoint at a specific point (which happens automatically by default), or re-enable checkpointing after
See the tuning performance documentation for more details.
COPY [files...] [destination]
COPY instruction moves files from your repository to the runner.
Files can be: - relative (to the layerfile location for sources, and WORKDIR location, or /root if not specified for destination) - absolute (from the root of the repository for sources, and filesystem root for destination)
COPY . .to copy the directory containing the Layerfile to the current working directory (or /root if WORKDIR has not been used)
COPY package.json yarn.lock ./to copy those two files to the current directory.
COPY / /rootto copy the entire repository to /root in the runner.
ENV instruction persistently sets environment variables in this Layerfile
$GOPATH/binto the existing path.
ENV CI=hellosets the variable
$CIto the value
EXPOSE WEBSITE [location on runner] (path) (rewrite path)
EXPOSE WEBSITE instruction creates a persistent link to view a webserver running at a specific port in the Layerfile. It’s especially useful for sharing changes with non-technical stakeholders or running manual QA/review.
EXPOSE_WEBSITE_URL is available even before
EXPOSE WEBSITE if you need to “bake” the path to the exposed website URL.
EXPOSE WEBSITE localhost:80to expose the local webserver at port 80
EXPOSE WEBSITE localhost:80 /apiwith
EXPOSE WEBSITE localhost:3000 /to route all requests that start with /api to port 80 in the runner, and all other requests to port 3000.
FROM instruction tells LayerCI what base to use to run tests from.
There can only be one
FROM line in a Layerfile, and it must always be the first directive in the Layerfile.
For now, only
FROM vm/ubuntu:18.04 is allowed as a top level, but inheriting from other Layerfiles is possible.
FROM vm/ubuntu:18.04to use ubuntu:18.04 as the base.
FROM ../baseto inherit from the file at
../base/Layerfilerelative to the current Layerfile
FROM /baseto inherit from the file at
MEMORY instruction allows you to reserve memory before you need it.
In particular, languages like
nodejs might require memory to be available before they are used.
We’ll automatically add memory as it’s requested, adding memory with
MEMORY will decrease snapshot speed.
There’s a limit to an additional
4G of memory added at once.
MEMORY 2Gto ensure at least 2 gigabytes of memory are available.
RUN (BACKGROUND|REPEATABLE) [command ...]
RUN instruction runs the given script, and fails the entire Layerfile if the given command fails.
For example, you might use
RUN echo "the directory is $(pwd)" to print your current directory.
RUN echo helloprints “hello” to the terminal
RUN BACKGROUND python3 -m http.serverrun
python3 -m http.serverpersistently in the background.
RUN REPEATABLE docker build -t hellois a performance optimization, see tuning performance
SECRET ENV [secret name...]
SECRET ENV instruction adds values from secrets to the runner’s environment.
It’s useful for authenticating LayerCI with other services on your behalf.
SECRET ENV ENV_FILEto expose your dotfile env
.envand then use
RUN echo "$ENV_FILE" | base64 -d > ~/.envto decode the uploaded env file to the specific location.
SETUP FILE [file ...]
SETUP FILE instruction causes the contents of the given file to be sourced before every
This is equivalent to copy/pasting the contents of the file into the terminal before every
A common use case is to set a lot of environment variables using an “.env” file, or specifying a custom “.bashrc” file.
SETUP FILE .envto run
source (repository root)/.envbefore every
SPLIT instruction causes the runner to duplicate its entire state a number of times at a specific point.
Each copy of the runner will have
SPLIT_NUM environment variables automatically set.
The former will be the index of the runner, and the latter will be the number of copies.
SPLIT 3and three copies of the runner will have
ENV SPLIT=0 SPLIT_NUM=3and
ENV SPLIT=1 SPLIT_NUM=3and so on.
USER instruction allows you to run as a non-root user.
The user is added to the
root group to circumvent permission denied errors.
USER wwwto run the remaining commands as the
WORKDIR instruction changes the locatation from which files are resolved in the runner.
WORKDIR /tmpto run commands in the
/tmpdirectory within the runner.
WORKDIR helloto run commands in the
(workdir)/hellodirectory within the runner.