Layerfile reference

This page contains a reference for each directive which can appear in a Layerfile.

For a more introductory reference, see the documentation home

ARTIFACT

ARTIFACT [PRIVATE/PUBLIC] [file/directory...]

The ARTIFACT instruction allows you to download files from the virtual machine running the test.

Examples

  • Use ARTIFACT PUBLIC built/file.jar to create a download link to the built jar file
  • Use ARTIFACT PRIVATE /var/log/buildlog to create a download link to the logs for the run

BUTTON

BUTTON [message...]

The BUTTON instruction allows you to block the progress of a run until the button is pressed.

Examples

  • Commonly used for deployment: BUTTON would you like to deploy? followed by RUN ./deploy.sh would not deploy unless the button was pressed.

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 up RUN apt-get update
  • Use CACHE ~/.cache/go-build to speed up RUN go install
  • Use CACHE ~/.npm ~/.next/cache ~/.yarn/cache to speed up npm install and yarn 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 after CHECKPOINT 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...]

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 value hello.

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 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 with 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

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 terminal
  • RUN BACKGROUND python3 -m http.server run python3 -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 use RUN 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 run source (repository root)/.env before every RUN 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 have ENV SPLIT=0 SPLIT_NUM=3 and ENV 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 the www user.

WORKDIR

WORKDIR [directory]

The WORKDIR instruction changes the locatation 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.