.. _introduction:

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

This guide will detail 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, a
knowledge of Docker and Docker Swarm is required.

## Components

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

 - Ingestor (ingestor)
 - Preprocessor (preprocessor)
 - Registrator (core)
 - Renderer (core)
 - Cache (cache)
 - Seeder (cache)
 - Client (client)
 - Database (postgis)
 - Redis (redis)
 - Reverse Proxy (traefik)

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

Images
------

The software is distributed as Docker images, which can be instantiated
and run in their intended role. Some images are hosted on the docker hub,
the official and default repository for Docker images. Other images reside
on the gitlab.eox.at repository. Images from the official repository
are only identified via their name, whereas images from the eox repository
conventionally use the full URL, including the domain name.

 - 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 will 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 enpoints are configured. Usually
    this is associated with additional backdrop and overlay layers.
 - preprocessor.yml: This file configures the preprocessing process.
 - mapcache.xml: This file defines the input sources of the cache and its
    published layers.
 - init-db.sh: This file sets up the registrator and renderer side of the VS,

Setup
-----

In order to help with the initial setup of a VS, the ``pvs_starter`` package
allows to quickly establish the required structure of configuration files.

It is run from a configuration file and sets up