Environment¶

Lifecycle¶

Environments have a state, which are:

Empty: Nothing has been created, just Qaack is aware of the existence of the git reference associated with the environment and provides it to being created.
Creating: Temporal state, the services and being created without checkout code or run build commands. This status can not be stopped.
Created: The environment is running and accessible through the webproxy but not code and not build commands has been executed.
Queued: The environment is waiting to get a slot in the build queue.
Building: The build commands are being executed. This can be cancelled.
Cancelled: The build process has been cancelled without any further action (no clean up)
Failed: The build process didn’t complete successfully
Built: The build process has completed without errors.

Qaackfile (environment config file)¶

The Qaackfile is the file that describes how a environment has to be created and built. It defines things such as services to create, aliases to access the container, tests, quick actions and variables.

For a complete reference of the Qaackfile click here.

By default, Qaack will look for the Qaackfile in the path qaack/qaack.yml of the git reference of the environment, but it can configured to fetch from the repository site (check this).

In addition, the Qaackfile support templating.

Templating¶

The templating of the Qaackfile occurs before the creation of the environment. In consequence, the available variables value will be the ones at the moment of the creation of the environment.

For a complete reference of the available variables click here.

You can use template variables everywhere, for example to define your iamge to use, or append services depending of the repository type.

services:
  {{ eq .Repository.Type "gitlab" }}
    my_service
        image: registry.gitlab.com/{{ RepositoryParam "GitlabProjectGroup" }}/{{ RepositoryParam "GitlabProjectName" }}:{{ .Environment.Ref.Hash }}
        commands:
          ...
  {{ end }}

Reusables¶

Attention

This feature is under development, changes are expected

Reusable environments is a very useful feature that allows to save a environment at a arbitraty step and reuse later in other environment.

This feature has been desinged and implemented with the goal of save resources.

Tip

For example, in the case of a NodeJS project, you can save a environment after run npm ci and later add npm i. This will be faster as the dependencies are already installed.

Tip

For example, in the case of a Composer based project, you can save a environment after run composer install so next time it runs on a new environment it will just install the missing dependencies.

Tip

In any other case, if your environment have some OS level dependencies, like packages, libraries or whatever, you can install them once in the reusable environment.

Also, new environment will save space as they reuse a common image of dependencies.

Configuration about when to create a reusable environment and later where to reuse this is specified in the Qaack file.

There are two directives in the qaack file:

make_reusable: for specify when to save
reuse: to specify which reusable environment choose

Caution

If there are differences in the configuration between saved environment and the reusing one, it could result in a unexpected beahviour. Qaack will reuse if all the services matches and the step specified to save exists.

It wont check if new commands have been included, deleted or reorganized

In the build process, after every step on every service is checked if there is any reusable environment configuration directive that matches the current position of the build process.

In the case that any config matches, then all the services are paused, then all saved and then unpaused.

The reuse label will be checked before start the create process. The reusable environment will be used a the image to pull instead of the specified by the service config.

Later, when building, Qaack will skip all the steps and services until reach the step specified for the reusable environment.

Reusing environment files will be placed over the saved ones, without any file merge mechanism.

Code checkout¶

Code can be automatically copied to every service if the checkout option is set to true in the Qaackfile.

The code is transfered to the service using git command.

The command executed is mainly git clone when a environment is not using any reusable environment.

In the case of a reusable environment, git fetch, git checkout and git pull is used instead.

When the git reference using is a Merge or Pull request, then the git command git merge is used.

Tip

To avoid undesired commits, push origin is set to a non valid url.

Clones¶

This featue allows you to create new environments from the same git reference.

Cloned environments are independent but they behave the same in cases like reusable environments.

They are build from scrath without any reusability from the “original” one.

Its controlled using this endpoint (called spawn).

On deletion, environments will be completly deleted (that is, not setting to empty state) until its the last one with the same git reference.

Time to life (TTL)¶

All environment can have a expiration date, this is when the environment will be deleted automatically. The title to life is expressed in minutes

The lifetime starts to count since the creation of the environment.

Once a environment has been created, its not possible to modify it.

The time to life as well as the expiration date can be known inside the container as a environment variable.

Webproxy¶

Qaack handles incoming requests to services internally and integrates the requests with the environment management. This means that when a environment doest exists or its not ready, Qaack sends a information page with the current state of the environment.

The selection of the target environment and service (optionally) is based on the subdomain or http header qaack-env-id.

In addition, you can specify a url when a environment is not found using a query parameter called qck_wp_redirect_url.

For domains without subdomain, it servers the API (For example qaack.cloud)
Foo domains with subdomain exactly equal to panel it will serve the API (For example panel.qaack.cloud)
For the rest of domains, it will find a environment id that matches the subdomain or the characters after the last - if any. (For example, nnnnnn.qaack.cloud and label-nnnnnn.qaack.cloud will find a environment with nnnnnnn id)

Is possible to specify custom aliases for environments on the Qaackfile. These aliases are integrated with the qaackfile and the user interface. Check qaack file reference for more aliases info.

Environments will be available with addresses like:

[envid].qaack.cloud
[alias]-[envid].qaack.cloud

And for specific services it will be:

serv-[serv_name]-[envid].qaack.cloud
[alias]-[serv_name]-[envid].qaack.cloud

Environment variables¶

Warning

To effectively apply custom variable changes is needed to recreate the environment

There are two kind of variables:

Predefined variables
Custom variables

These variables are automatically added by Qaack and their purpose is provide more details of the system (like exposed URL, service, environment and repository details).

Look at this table to more details check the predefined variables specifications

These variables are defined by the user.

Variables have a visibility settings, allowing the user to enable it on runtime and/or build time.

There are several layers of variables:

Config file (per service)
Config file (global)
Repository
Group

The lower the layer its, the higher precedence it has. ( This is, config file variable overrides group variables)

Variables can be available only under certain circunstances. The options are:

Always: This means that the variable is available in all cases (build and runtime)
Buildtime: This means the variable is available only during the build process.