Documentation

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

BUILD ENV

The BUILD ENV instruction tells the layerfile to rebuild when a variable changes.


Examples

  • Commonly used with $SUBDOMAIN to ensure each branch has the proper value:

Layerfile

        BUILD ENV SUBDOMAIN
        RUN echo "HOST=$SUBDOMAIN.mydomain.com" >> .env
        RUN docker-compose up -d

Possible values

SUBDOMAIN

SUBDOMAIN=my-branch

The SUBDOMAIN variable is often used to set the HOST variable for webservers.

It is a cleaned up version of the $GIT_BRANCH variable, acceptable for use in a URL.

  • feat/add-some-dashboard-pages becomes add-some-dashboard-pages

Common use is to set HOST=$SUBDOMAIN.demo.example.com


DEPLOYMENT_HOST

DEPLOYMENT_HOST=job-5.demo.example.com

The DEPLOYMENT_HOST variable is set if a deployment exists for your run.

It's often used to tell a webserver where it is being hosted.

If there are multiple deployments, a single one is returned.


CI

CI=true, IS_CI_MACHINE=true, CI_MACHINE=true, IN_CI_MACHINE=true, IN_CI=true

These CI variables are always true while running a Layerfile.


DEBIAN_FRONTEND

DEBIAN_FRONTEND=noninteractive

The DEBIAN_FRONTEND variable is always set to noninteractive in webapp.io. To change this behavior, use, e.g., ENV DEBIAN_FRONTEND=readline


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_SHORT_COMMIT

GIT_COMMIT=111122223333

GIT_COMMIT is the first 12 characters of running git rev-parse HEAD in the repository.


GIT_COMMIT_TITLE

GIT_COMMIT_TITLE="[improvement] do something"


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.

Note: Unavailable for use by BUILD ENV


WEBAPPIO

WEBAPPIO=true

WEBAPPIO is always true when running a Layerfile


GIT_BRANCH

GIT_BRANCH=staging

GIT_BRANCH is the branch which is checked out in this repository.


JOB_ID

JOB_ID=5

JOB_ID always exists. It's set to the ID of the current running job.


PULL_REQUEST_URL

PULL_REQUEST_URL=https://github.com/some/repo/pull_requests/5

PULL_REQUEST_URL may or may not exist. It's a link to the pull request that triggered this pipeline.


REPOSITORY_NAME

REPOSITORY_NAME=somerepo

REPOSITORY_NAME is the name of the repository. If the repository is at github.com/a/b, this would be "b"


REPOSITORY_OWNER

REPOSITORY_OWNER=repoowner

REPOSITORY_OWNER is the name of the owner of this repository. If the repository is at github.com/a/b, this would be "a"


ORGANIZATION_NAME

ORGANIZATION_NAME=myorg

ORGANIZATION_NAME is the name of the current organization. If the dashboard is at webapp.io/myorg, this would be "myorg"


RUNNER_ID

RUNNER_ID=main-layerfile

RUNNER_ID is the id of the current layerfile runner.


RETRY_INDEX

RETRY_INDEX=1

RETRY_INDEX is the current retry for the given runner (initially 1, then when retried once, 2, etc)


API_EXTRA

API_EXTRA=some data passed from API

API_EXTRA is optional data passed in when a run is started by the API.


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 webapp.io 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 webapp.io 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...] 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 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_HOST environment variable is available even before EXPOSE WEBSITE if you need to "bake" the path to the exposed website URL.

If the default 2 minute timeout is not sufficient for your application, use the following pattern to wait until the server is ready: expose website directive

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 webapp.io 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)

LABEL

LABEL [key=value..]

The LABEL directive allows users to control modify meta aspects of their runs

Layerfile

LABEL display_name=cool_layerfile_name

Possible values

display_name

LABEL display_name=testName

The display_name key allows the user to modify the display name in the runs dashboard

display name

status

LABEL status=merge or LABEL status=hidden

The status key allows the user control the behaviour of check notification within your pull request.

  • The merge status will cause webapp to summarize all runs resulting from the SPLIT directive

    status merge

  • The hidden status will cause webapp to hide the run status of the 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.

Secrets are useful for storing sensitive information. They can hold passwords, API keys, or other private credentials. For security reasons, it is good practice to not keep this information within source code. Managing private data using secrets allows easy authentication with other services on your behalf.

webapp.io has a secrets manager built into the platform. This makes entering and editing secrets as simple as 1, 2, 3:


Step 1: Navigate to the secrets tab in your webapp.io account. View of secrets page in webapp.io


Step 2: Click ‘NEW’ in the top right corner. Follow the prompts to choose a secret name, value, and destination repository. View of dialogue box prompting secret creation in webapp.io


Step 3: All done! View of created secret in webapp.io


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.

Who can create secrets?

Only owners of an organization's webapp.io account can create and edit secrets. Permissions can be edited in the members tab, which can be found in the settings dropdown menu. The members tab displays all users in an organization.

View of webapp.io, highlighting the members tab within the settings menu


Click on the name of a user to display their permissions. Only users with owner-level access can create secrets. An organization’s owner(s) can edit permissions for other users.

View of how permissions are visible below a member's name in webapp.io's members tab


SKIP REMAINING IF

SKIP REMAINING IF [KEY=VALUE]

The SKIP REMAINING IF instruction will cause remaining instructions in the Layerfile to be skipped if the condition is evaluated to true.

Multiple SKIP REMAINING IF instructions may be declared in one Layerfile.

Conditions may use any variable from BUILD ENV.

Conditions may use AND to group statements using logical AND.

Conditions may use != to evaluate statements are not true.

Examples

  • Use SKIP REMAINING IF GIT_BRANCH!=master to skip execution on any branch that is not master.
  • Use SKIP REMAINING IF GIT_BRANCH!=master AND REPOSITORY_NAME !=~ "web" would skip remaining actions if the branch is not master, and the repository name is not "web"
  • Use SKIP REMAINING IF GIT_COMMIT_TITLE =~ "\[skip tests\]" would skip remaining actions if the commit title contained "[skip tests]"
  • Use SKIP REMAINING IF GIT_BRANCH!=~^(master|dev)$ would skip remaining actions if the branch is anything besides master or dev

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.

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

Layerfile

    # 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

Layerfile

    # 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

Advanced workflow graph example


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.