This page contains a reference for each directive which can appear in a Layerfile.
For a more introductory reference, see the documentation home
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 [key=value...] or
BUILD ENV [key...]
ENV instruction persistently sets environment variables in this Layerfile
$GOPATH/binto the existing path.
ENV CI=hellosets the variable
$CIto the value
Build Environment variables
Some environment variables are dynamically set for the run and can be used in
BUILD ENV allows you to rerun a step whenever one of those variables change.
BUILD ENV example
FROM vm/ubuntu:18.04 BUILD ENV LAYERCI_BRANCH RUN echo "the current branch is: $LAYERCI_BRANCH"
CI variables are always
true in LayerCI.
GIT_TAG is the result of running
git describe --always in the repository.
GIT_COMMIT is the result of running
git rev-parse HEAD in the repository.
GIT_CLONE_URL is a token which can be used to clone this repository.
git clone https://[email protected]/org/repo.git
EXPOSE_WEBSITE_HOST is the hostname exposed by
It’s often used to link a frontend with a backend when running both with
EXPOSE WEBSITE and
You can even reference this before
EXPOSE WEBSITE is ever used, but the URL is only live after the run passes.
LAYERCI is always
true in LayerCI test runs.
LAYERCI_BRANCH is included if this commit was to a specific branch in the repository.
LAYERCI_BRANCH is not included if this job is running due to an external pull request.
LAYERCI_JOB_ID always exists. It’s set to the ID of the current running job.
LAYERCI_PULL_REQUEST may or may not exist. It’s a link to the pull request that triggered this pipeline.
LAYERCI_REPO_NAME is the name of the repository. If the repository is at github.com/a/b, this would be “b”
LAYERCI_REPO_OWNER is the name of the owner of this repository. If the repository is at github.com/a/b, this would be “a”
LAYERCI_ORG_NAME is the name of the current organization. If the dashboard is at layerci.com/myorg, this would be “myorg”
LAYERCI_RUNNER_ID is the id of the current layerfile runner.
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 environment variable 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
WAIT [layerfile paths...]
WAIT instruction allows you to make one step require other steps to succeed before running.
It’s especially useful for conditional actions like executing notifications, deployment, and CI/CD.
Continuous deployment with WAIT
# at deploy/Layerfile FROM vm/ubuntu:18.04 # Wait for the layerfiles at /unit-tests/Layerfile and /acceptance-tests/Layerfile WAIT /unit-tests /acceptance-tests RUN ./notify-slack.sh RUN ./deploy.sh
Conditional deployment with WAIT and BUTTON
# at deploy/Layerfile FROM vm/ubuntu:18.04 # Wait for the layerfiles at /unit-tests/Layerfile and /acceptance-tests/Layerfile WAIT /unit-tests /acceptance-tests RUN ./notify-slack.sh BUTTON deploy? RUN ./deploy.sh
What the job view will look like with WAIT
- Notice that deploy only occurs after all of the other layerfiles have succeeded.
- This layerfile is available here
WORKDIR instruction changes the location 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.