.. _introduction:

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

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

View Server (VS) is a Docker-based software and all of its components are
distributed and executed in the context of Docker images, containers, and Helm charts.
Basic knowledge of Docker and either Docker Swarm or Helm and Kubernetes is a prerequisite.

Components
----------

.. figure:: images/architecture.*
   :alt: View Server Architecture

   *View Server Architecture*

Individual components of VS are 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 <https://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.

VS software brings together all the components in their latest versions in the 
default `vs-deployment` helm chart which can be found in 
`EOX public charts repository <https://charts-public.hub.eox.at/api/charts/vs>`_
or when needed to be cloned locally from
`EOX Gitlab repository <https://gitlab.eox.at/vs/vs-deployment>`_.

VS consists of the following service components (with their respective Docker image in parentheses):

- Web Client (`registry.gitlab.eox.at/vs/vs/client <https://gitlab.eox.at/vs/vs/container_registry/378>`_)
- Cache (`registry.gitlab.eox.at/vs/vs/cache <https://gitlab.eox.at/vs/vs/container_registry/393>`_)
- Renderer (`registry.gitlab.eox.at/vs/vs/core <https://gitlab.eox.at/vs/vs/container_registry/387>`_)
- Registrar (`registry.gitlab.eox.at/vs/vs/core <https://gitlab.eox.at/vs/vs/container_registry/387>`_)
- Seeder (`registry.gitlab.eox.at/vs/vs/seeder <https://gitlab.eox.at/vs/vs/container_registry/395>`_)
- Preprocessor v2 (`registry.gitlab.eox.at/vs/preprocessor <https://gitlab.eox.at/vs/preprocessor/container_registry/165>`_)
- Preprocessor with Mapchete (`registry.gitlab.eox.at/vs/vs/preprocessor <https://gitlab.eox.at/vs/vs/container_registry/381>`_)
- Ingestor (`registry.gitlab.eox.at/vs/ingestor <https://gitlab.eox.at/vs/ingestor/container_registry/163>`_)
- Harvester (`registry.gitlab.eox.at/vs/vs/harvester <https://gitlab.eox.at/vs/harvester/container_registry/373>`_)
- Scheduler (`registry.gitlab.eox.at/vs/vs/scheduler <https://gitlab.eox.at/vs/scheduler/container_registry/367>`_)
- Database (`postgis/postgis <https://hub.docker.com/r/postgis/postgis/>`_)
- Queue Manager (`redis <https://hub.docker.com/_/redis>`_)


Additional services deployed with View Server in different contexts are:

- Reverse proxy (`traefik <https://hub.docker.com/_/traefik>`_)
- Log collector (`registry.gitlab.eox.at/esa/prism/fluentd <https://gitlab.eox.at/esa/prism/fluentd/container_registry/170>`_)
- Kibana (`kibana <https://hub.docker.com/_/kibana>`_)
- Elasticsearch (`elasticsearch <https://hub.docker.com/_/elasticsearch>`_)
- Shibboleth SP3 (`registry.gitlab.eox.at/esa/prism/shibauth <https://gitlab.eox.at/esa/prism/shibauth/container_registry/171>`_) - only in PRISM
- SFTP (`registry.gitlab.eox.at/esa/prism/sftp <https://gitlab.eox.at/esa/prism/sftp/container_registry/173>`_) - only in PRISM
- Dem-App (`registry.gitlab.eox.at/esa/prism/dem-app <https://gitlab.eox.at/esa/prism/dem-app/container_registry/177>`_) - only for DEM collections in PRISM
- Terrain-server (`geodata/cesium-terrain-server <https://hub.docker.com/r/geodata/cesium-terrain-server>`_) - only for DEM collections in PRISM

These components are expected to be managed together in a Docker Swarm via
Docker Compose configuration files and in Kubernetes as Helm releases
with configuration Values.

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

The section :ref:`operating_k8s` describes how to customize the configuration file `values.yaml` and deploy VS on Kubernetes.

The section :ref:`initswarm` describes additional steps necessary to deploy a Docker Swarm stack using the
configuration file `values.yaml`.

You can choose not to read through the setup and configuration and rather focus on 
a cookbook of steps for creating a complete configuration for a single data collection in
section :ref:`creating_new_collections`

To search for concrete management/operations task after having already setup a running instance, no matter the platform, please continue directly to a condensed chapter listing the individual commands: :ref:`operation_management`.

Migration Guide
---------------

View Server adheres to `Semantic Versioning <https://semver.org/>`_ in format MAJOR.MINOR.PATCH and upgrading it by a PATCH version increase (bugfixes) is possible without special considerations by usual deployment upgrade methods (depends if on Docker Swarm or Kubernetes).

For instructions regarding MAJOR or MINOR version increase, please refer to the `View Server breaking changes <https://gitlab.eox.at/vs/vs/-/tree/main/BREAKING.md>`_ and any extra project specific Migration guides.