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 :ref:`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 :ref:`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 :ref:`here`. You can use template variables everywhere, for example to define your iamge to use, or append services depending of the repository type. .. code-block:: yaml 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. 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: - :ref:`make_reusable`: for specify when to save - :ref:`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** 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 :ref:`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 :ref:`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``. 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 :ref:`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 ===================== .. _custom-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 :ref:`predefined variables specifications` 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: 1. Config file (per service) 2. Config file (global) 3. Repository 4. 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. -----