# Installation

This manual describes the installation of the gempa software manager (GSM).
GSM is a packet manager which supports to install SeisComP as well as gempa
packages from a configured remote package repository. Database migration
is **not supported** yet. However gsm informs the user about required migrations.

## Requirements

 * Python 3
 * pip3

## Install

1. Install required python packages for Python 3

2. Get the latest gsm package with
```
wget https://data.gempa.de/gsm/gempa-gsm.tar.gz
```

3. Extract the package with
```
tar xf gempa-gsm.tar.gz
```
The tar file contains a folder named *gsm* containing the complete gsm bundle.

## File structure

```
gsm
│   README
│   CHANGELOG
│   gsm.conf       # Stores the configuration e.g. username and password
└───local          # Local package storage. Stores information about installed
|   |              # packages.
│   │   gsm
│   │   ...
│
└───sync           # Remote package cache. Stores information about all
    |              # available packages.
    |   gaps
    │   gsm
    │   scanloc
    |   ...
```

## Setup

To setup the installation environment run
```
./gsm setup
```

Configuration settings stored in gsm.conf

| Variable  | Description   |
|---|---|
|os| Distribution name e.g. rhel or ubuntu|
|os_version| Major distribution version e.g 7 or 20.04|
|arch| System architecture e.g. x86_64 or armv7l|
|base_url| gempa customer repo base URL e.g. https://data.gempa.de/packages/foo|
|user| Username provided in the Wiki section of the gempa customer portal|
|password| Password provided in the Wiki section of the gempa customer portal|
|release| Name of the SeisComP release. e.g 5 or nightly|
|download_dir| Directory where downloaded files are stored|
|install_path| User defined root path e.g. /home/sysop/seiscomp|
|data_dir| Base directory for data packages like maps or greensfunctions|
|verify| Enable/disable SSL certificate check e.g. True|
|debug| Enable verbose logging. Default: False|
|sync_dir| Remote package cache, contains information about available packages|
|local_dir| Local package storage, contains information about installed packages|

## Proxy Settings

Normally no user interaction is required but some systems require to specify
additional proxy settings for the current shell in order that **gsm** can establish a
connection to the gempa package server. For this **gsm** uses the Python requests
module to transfer data and there are several ways to define the proxy server.
Here an example:

```
export HTTP_PROXY="http://10.10.1.10:3128"
export HTTPS_PROXY="http://10.10.1.10:1080"
```

Then **gsm** can be used as usual.

## Deploy

To update the package cache run
```
./gsm update
```

To install a package run
```
./gsm install app
```

To install all configured packages run
```
./gsm install
```
To install spefific version of a package run
```
./gsm install app=2019.101
```

To reinstall a package run
```
./gsm reinstall app
```

To override the configured package selection run e.g.
```
./gsm install seiscomp licenses
```
To show all installed packages with version
```
./gsm info
```
To show installed package with all infomation
```
./gsm info app
```

## Offline workflow

Sometimes a user or an organization has the requirement that downloaded packages be virus-checked before installation, or that the actual installation be done on a machine without internet access. We here describe a basic offline workflow using gsm (gempa software manager) enabling this. Note that on some systems, the command `gsm` has to be replaced by `./gsm`. Replace the exemplary packages *seiscomp* and *tools* by your actual packages.

### First time

#### On *online* machine
1. Create and change into install directory, e.g.:  
`cd ~`  
`mkdir install`  
`cd install`
2. Download gsm tarfile:  
`wget https://data.gempa.de/gsm/gempa-gsm.tar.gz`
3. Unpack gsm:  
`tar xf gempa-gsm.tar.gz`  
`cd gsm`
4. Perform setup:  
`gsm setup`
5. Perform update via gempa repository:  
`gsm update`
6. Install required packages in **download-only mode**, e.g.:  
`gsm install -d seiscomp tools`
7. If required, virus-check gsm directory

#### On *offline* machine
1. Create install directory, e.g.:  
`cd ~`  
`mkdir install`  
`cd install`
2. Copy gsm directory from online machine:  
`scp -r user1@online-machine:~/install/gsm user2@offline-machine:~/install`  
(or copy with memory stick)  
`cd ~/install/gsm`
3. Install required packages in **offline mode**:  
`gsm install -o seiscomp tools`

### Subsequent times

#### On *online* machine
1. Go to gsm directory:  
`cd ~/install/gsm`
2. Remove files in packages directory to reduce virus-checking effort:  
`gsm clean packages`
3. Perform update via gempa repository:  
`gsm update`
4. Install required packages in **download-only mode**, e.g.:  
`gsm install -d seiscomp tools`
5. If required, virus-check gsm directory

#### On *offline* machine
1. Go to gsm directory:  
`cd ~/install/gsm`
2. Clean *sync* and *packages* directories:  
`gsm clean all`
3. Copy directories `gsm/sync` and `gsm/packages` from online machine to offline machine using memory stick or scp
4. Install latest version of gsm (don't force reinstall if already latest):  
`gsm install -o gsm`
5. Install new versions of all previously installed packages in **offline mode**:  
`gsm install -o`