.. _install: Installation ============ Below are installation notes for GeoHealthCheck (GHC). 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. 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. 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`. .. code-block:: bash 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`. .. code-block:: bash 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. .. _upgrade: Upgrade ------- An existing GHC database installation can be upgraded with: .. code-block:: bash # 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. 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 :ref:`architecture` chapter and :ref:`admin_running` and below. 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 :ref:`admin_user_mgt` for solving password problems. See `closed issues for related Milestone 0.6.0 `_ Upgrade notes v0.7.0 .................... No database changes. Many fixes and enhancements, see `closed issues for related Milestone 0.7.0 `_. 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 `_. 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 `_. 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 `_. 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 Running ------- Start using Flask's built-in WSGI server: .. code-block:: bash 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 :ref:`admin_running` 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: .. code-block:: bash # 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. 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: .. code-block:: bash location /geohealthcheck { proxy_pass http://127.0.0.1:8000/geohealthcheck; } - Include the parameter "-e SCRIPT_NAME=/geohealthcheck" in your command for running gunicorn: .. code-block:: bash gunicorn -e SCRIPT_NAME=/geohealthcheck app:app Production Recommendations -------------------------- 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. 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 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. 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. 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 `_. 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.