.. _admin:

Administration
==============

This chapter describes maintenance tasks for the administrator of a GHC instance.
There is a separate :ref:`userguide` 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:

.. code-block:: bash
    
    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.

Database
--------

For database administration the following commands are available.

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


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.

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.

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 <https://demo.geohealthcheck.org/csv>`_)
* one Resource: https://demo.geohealthcheck.org/resource/1/json (or `CSV <https://demo.geohealthcheck.org/resource/1/csv>`_)
* all history (Runs) of one Resource: https://demo.geohealthcheck.org/resource/1/history/json (or `in csv <https://demo.geohealthcheck.org/resource/1/history/csv>`_)

NB for detailed reporting data only JSON is supported.

.. _admin_user_mgt:

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).

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 <https://passlib.readthedocs.io/en/stable/>`_
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';

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`.