Request access

Intro

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

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.

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

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

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

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

ENV

ENV [key=value...] or BUILD ENV [key...]

The ENV instruction persistently sets environment variables in this Layerfile

Examples

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.

Examples

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

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

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

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:

View of secrets page in webapp.io

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

View of dialogue box prompting secret creation 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 created secret in webapp.io

Step 3: All done!

Examples

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

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

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

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

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

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

Advanced workflow graph example

WORKDIR

WORKDIR [directory]

The WORKDIR instruction changes the location from which files are resolved in the runner.

Examples


Edit these docs