Description

Downloads and updates LIPI installation and configuration files.

Install the update tool

# download
user@localhost$ wget <https://api.mazemap.com/lipi/download/lipi>

# (optional) add to path for ease of use
user@localhost$ cp lipi /usr/local/bin/

# complete installation (one time setup of api key and installation folder)
user@localhost$ lipi --setup
Initiating setup
Setup already complete. Reconfigure (y/n): y
Mazemap API key: 123456789
Installation folder: /lipi-install
Saving config: OK
Installing cron: OK
Setup complete

Usage

Download and install latest lipi

(requires MazeMap api key and internet access)

lipi --install latest

Note: If this is the first installation, the tool will also download the configuration
file from MazeMap.

Run status check

lipi --status

Run status check, and report to MazeMap

(requires MazeMap api key and internet access)

lipi --status report

List available lipi versions

(requires MazeMap api key and internet access)

lipi --list-available

Download and install specific version of lipi

(requires MazeMap api key and internet access)

lipi --install 1.0.1

Install from local source

lipi \
    --install 1.0.1 \
    --lipi-path /path/to/lipi.zip \
    --config-path /path/to/config.json

Install from MazeMap, using custom configuration file

lipi \
    --install latest \
    --config-path /path/to/config.json

Update config of running lipi

(requires MazeMap api key and internet access)

lipi --update-config

Update config of running lipi, using custom configuration file

(requires mazemap api key and internet access)

lipi --update-config \
    --config-path /path/to/config.json

List installed lipi versions and see which one is active

lipi --list

Activate a previous installation

lipi --activate [copy and paste a value from the list of installed versions]

Reconfigure running LIPI

Reinitialize the current configuration with new variables.

lipi --reconfigure

What happens during install and updating

• If the MazeMap api key is set, the tool can download new versions of lipi and
  the configuration file from MazeMap servers.

• After running initial --setup, the tool will install a cron task which regularly
  runs the command lipi --status report. This will send lipi health data to MazeMap
  on a regular basis so that we can provide a better level of service to you. This is
  only installed if the MazeMap API Key is set during setup. If this is not installed
  we can not help debugging an installation, and we will not be able to help users
  if they have trouble accessing the LIPI service. See Run status check, and report to MazeMap
  to see what is reported to MazeMap.

• When installing a new version of LIPI, the update tool will prefer to use the
  configuration files of the currently running LIPI version. This can be overridden
  using the --config-path flag or by running --update-config before running
  --install.

• Every --install and --update-config creates a new installation version. This
  is done to allow switching between new and previous installations or configurations
  at will. If something goes wrong, a previous version can be activated using
  --activate. The installation or update process will activate the previous version
  if the new version can't be started or seem unresponsive (if --status does not
  show a fully healthy installation).

Manual fixing:

• --setup stored values in a file params.txt. Running --setup again will overwrite it.

• A LIPI service has a config.json in its installation folder, which can be copied,
  edited and used using --config-path, if needed.

• The folders under lipi installation path are self contained and can be deleted at will.
  Just make sure to not delete the running version. Use --list or --status to see which
  version is running.

• LIPI is started using systemctl. Status and control of that service is available.
  systemctl [status|start|stop|restart] lipi.service.

Internal README

Local development

Build and start test docker container:

./test.sh

Docker container contains following folders:

/updatetool - mazemap-gerrit/positioning/updatetool/

/lipi-sources - contains set of lipi test installations and an empty config.json

/mockservice - contains files needed to start the mock service

Packaging

Start test docker container and run:

./package.sh

Produces updatetool/bin/lipi

Testing with mock lipi installation

Following commands are run from inside test docker container.

# Starts a service on port 443 which answers 200 on localhost:443/shallow and localhost:443/deep.
# This will allow the health checks to complete even though there's no lipi service running.
./start-mock-server.sh

# run commands on python src:
python src/updater.py --help

# run commands using packaged executable
bin/lipi --help