intro.rst

.. _introduction:

Introduction
============

This guide details the operation of a View Server and all of its
components.

Since the View Server is a Docker based software and all of its components are
distributed and executed in context of Docker images and containers, basic
knowledge of Docker and Docker Swarm is a prerequisite.

Components
----------

.. figure:: images/architecture.png

The View Server consists of the following service components (with their
respective Docker image in parenthesis):

.. - Ingestor (ingestor) TODO: re-add this

 - Reverse Proxy (traefik)
 - Preprocessor (preprocessor)
 - Registrar (core)
 - Renderer (core)
 - Cache (cache)
 - Seeder (cache)
 - Client (client)
 - Database (postgis)
 - Queue Manager (redis)
 - Reverse Proxy (traefik)

These services are bundled and managed together in a Docker Swarm via
Docker Compose configuration files.

Docker Images
-------------

The software is distributed as Docker images, which can be instantiated
and run in their intended role. Some images are hosted on
`docker hub <https://hub.docker.com/>`_,
the official and default repository for Docker images. Other images reside
on an `EOX hosted registry <gitlab.eox.at>`_. Images from the official registry
are only identified via their name, whereas images from the EOX registry
conventionally use the full URL, including the domain name. Below is a list of
the used images:

 - mdillon/postgis:10
 - redis
 - traefik:2.1
 - registry.gitlab.eox.at/esa/prism/vs/pvs_core:latest
 - registry.gitlab.eox.at/esa/prism/vs/pvs_cache:latest
 - registry.gitlab.eox.at/esa/prism/vs/pvs_preprocessor:latest
 - registry.gitlab.eox.at/esa/prism/vs/pvs_client:latest

Configuration Files
-------------------

The following configuration files impact the behavior of the View Server:

 - `index.html`: This is the main file to configure the client. In this file,
   the viewing layer, search and download endpoints are configured. Usually
   this is associated with additional backdrop and overlay layers.
 - `preprocessor.yml`: This file configures the preprocessing steps.
 - `mapcache.xml`: This file defines the input sources of the cache and its
   published layers.
 - `init-db.sh`: This file sets up the registrar and renderer side of the VS.

Initialization and Setup
------------------------

In order to help with the initial setup of a VS, the ``pvs_starter`` package
described in the section :ref:`initialization` allows to quickly establish the
required structure of configuration files.

The section :ref:`setup` describes how to deploy a Docker Swarm stack using the
configuration files generated in the initialization step.