Layerfiles can be composed into arbitrarily powerful workflows.
Consider these three Layerfiles:
1. Layerfile at (repo root)/Layerfile
2. Layerfile at (repo root)/web/Layerfile
3. Layerfile at (repo root)/web/tests/Layerfile
When commited to a repository, they will create the following execution graph, where each node is created by a layerfile:
Here, webapp.io has searched for files named 'Layerfile', discovered all three of these files, and linked them based on their parents (look at the FROM lines)
Ramifications of inheritance using 'FROM'
Beyond just ensuring that actions occur sequentially,
FROM also shares files and processes between parents and children.
Layerfile 1 installs
python3 here, and installs (and starts) a postgres instance, which means that layerfiles #2 and #3 both get a distinct copy of the database.
Layerfiles can set up a migrated database in 5 seconds
It's common to use webapp.io to run QA processes against a full stack including open-source databases.
Consider the following Layerfile:
There's a lot to unpack here, but there are a few important takeaways from this example:
- You can install docker & docker-compose and efficiently create containers within a Layerfile
- RUN REPEATABLE lets you reuse built images & volumes from the last time this pipeline ran
- Webapp.io will create a snapshot with everything created so that you can avoid re-building, re-creating, and re-migrating database data every time.
As before, other Layerfiles can extend from this one to run e2e tests or create a full-stack demo environment with
Logging in to Docker
Webapp.io creates entire VMs as easily as Dockerfiles, so it's common for our users to use Docker or docker-compose within webapp.io.
Docker hub rate limits requests made by unauthenticated users, so it's imperative to create a docker hub account and log in to it to avoid failing tests.
The simplest way is to combine SECRET ENV with
- Add a new secret with key "DOCKER_LOGIN" in the secrets pane (the lock icon to the left)
- Make the value for that secret be your docker hub login
- Press the "Save" button to save the new secret.
Change your Layerfile and add the following lines after installing Docker:
Full example of Layerfile that installs & runs a docker container, then creates a persistent staging link from it:
EXPOSE WEBSITE allows you to whitelabel staging servers on your own domain.
example.com could route
$branch.demo.example.com to the latest commit on the branch
$branch by adding a single DNS record
CNAME *.demo demotarget.webapp.io
How to set up deployments:
Using webapp.io/dashboard, navigate to your customs domains.
Add the specific domain that you want everything to be exposed under. In the example below, we are adding cidemolocal.co. A CNAME record will be provided.
Add the CNAME record in your DNS hosting provider (ex: Cloudflare, godaddy, etc). Creating a new record can usually be done within the DNS settings. Once this is done, DNS IS SET UP can be found next to the new domain.
Next, click ‘Add’ to create a new deployment rule. Fill in the appropriate fields.
The deployment is now listed under ‘Subdomain creation rules’
Use-cases for deployments
- Host your staging servers on your own domain to make them easier to find.
staging.demo.example.comcould be bookmarked by a QA person to see the latest commit on the
- Run your backend and frontend in different Layerfiles and combine them behind one host (
- Allow multiple subdomains to the same Layerfile in case your application does host based routing (e.g.,
- Private Deployments which prevents people from outside your organizations from viewing your site
By default, EXPOSE WEBSITE creates staging servers are at
https://(uuid).cidemo.co, where the uuid is unique for every Layerfile. The deployments page lets you customize this by adding a column to its table and adding a
CNAME record on a domain you control.
Subdomains within deployments
Subdomains are preconfigured in webapp.io. Your webserver always sees the host as localhost. If you don’t want that to be the case, please contact support.
For example, say you have a deployment at deployment.demo.webapp.io. If you then go to hello.deployment.demo.webapp.io, it will go to the same deployment. Similarly, if you navigate to greetings.deployment.demo.webapp.io, it will also direct to deployment.demo.webapp.io. This happens by default.
Two layerfile polyrepo example
- In this example, the backend and frontend are separate repositories, and we want to use the latest version of the frontend whenever the backend is built.
Create a single deployment from $branch.demo.yourdomain.com to the backend repository, leave the branch field empty
Create a CNAME record from *.demo to demotarget.webapp.io
Push the layerfiles above to a branch, say, "main"
Visit main.demo.yourdomain.com - notice that requests to main.demo.yourdomain.com/api/hello go to the backend layerfile, while requests to main.demo.yourdomain.com go to the frontend layerfile (within the backend domain)
OAuth (logging in with external sites)
OAuth is what lets you log in to a service with an existing Google or Facebook account.
Webapp.io customers often need to set a redirect target from their "test app" on an external service to allow logging in to their own accounts.
For this use case, we've created the
layer-oauth-target.cidemo.co endpoint, and the flow looks like this:
- User visits
- User clicks "log in with Google"
- User is redirected to a Google login page for a test application
- The "redirect URI" for that login page is "layer-oauth-target.cidemo.co", so the user is sent to
layer-oauth-target.cidemo.coreads a cookie to see which cidemo site the user was last on, so the user is redirected back to
- The application can now read the code and log the user in as usual.
Combining with white-labeled sites (routing)
The same can be done for layer-oauth-target.demo.example.com, in the case where a route with
To install Yarn, your Layerfile will include something like this:
Information on optimizing and troubleshooting Yarn in webapp.io can be found here.
Groups and Permissions
Permissions allow for the management of read/write access to various features of webapp.io. Permissions can be managed for the members of your organization through the members section of organization settings.
Permissions are a hierarchy of keywords separated by periods(
.) using star(
*) as a wildcard.
settings.billing.tier equates to the organziation billing tier setting permission.
settings.* equates to all organziation settings permissions.
* equates to all permissions.
Access to view the organization dashboard (recent commits, custom domains, new installations, organization settings) is managed thorugh the
Access to install webapp.io on new repositories is managed through the
Access to perform actions on repositories is managed the the
Access to perform actions on a specific repository is managed through the
repo.<reposirory name> keyword. Repository names are lower cased and have both spaces and periods replaced with dashes(
-). For example, a repository
helloWorld/my first.program is normalized to
Access to the debugging terminal of a staging server is managed through the
repo.<reposirory name>.stagingterm keyword.
Repository controls are managed through the
controls keyword with the following permissions:
repo.<reposirory name>.controls.retrythe ability to retry a run
repo.<reposirory name>.controls.cancelthe ability to cancel a run
repo.<reposirory name>.buttonthe ability to click buttons defined in Layerfiles
Access to read and write secrets is managed though the
Access to read and write organization settings are managed through the
Organization membership management has the following permissions:
setttings.members.rolesalter member roles
setttings.members.usersalter organization's users
setttings.members.users.inviteinvite users to organization
Organization billing settings have the following permissions:
settings.billing.tiermanage organization billing tier
settings.billing.paymentmanage organization payment method
An organization has two role groups by default, owners and members. Owners have read/write access to all parts of the organization, members have a subset. Members start with the default permissions of:
Permissions can be granted to role groups in the members section of organization settings.
To add additional role groups contact support at [email protected].