.. highlight:: yaml

.. _process_config:

==============
Process Config
==============


This config resides in ``/etc/lithos/processes/NAME.yaml`` (by default).
Where ``NAME`` is the name of a sandbox.

It mainly contains three things:

* ``image`` the process is run from
* ``config`` file name inside the image that specifies command-line and other
  process execution parameters
* number ``instances`` of the process to run

For example::

    django:
        image: django.v3.5.7
        config: /config/worker_process.yaml
        instances: 3

    redis:
        image: redix.v1
        config: /config/redis.yaml
        instances: 1

This will start three python ``django`` worker processes and one redis.

.. hint:: Usually this config is generated by some tool like ansible_ or
   confd_.

There is also a way to create **ad-hoc** commands. For example::

    manage:
        kind: Command
        image: django.v3.5.7
        config: /config/manage_py.yaml

This will allow to start a ``manage.py`` command with::

    $ lithos_cmd SANDBOX_NAME manage syncdb

This runs command in the same sandbox like the worker process itself but
the command is actually attached to current shell. The commands may be freely
mixed with ``Daemon`` items (which is default ``kind``) in same config. The
only limitation is that names must not be duplicated

The ``Command`` is occasionally useful, but should be used with care. To start
a command you need root privileges on host system, so it's only useful for
SysOp tasks or **may be** for cron tasks but not for normal operation of
application.

Options
=======

.. popt:: instances

   Number of instances to run

.. popt:: image

   Identifier of the image to run container from

.. popt:: config

   Configuration file name (absolute name in container) to run

.. popt:: ip-addresses

   A list of ip addresses if :opt:`bridged-network` is enforced in sandbox.
   Note the number of items in this list must match :popt:`instances` value.

.. popt:: variables

   A mapping of `variable: value` for variables that can be used in process
   config.

.. popt:: extra-secrets-namespaces

   Additional secrets namespaces allowed for this specific project. In
   addition to :opt:`secrets-namespaces`. See :ref:`encrypted-vars` for
   more info.

.. _process_variables:

Variables
=========

You can also add variables for specific config:

For example::

    django:
        image: django.v3.5.7
        config: /config/worker_process.yaml
        variables:
          tcp_port: 10001
        instances: 3

Only variables that are **declared** in :ref:`container config
<container_variables>` can be substituted. Extra variables are ignored. If
there is a declared variable but it's not present in process config, it doesn't
pass configuration check.

.. _ansible: http://www.ansible.com/
.. _confd: https://github.com/kelseyhightower/confd