Intro
This page contains a reference for each directive which can appear in a Layerfile.
For a more introductory reference, see the documentation home
CACHE
CACHE [cached directories...]
The CACHE
instruction makes specific files/directories be shared across runs, almost always as a performance improvement.
See the tuning performance documentation for more details.
Examples
- Use
CACHE /var/cache/apt
to speed upRUN apt-get update
- Use
CACHE ~/.cache/go-build
to speed upRUN go install
- Use
CACHE ~/.npm ~/.next/cache ~/.yarn/cache
to speed upnpm install
andyarn install
Each LayerCI account gets a fixed amount of cache storage, and we periodically delete old or inactive caches.
CHECKPOINT
CHECKPOINT (name)
or CHECKPOINT disabled
The 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.
Examples
- Use
CHECKPOINT disabled
to disable checkpointing from that point onwards - Use
CHECKPOINT deploy
to create a checkpoint named “deploy”, which can be triggered as a lambda from our api - Use
CHECKPOINT
to expliticly take a checkpoint at a specific point (which happens automatically by default), or re-enable checkpointing afterCHECKPOINT disabled
See the tuning performance documentation for more details.
COPY
COPY [files...] [destination]
The 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)
Examples
- Use
COPY . .
to copy the directory containing the Layerfile to the current working directory (or /root if WORKDIR has not been used) - Use
COPY package.json yarn.lock ./
to copy those two files to the current directory. - Use
COPY / /root
to copy the entire repository to /root in the runner.
ENV
ENV [key=value...]
or BUILD ENV [key...]
The ENV
instruction persistently sets environment variables in this Layerfile
Examples
ENV PATH=$GOPATH/bin:$PATH
adds$GOPATH/bin
to the existing path.ENV CI=hello
sets the variable$CI
to the valuehello
.
Build Environment variables
Some environment variables are dynamically set for the run and can be used in RUN
directives.
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
CI=true
, IS_CI_MACHINE=true
, CI_MACHINE=true
, IN_CI_MACHINE=true
, IN_CI=true
These CI
variables are always true
in LayerCI.
GIT_TAG
GIT_TAG=v1.0.0
GIT_TAG
is the result of running git describe --always
in the repository.
GIT_COMMIT
GIT_COMMIT=111122223333444455556666777788889999aaaa
GIT_COMMIT
is the result of running git rev-parse HEAD in the repository.
GIT_CLONE_USER
GIT_CLONE_USER=x-access-token:<token>
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
EXPOSE_WEBSITE_HOST=(uuid).cidemo.co
EXPOSE_WEBSITE_HOST
is the hostname exposed by EXPOSE WEBSITE
It’s often used to link a frontend with a backend when running both with EXPOSE WEBSITE
and RUN BACKGROUND
You can even reference this before EXPOSE WEBSITE
is ever used, but the URL is only live after the run passes.
LAYERCI
LAYERCI=true
LAYERCI
is always true
in LayerCI test runs.
LAYERCI_BRANCH
LAYERCI_BRANCH=staging
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
LAYERCI_JOB_ID=5
LAYERCI_JOB_ID
always exists. It’s set to the ID of the current running job.
LAYERCI_PULL_REQUEST
LAYERCI_PULL_REQUEST=https://github.com/some/repo/pull_requests/5
LAYERCI_PULL_REQUEST
may or may not exist. It’s a link to the pull request that triggered this pipeline.
LAYERCI_REPO_NAME
LAYERCI_REPO_NAME=somerepo
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
LAYERCI_REPO_OWNER=repoowner
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
LAYERCI_ORG_NAME=myorg
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
LAYERCI_RUNNER_ID=main-layerfile
LAYERCI_RUNNER_ID
is the id of the current layerfile runner.
EXPOSE WEBSITE
EXPOSE WEBSITE [location on runner] (path) (rewrite path)
The 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.
Additionally, the EXPOSE_WEBSITE_URL
environment variable is available even before EXPOSE WEBSITE
if you need to “bake” the path to the exposed website URL.
Examples
- Use
EXPOSE WEBSITE localhost:80
to expose the local webserver at port 80 - Combine
EXPOSE WEBSITE localhost:80 /api
withEXPOSE 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
FROM [source]
The 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.
Examples
- Use
FROM vm/ubuntu:18.04
to use ubuntu:18.04 as the base. - Use
FROM ../base
to inherit from the file at../base/Layerfile
relative to the current Layerfile - Use
FROM /base
to inherit from the file at(repo root)/base/Layerfile)
MEMORY
MEMORY [number](K|M|G)
The 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.
Examples
- Use
MEMORY 2G
to ensure at least 2 gigabytes of memory are available.
RUN
RUN (BACKGROUND|REPEATABLE) [command ...]
The 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.
Examples
RUN echo hello
prints “hello” to the terminalRUN BACKGROUND python3 -m http.server
runpython3 -m http.server
persistently in the background.RUN REPEATABLE docker build -t hello
is a performance optimization, see tuning performance
SECRET ENV
SECRET ENV [secret name...]
The SECRET ENV
instruction adds values from secrets to the runner’s environment.
It’s useful for authenticating LayerCI with other services on your behalf.
Examples
- Use
SECRET ENV ENV_FILE
to expose your dotfile env.env
and then useRUN echo "$ENV_FILE" | base64 -d > ~/.env
to decode the uploaded env file to the specific location.
SETUP FILE
SETUP FILE [file ...]
The SETUP FILE
instruction causes the contents of the given file to be sourced before every RUN
command.
This is equivalent to copy/pasting the contents of the file into the terminal before every RUN
command.
A common use case is to set a lot of environment variables using an “.env” file, or specifying a custom “.bashrc” file.
Examples
- Use
SETUP FILE .env
to runsource (repository root)/.env
before everyRUN
command.
SPLIT
SPLIT [n]
The 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
and SPLIT_NUM
environment variables automatically set.
The former will be the index of the runner, and the latter will be the number of copies.
Examples
- Use
SPLIT 3
and three copies of the runner will haveENV SPLIT=0 SPLIT_NUM=3
andENV SPLIT=1 SPLIT_NUM=3
and so on.
USER
USER [username]
The USER
instruction allows you to run as a non-root user.
The user is added to the root
group to circumvent permission denied errors.
Examples
- Use
USER www
to run the remaining commands as thewww
user.
WAIT
WAIT [layerfile paths...]
The 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.
Examples
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
WORKDIR [directory]
The WORKDIR
instruction changes the location from which files are resolved in the runner.
Examples
- Use
WORKDIR /tmp
to run commands in the/tmp
directory within the runner. - Use
WORKDIR hello
to run commands in the(workdir)/hello
directory within the runner.