Installation Guide
===============================================
.. toctree::
This page explains how to install Geona Hyperspectral
Installing Dependencies
-----------------------
Geona Hyperspectral is deployed using Linux container technology which means that there is just one software dependency
to install; all other dependencies are bundled inside the container. The software required to run, manage, and interact
with Geona Hyperspectral is called Docker.
We assume that the operator has some working knowledge of Docker, although this not need to be extensive. Docker provide
a full suite of documentation, product manuals, and guides which provide an excellent resource to understand the
software and its capabilities - `https://docs.docker.com/ `_
Docker Installation
___________________
.. image:: ../images/horizontal-logo-monochromatic-white.png
:width: 200
:align: right
Complete installation guide for Docker is available on the `Docker documentation website `_
for Windows, Mac and Linux
Verify Docker Installation
__________________________
Once installed, you can validate that the Docker engine installed correctly by using a command line tool. This command
will return the version number of the currently installed version of the Docker engine::
$ docker -v
Docker version 20.10.7, build f0df350
.. note::
Make sure that you are running Docker version 18.09 or higher
Installing Geona Hyperspectral
------------------------------
The software is available as a container to download from the container registry. To download the container, first login
to the container registry, replacing ``{personal-access-token}`` with you access token supplied by PML Applications::
$ docker login -u {personal-access-token} -p {personal-access-token} registry.digitalocean.com
Login Succeeded
Once logged in, pull the container from the registry::
$ docker pull registry.digitalocean.com/geona/hyperspectral:latest
The output of the ``pull`` command will look something like the following, although version numbers will change over time::
latest: Pulling from geona/hyperspectral
4d32b49e2995: Already exists
7d1600b414a9: Pull complete
514f134d6b0a: Pull complete
cb3210c445d8: Pull complete
20c76659694d: Pull complete
6c0372f9db9f: Pull complete
c6645d584768: Pull complete
47505e46ddc2: Pull complete
e7578e9c495f: Pull complete
0838873a3cc6: Pull complete
769e6a1ea9c6: Pull complete
02488c2fee0c: Pull complete
Digest: sha256:8f59c2cb920e82470be02feb8aa8ff2c9127ab0887065eff311de8eca96a051a
Status: Downloaded newer image for registry.digitalocean.com/geona/hyperspectral:latest
registry.digitalocean.com/geona/hyperspectral:latest
Workspace Directory
-------------------
All the software required to run Geona Hyperspectral is bundled within the container, however, we need to make the input
data available to the software. To do this we will mount a directory from your workstation into the container; this
directory will provide a persistent storage location for input data (i.e. the raw sensor data, navigation data, etc.),
configuration files which the software will produce, a workspace used while processing data, and a location for log files
to be saved.
This directory needs to have sufficient available disk space and be writable by the user account used to run the container (see `User Setup`).
In the working directory Geona will automatically create a series of folders for use when processing hyperspectral data.
These include:
* **configs** - when you use the user interface to create processing jobs the configuration is saved for future use; these files are name ``geona_hyperspectral_config__.ini``
* **licence** - this directory will contain a JSON file name ``licence_credentials.cfg`` which will contain you licence information
* **logs** - output location for system logs; log files will be generated each time an instance of the container is run with a name made up of the container start date/time suffixed with ``_geona_hyperspectral.log``, e.g. `2022-05-06-225307_geona_hyperspectral.log`
* **workspace** - this is the working directory which Geona uses to process data and produce results. Within this directory there will be a sub-directory for each processing job which is run.
User Setup
----------
The process which runs inside the container does so as a user called ``geona`` with a UID of ``65151``. This user is a
member of a group, also called ``geona``, with a GID of ``65151``. All files and folders created during the processing will be
owned by this user. This is to avoid all files which are created by Geona from being owned by ``root``.
If you are providing raw input data from your host machine, or local network, using the local volume, these files must be readable
by the ``geona`` group and the directory must be writable for log files and intermediate files created during processing. The best
way to do this is to create ``geona`` group on your local system specifying the group ID as ``65151``, add your user account to that
group, and then make ``geona`` the group owner of your local workspace directory; e.g. in a Linux environment::
$ sudo groupadd -g 65151 geona
$ sudo usermod -g 65151 $(id -u -n)
$ sudo chgrp 65151 -R /opt/geona/data
Once you have directory ready, you are ready to get started - :doc:`Quick start guide `