1. Installation

Below are installation notes for GeoHealthCheck (GHC).

1.1. Docker

The easiest and quickest install for GHC is with Docker/Docker Compose using the GHC images hosted on Docker Hub.

See the GHC Docker Readme for a full guide.

1.2. Requirements

GeoHealthCheck is built on the awesome Flask micro-framework and uses Flask-SQLAlchemy for database interaction and Flask-Login for authorization. Flask-Migrate with Alembic and Flask-Script is used for database upgrades.

OWSLib is used to interact with OGC Web Services.

APScheduler is used to run scheduled healthchecks.

These dependencies are automatically installed (see below). Invoke is used for installation and management. Cron was used for scheduling the actual healthchecks before v0.5.0 but is now obsolete.

Starting from version v0.8.0 GeoHealthCheck requires python3 3. Previous versions require python3 2. GeoHealthCheck is at least compatible with Python versions up to and including 3.12.3. Higher Python versions may work but are untested.

1.3. Install

Note

It is strongly recommended to install GeoHealthCheck in a Python Virtual Environment. A Virtual Environment is self-contained and provides the flexibility to install / tear down / whatever packages without affecting system wide packages or settings. The installation is driven by the standard config file pyproject.toml. It is strongly recommended to use Pixi to manage installation and management.

• Download a GeoHealthCheck release from https://github.com/geopython/GeoHealthCheck/releases, or clone manually from GitHub.

It is strongly recommended to install Pixi to handle the GeoHealthCheck installation and further tasks. The GHC Dockerfile also uses Pixi.

git clone https://github.com/geopython/GeoHealthCheck.git
cd GeoHealthCheck

# Install production environment
pixi install -e prod

# bootstrap the app (config, static assets, i18n, local docs, DB)
pixi run -e prod setup

# generate secret key
pixi run -e prod create-secret-key
# setup local configuration (overrides GeoHealthCheck/config_main.py)
vi instance/config_site.py
# edit:
# - SQLALCHEMY_DATABASE_URI = 'sqlite:///../instance/data.db' - put in instance dir
# - SECRET_KEY  # paste from invoke create-secret-key
# - GHC_RETENTION_DAYS
# - GHC_SELF_REGISTER
# - GHC_NOTIFICATIONS
# - GHC_NOTIFICATIONS_VERBOSITY
# - GHC_ADMIN_EMAIL
# - GHC_NOTIFICATIONS_EMAIL
# - GHC_SITE_TITLE
# - GHC_SITE_URL
# - GHC_RUNNER_IN_WEBAPP # see 'running' section below
# - GHC_REQUIRE_WEBAPP_AUTH  # optional: to require authentication to access webapp
# - GHC_SMTP  # if GHC_NOTIFICATIONS is enabled
# - GHC_MAP  # or use default settings
# - GEOIP  # or use the default settings

# Optional: edit other settings or leave defaults (see above)

# setup superuser account password and email directly
pixi run -e prod create --username admin --password admin --email a@a.com

# or shorter
pixi run -e prod create -u admin -p admin --e a@a.com

# run locally
pixi run -e prod run

# open http://localhost:8000 in browser

The following local install using the standard Python venv works with Python 3.12, other (lower) Python versions may need changes in pyproject.toml.

python -m venv ghc && cd ghc
. bin/activate
git clone https://github.com/geopython/GeoHealthCheck.git
cd GeoHealthCheck
pip install --no-cache-dir -U pip setuptools wheel Invoke
pip install --no-cache-dir -e .

# setup app
invoke setup

# create secret key to use for auth
invoke create-secret-key

# almost there!  Customize config
vi instance/config_site.py
# edit:
# - SECRET_KEY  # paste from invoke create-secret-key
# See above for other variables.

# setup database and superuser account directly
invoke create -u admin -p admin -e a@a.com

# start web-app
python GeoHealthCheck/app.py  # http://localhost:8000/

# when you are done, you can exit the virtualenv
deactivate

NB GHC supports internal scheduling, no cronjobs required.

1.4. Upgrade

An existing GHC database installation can be upgraded with:

# In the top directory (e.g. the topdir cloned from github)
invoke db-action upgrade

# Notice any output, in particular errors

Notes:

• Always backup your database first!!

• make sure Flask-Migrate is installed (see requirements.txt), else: pip install Flask-Migrate==2.5.2, but best is to run invoke setup also for other dependencies

• upgrading is “smart”: you can always run invoke upgrade, it has no effect when DB is already up to date

• when upgrading from earlier versions without Plugin support:

  • adapt your config_site.py to Plugin settings from config_main.py

  • assign Probes and Checks to each Resource via the UI

When running with Docker see the GHC Docker Readme how to run invoke upgrade within your Docker Container.

1.4.1. Upgrade notes v0.5.0

In GHC v0.5.0 a new run-architecture was introduced. By default, healthchecks run under the control of an internal scheduler, i.s.o. of external cronjobs. See also the Architecture chapter and Healthcheck Scheduling and below.

1.4.2. Upgrade notes v0.6.0

In GHC v0.6.0 encryption was added for password storage. Existing passwords should be migrated via the invoke upgrade command. Also password recovery was changed: a user can create a new password via a unique, personal URL that GHC sends by email. This requires a working email configuration and a reachable SITE_URL config value. See User Management for solving password problems.

See closed issues for related Milestone 0.6.0

1.4.3. Upgrade notes v0.7.0

No database changes. Many fixes and enhancements, see closed issues for related Milestone 0.7.0.

1.4.4. Upgrade notes v0.8.0

Main change: migrated from Python 2 to Python 3. No DB upgrades required. One major improvement was more robust (HTTP) retries using the requests Session object.

See closed issues for related Milestone 0.8.0.

1.4.5. Upgrade notes v0.8.3

Main change: Bugfixes and small new features on 0.8.0 (0.8.1 and 0.8.2 were skipped). No DB upgrades required.

OWSLib was upgraded to 0.20.0. Some Py2 to Py3 string encoding issues.

One major improvement was adding User-Agent HTTP header for Probe requests.

See closed issues for related Milestone 0.8.3.

1.4.6. Upgrade notes v0.9.0

Many (58!) issues and PRs went in. Also thanks to contributors some major features were added:

• configurable Geocoder (by @borrob)

• CI (from Travis CI) and Docker build/push migrated to Github Workflows

• OGC 3DTiles Probe (by SpotInfo)

• MapBox TileJSON Probe (by SpotInfo)

• additional WMTS Probes (by SpotInfo)

• use official OGC naming for OAFeat Probes (includes db-action upgrade)

• many bugfixes and security updates

Only a single db-action upgrade is required and only if your installation (DB) contains OGC OAFeat Resources and Probes, formerly called “WFS3”.

See closed issues/merged PRs for related Milestone 0.9.0.

1.4.7. Upgrade notes v0.10.0

This is a major upgrade. About 35 issues and PRs went in from 0.9.0 to 0.10.0. The main breaking change is that the project switched from requirements.txt plus Paver to pyproject.toml with the Invoke Task executor and the Pixi Python Environment Manager. This affects the installation and management steps and the Docker Image (much smaller!) plus Docker and Docker Compose deployment settings. Although using Pixi is preferred, a tradional “venv” install is still supported.

The preferred Python version is 3.12, default in Ubuntu 24.04. These versions are also used in the Docker Image. As a consequence some packages have upgrades, Flask-script was removed. In a next version more packages will be upgraded. Higher Python versions like 3.13 may work, but are not guaranteed.

See closed issues for the related GitHub Milestone 0.10.0.

Specifics, for existing, pre 0.10.0, installations:

• Docker Containers now run under a specific non-root user. This may give permission issues.

• docker-compose.yml: entrypoint now uses scripts directly like /app/docker/scripts/run-runner.sh i.s.o. /run-runner.sh

• When using SQLite in a Docker Named Volume you may need to re-init the DB if you get permission issues

• Paver is replaced by Invoke and Pixi: see the updated README and docs for new maintenance commands

1.5. Running

Start using Flask’s built-in WSGI server:

python3 GeoHealthCheck/app.py  # http://localhost:8000
python3 GeoHealthCheck/app.py 0.0.0.0:8881  # http://localhost:8881
python3 GeoHealthCheck/app.py 192.168.0.105:8957  # http://192.168.0.105:8957

This runs the (Flask) GHC Webapp, by default with the GHC Runner (scheduled healthchecker) internally. See also Healthcheck Scheduling for the different options running the GHC Webapp and GHC Runner. It is recommended to run these as separate processes. For this set GHC_RUNNER_IN_WEBAPP to False in your site_config.py. From the command-line run both processes, e.g. in background or different terminal sessions:

# run GHC Runner, here in background
python3 GeoHealthCheck/scheduler.py &

# run GHC Webapp for http://localhost:8000
python3 GeoHealthCheck/app.py

To enable in Apache, use GeoHealthCheck.wsgi and configure in Apache as per the main Flask documentation.

1.6. Running under a sub-path

By default GeoHealthCheck is configured to run under the root directory on the webserver. However, it can be configured to run under a sub-path. The method for doing this depends on the webserver you are using, but the general requirement is to pass Flask’s SCRIPT_NAME environment variable when GeoHealthCheck is started.

Below is an example of how to use nginx and gunicorn to run GeoHealthCheck in a directory “geohealthcheck”, assuming that you have nginx and gunicorn already set up and configured:

• In nginx add a section to the server block you are running GeoHealthCheck under:

location /geohealthcheck {
  proxy_pass http://127.0.0.1:8000/geohealthcheck;
}

• Include the parameter “-e SCRIPT_NAME=/geohealthcheck” in your command for running gunicorn:

gunicorn -e SCRIPT_NAME=/geohealthcheck app:app

1.7. Production Recommendations

1.7.1. Use Docker!

When running GHC in long-term production environment the following is recommended:

• use Docker, see the Docker Readme

Using Docker, especially with Docker Compose (sample files provided) is our #1 recommendation. It saves all the hassle from installing the requirements, upgrades etc. Docker (Compose) is also used to run the GHC demo site and almost all of our other deployments.

1.7.2. Use PostgreSQL

Although GHC will work with SQLite, this is not a good option for production use, in particular for reliability starting with GHC v0.5.0:

• reliability: GHC Runner will do concurrent updates to the database, this will be unreliable under SQLite

• performance: PostgreSQL has been proven superior, especially in query-performance

1.7.3. Use a WSGI Server

Although GHC can be run from the commandline using the Flask internal WSGI web-server, this is a fragile and possibly insecure option in production use (as also the Flask manual states). Best is to use a WSGI-server as stated in the Flask deployment options.

See for example the GHC Docker run.sh script to run the GHC Webapp with gunicorn and the GHC Runner run-runner.sh script to run the scheduled healthchecks.

1.7.4. Virtual Environment

Use Virtual Environment! This is a general Python-recommendation. Save yourself from classpath and library hells by using Python’s built-in virtualenv! Starting with python3 3.3 a venv script is provided in the standard library.

1.7.5. Use SSL (HTTPS)

As users and admin may login, running on plain http will send passwords in the clear. These days it has become almost trivial to automatically install SSL certificates with Let’s Encrypt.

1.8. Running on RaspberryPi

Running GeoHealthCheck on a RaspberryPi works with Docker. But the standard Docker image cannot be used, because it is not targeted at RaspberryPi’s ARM architecture. However, it is possible to manually build the Docker image for this architecture by replacing the Python base image of the Dockerfile with arm32v7/python:3.7.9-alpine. The image needs to be build on a machine with that architecuture. The RaspberryPi itself can be used for that, but it takes up to one hour.