This page contains a reference for each directive which can appear in a Layerfile.
For a more introductory reference, see the documentation home
The BUILD ENV instruction
BUILD ENV instruction tells the layerfile to rebuild when a variable changes.
- Commonly used with
$SUBDOMAINto ensure each branch has the proper value:
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.
Common use is to set
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 variables are always
true while running a Layerfile.
DEBIAN_FRONTEND variable is always set to
noninteractive in webapp.io.
To change this behavior, use, e.g.,
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_COMMIT is the first 12 characters of running
git rev-parse HEAD in the repository.
GIT_COMMIT_TITLE="[improvement] do something"
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.
Note: Unavailable for use by BUILD ENV
WEBAPPIO is always
true when running a Layerfile
GIT_BRANCH is the branch which is checked out in this repository.
JOB_ID always exists. It's set to the ID of the current running job.
PULL_REQUEST_URL may or may not exist. It's a link to the pull request that triggered this pipeline.
REPOSITORY_NAME is the name of the repository. If the repository is at github.com/a/b, this would be "b"
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 is the name of the current organization. If the dashboard is at webapp.io/myorg, this would be "myorg"
RUNNER_ID is the id of the current layerfile runner.
RETRY_INDEX is the current retry for the given runner (initially 1, then when retried once, 2, etc)
API_EXTRA=some data passed from API
API_EXTRA is optional data passed in when a run is started by the API.
The BUTTON instruction
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.
The CACHE instruction
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 webapp.io account gets a fixed amount of cache storage, and we periodically delete old or inactive caches.
The CHECKPOINT instruction
CHECKPOINT (name) or
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.
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.
The COPY instruction
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.
The ENV instruction
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
The EXPOSE WEBSITE instruction
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_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 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.
EXPOSE WEBSITE localhost:80 /cypress$SPLITafter a
SPLIT 5directive to make each split have a unique path (e.g.,
The FROM instruction
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.
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
The LABEL instruction
LABEL directive allows users to control modify meta aspects of their runs
display_name key allows the user to modify the display name in the runs dashboard
LABEL status=merge or LABEL status=hidden
status key allows the user control the behaviour of check notification within
your pull request.
mergestatus will cause webapp to summarize all runs resulting from the SPLIT directive
hiddenstatus will cause webapp to hide the run status of the Layerfile
The MEMORY instruction
MEMORY instruction allows you to specify how much memory your environment uses.
This directive must always go at the top of a Layerfile.
If used in conjunction with
FROM /base-image, the parent Layerfile must be the one which specifies
MEMORY, otherwise children might have to re-run steps from the parent Layerfile.
MEMORY 2Gto ensure at least 2 gigabytes of memory are available.
The RUN instruction
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
The SECRET ENV instruction
SECRET ENV [secret name...]
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.
Step 2: Click ‘NEW’ in the top right corner. Follow the prompts to choose a secret name, value, and destination repository.
Step 3: All done!
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.
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.
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.
The SETUP FILE instruction
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 setup-script.sh to run
source setup-script.sh before every
The SKIP REMAINING IF instruction
SKIP REMAINING IF [KEY=VALUE]
SKIP REMAINING IF instruction will cause remaining instructions in the Layerfile to be skipped if the condition is evaluated to true.
SKIP REMAINING IF instructions may be declared in one Layerfile.
Conditions may use any variable from
Conditions may use
AND to group statements using logical AND.
Conditions may use
!= to evaluate statements are not true.
SKIP REMAINING IF GIT_BRANCH!=masterto skip execution on any branch that is not master.
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"
SKIP REMAINING IF GIT_COMMIT_TITLE =~ "\[skip tests\]"would skip remaining actions if the commit title contained "[skip tests]"
SKIP REMAINING IF GIT_BRANCH!=~^(master|dev)$would skip remaining actions if the branch is anything besides
The SPLIT instruction
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.
The USER instruction
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
The WAIT instruction
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
Conditional deployment with WAIT and BUTTON
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
The WORKDIR instruction
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.