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.
Softrebuilding: Doing a partial rebuild, only recreating unlocked services.

stateDiagram-v2
    Empty --> creating
    creating --> created
    creating --> failed
    created --> Empty
    created --> queued

    failed --> Empty 

    queued --> building
    building --> failed
    building --> cancelled
    building --> built

    built --> Empty
    built --> Softrebuilding
    cancelled --> Empty

    Softrebuilding --> built
    Softrebuilding --> failed

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.

You can check the full Qaackfile specification.

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 Qaackfile mode).

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¶

Warning

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. :::

Configure¶

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

Warning

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

Saving the environment¶

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.

Reusing a environment¶

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.

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.

Soft rebuilding¶

Warning

Locked services will be stopped, consider this for non-saved data.

This feature allows to partially rebuild a environment and preserve the content of serivces between builds.

A typical use case is when you want to rebuild the service that has the code but not the database.

It relies on locking services. Services can be locked and unlocked from the panel and with the API. When a service is locked, it will be preserved between builds. When a service is unlocked, it will be recreated in the next build. There is not any special trigger for a soft rebuild, just the normal rebuild process. In the case that at least one service is locked, the environment will be marked as Softrebuilding when rebuilding.

A environment with locked services cannot be deleted, only rebuilt. It does not affect to clones.

Info

Unlocked services will follow the reusable environment workflow as usual.

In order to avoid data-loss, expiration time for environments with locked services is disabled.

Note

Environment TTL is disabled once any service is locked. The only way to set a TTL after that is to delete and recreate the environment.

Warning

Environment variables of the locked services are not updated. Information like TTL may be outdated.

Behavior on errors¶

When rebuilding, the Qaackfile is updated as usual and the not locked services recreated. In the case of any error, the locked services will be preserved and the environment will be marked as Failed. The environment can be rebuilt if its failed.

Tolerations to changes¶

No build command nor any code checkout is executed in the locked sevices. They are completely ignored.

Changes on other services will be tolerated. However, the deletion of changing the image of any service locked will lead to a failed environment.

To allow to integrate the Qaackfile commands with this feature, a environment variable is injected to unlocked services when recreating them. This variable is QCK_SOFT_REBUILD and its value is true. Otherwise it does not appear.

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.

Domain matching¶

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)

Aliases¶

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

Prefefined 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 environment variables.

Custom defined variables¶

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)

Variable visibility¶

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.