3. Administration

This chapter describes maintenance tasks for the administrator of a GHC instance. There is a separate User Guide that provides guidance to the end-user to configure the actual Resource healthchecks.

Since v0.10.0, Invoke and Pixi can be used. Before Pixi commands, run pixi shell -e prod in the repo top level directory. Below the main commands (hint: type pixi run –help to see commands:

pixi run setup  or  invoke setup
pixi run create  or  invoke create
pixi run load-data  or  invoke load-data
pixi run drop-data  or  invoke drop-data
pixi run create-secret-key  or  invoke create-secret-key
pixi run run  or  python GeoHealthCheck/app.py
pixi run db-action  (pixi run db-action --help for tasks) or  invoke db-action

Each of the sections below is geared at a specific administrative task area.

3.1. Database

For database administration the following commands are available.

3.1.1. create db

To create the database execute the following:

Open a command line, (if needed activate your virtualenv), and do

invoke create -u <username>> -p <password> -e you@email.com

3.1.2. drop db

To delete the database execute the following, however you will loose all your information. So please ensure backup if needed:

Open a command line, (if needed activate your virtualenv), and do

invoke drop-data

Note: you need to create a Database again before you can start GHC again.

3.1.3. load data

To load a JSON data file, do (WARN: deletes existing data!)

invoke load-data <datafile.json>

Hint: see tests/data for example JSON data files.

3.1.4. export data

Exporting database-data to a .json file with or without Runs is still to be done.

Exporting Resource and Run data from a running GHC instance can be effected via a REST API, for example:

all Resources: https://demo.geohealthcheck.org/json (or as CSV)
one Resource: https://demo.geohealthcheck.org/resource/1/json (or CSV)
all history (Runs) of one Resource: https://demo.geohealthcheck.org/resource/1/history/json (or in csv)

NB for detailed reporting data only JSON is supported.

3.2. User Management

During initial setup, a single admin user is created interactively.

Via the GHC_SELF_REGISTER config setting, you allow/disallow registrations from users on the webapp (UI).

3.2.1. Passwords

Passwords are stored encrypted. Even the same password-string will have different “hashes”. There is no way that GHC can decrypt a stored password. This can become a challenge in cases where a password is forgotten and somehow the email-based reset is not available nor working. In that case, password-hashes can be created from the command-line using the Python library passlib within an interactive Python-shell as follows:

$ pip install passlib
# or in Debian/Ubuntu: apt-get install python-passlib

python3
>>> from passlib.hash import pbkdf2_sha256
>>>
>>> hash = pbkdf2_sha256.hash("mynewpassword")
>>> print(hash)
'$pbkdf2-sha256$29000$da51rlVKKWVsLSWEsBYCoA$2/shIdqAxGJkDq6TTeIOgQKbtYAOPSi5EA3TDij1L6Y'
>>> pbkdf2_sha256.verify("mynewpassword", hash)
True

Or more compact within the root dir of your GHC installation:

>>> from GeoHealthCheck.util import create_hash
>>> create_hash('mynewpassword')
'$pbkdf2-sha256$29000$8X4PAUAIAcC4V2rNea9Vqg$XnMx1SfEiBzBAMOQOOC7uxCcyzVuKaHENLj3IfXvfu0'

Or even more compact within the root dir of your GHC installation via Invoke:

$ invoke create-hash -p mypass
Copy/paste the entire token below for example to set password
$pbkdf2-sha256$29000$FkJoTYnxPqc0pjQG4HxP6Q$C3SZb8jqtM7zKS1DSLcouc/CL9XMI9cL5xT6DRTOEd4

Then copy-paste the hash-string into the password-field of the User-record in the User-table. For example in SQL something like:

$ sqlite3 data.db
# or psql equivalent for Postgres

sqlite> UPDATE user SET password = '<above hash-value>' WHERE username == 'myusername';

3.3. Build Documentation

Open a command line, (if needed activate your virtualenv or your pixi environment) and enter invoke refresh_docs or pixi run docs. Find the generated HTML docs under docs/_build/html/index.html.