.. Configuration:

Configuration
=============

This chapter details how a running VS service can be configured. And what steps
are necessary to deploy the configuration.

Concepts
--------
This section explains the various kinds of configuration items and where to
apply them.

Docker Compose Settings
  These configurations are altering the behavior of the stack itself and its
  contained services. A complete reference of the configuration file structure
  can be found in `Docker Compose documentation
  <https://docs.docker.com/compose/compose-file/>`_.

Environment Variables
  These variables are passed to their respective containers environment and
  change the behavior of certain functionality. They can be declared in the
  Docker Compose configuration file directly, but typically they are bundled by
  field of interest and then placed into ``.env`` files and then passed to the
  containers. So for example, there will be a ``<stack-name>_obs.env`` file
  to store the access parameters for the object storage.
  All those files are placed in the ``env/`` directory in the instances
  directory.

  Environment variables and ``.env`` files are passed to the services via the
  ``docker-compose.yml`` directives. The following example shows how to pass
  ``.env`` files and direct environment variables:

  .. code-block:: yaml

    services:
      # ....
      registrar:
        env_file:
          - env/stack.env
          - env/stack_db.env
          - env/stack_obs.env
          - env/stack_redis.env
        environment:
          INSTANCE_ID: "prism-view-server_registrar"
          INSTALL_DIR: "/var/www/pvs/dev/"
          SCALEFACTOR: "1"
          IN_MEMORY: "false"
          INIT_SCRIPTS: "/configure.sh /init-db.sh"
        # ...


  The following ``.env`` files are typically used:

    * ``<stack-name>.env``: The general ``.env`` file used for all services
    * ``<stack-name>_db.env``: The database access credentials, for all services
      interacting with the database.
    * ``<stack-name>_django.env``: This env files defines the credentials for the
      django admin user to be used with the admin GUI.
    * ``<stack-name>_obs.env``: This contains access parameters for the object
      storage(s).
    * ``<stack-name>_preprocessor.env``: Preprocessor related environment
      variables
    * ``<stack-name>_redis.env``: Redis access credentials and queue names

  .. Usually, it is not possible to override the values in running containers.
  .. So whenever such a value is changed, the stack has to be re-deployed in
  .. order to push the changes to the services.

Configuration Files
  Such files are passed to the containers in a similar way as environment
  variables, but usually contain more settings at once and are placed at a
  specific path in the container at runtime.

  Configuration files are passed into the containers using the ``configs``
  section of the ``docker-compose.yaml`` file. The following example shows how
  such a configuration file is defined and the used in a service:


  .. code-block:: yaml

    # ...
    configs:
      my-config:
        file: ./config/example.cfg
    # ...
    services:
      myservice:
        # ...
        configs:
        - source: my-config
          target: /example.cfg


  The following configuration files are used throughout the VS:

    * ``<stack-name>_init-db.sh``: This shell script files purpose is to set up
      the EOxServer instance used by both the renderer and registrar.
    * ``<stack-name>_index-dev.html``/``<stack-name>_index-ops.html``: The
      clients main HTML page, containing various client settings. The ``dev`` one
      is used for development only, whereas the ``ops`` one is used for operational
      deployment.
    * ``<stack-name>_mapcache-dev.xml``/``<stack-name>_mapcache-ops.xml``: The
      configuration file for MapCache, the software powering the cache service.
      Similarly to the client configuration files, the ``dev`` and ``ops`` files
      used for development and operational usage respectively. Further
      documentation can be found at `the official site
      <https://mapserver.org/mapcache/config.html>`_.




https://gdal.org/user/configoptions.html