diff --git a/docs/admin.rst b/docs/admin.rst index 4908b403..a575b7c0 100644 --- a/docs/admin.rst +++ b/docs/admin.rst @@ -110,11 +110,13 @@ The following aspects of a `Resource` can be edited: By default, when resource is created, owner's email will be added to notifications, however, resource can have arbitrary number or emails to notify. +.. _admin_running: + Running Healthchecks -------------------- Healthchecks (Runs) for each Resource can be scheduled via `cron` or -(since v0.5.0) by running the **GHC Runner** app standalone (as daemon) +(starting with v0.5.0) by running the **GHC Runner** app standalone (as daemon) or within the **GHC Webapp**. Scheduling via Cron @@ -139,10 +141,18 @@ GHC Runner as Daemon In this mode GHC applies internal scheduling for each individual `Resource`. This is the preferred mode as each `Resource` can have its own schedule (configurable via Dashboard) and `cron` has dependencies on local environment. -Later versions may phase out cron-scheduling. -The **GHC Runner** can be run via the command `paver runner_daemon` or internally within -the **GHC Webapp** by setting the config variable **GHC_RUNNER_IN_WEBAPP** to True. +Later versions may phase out cron-scheduling completely. + +The **GHC Runner** can be run via the command `paver runner_daemon` or can run internally within +the **GHC Webapp** by setting the config variable **GHC_RUNNER_IN_WEBAPP** to `True` (the default). +NB it is still possible to run GHC as in the pre-v0.5.0 mode using cron-jobs: just run the +**GHC Webapp** with **GHC_RUNNER_IN_WEBAPP** set to `False` and have your cron-jobs scheduled. + +In summary there are three options to run GHC and its healthchecks: +* run **GHC Runner** within the **GHC Webapp**: set **GHC_RUNNER_IN_WEBAPP** to `True` and run only the GHC webapp +* (recommended): run **GHC Webapp** and **GHC Runner** separately (set **GHC_RUNNER_IN_WEBAPP** to `False`) +* (deprecated): run **GHC Webapp** with **GHC_RUNNER_IN_WEBAPP** set to `False` and schedule healthchecks via external cron-jobs Build Documentation ------------------- diff --git a/docs/config.rst b/docs/config.rst index 5c2d7775..4bc29cbb 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -25,7 +25,7 @@ You can override these settings in ``instance/config_site.py``: - **GHC_USER_PLUGINS**: list of Plugin classes or modules provided by user (you) - **GHC_PROBE_DEFAULTS**: Default `Probe` class to assign on "add" per Resource-type - **GHC_METADATA_CACHE_SECS**: metadata, "Capabilities Docs", cache expiry time, default 900 secs, -1 to disable -- **GHC_RUNNER_IN_WEBAPP**: should the GHC Runner Daemon be run in webapp (default: false) +- **GHC_RUNNER_IN_WEBAPP**: should the GHC Runner Daemon be run in webapp (default: ``True``) - **GHC_LOG_LEVEL**: logging level: 10=DEBUG 20=INFO 30=WARN(ING) 40=ERROR 50=FATAL/CRITICAL (default: 30, WARNING) - **GHC_MAP**: default map settings diff --git a/docs/install.rst b/docs/install.rst index 690a790e..ccc0c506 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -74,6 +74,7 @@ Install # - GHC_NOTIFICATIONS_EMAIL # - GHC_SITE_TITLE # - GHC_SITE_URL + # - GHC_RUNNER_IN_WEBAPP # see 'running' section below # - GHC_SMTP # if GHC_NOTIFICATIONS is enabled # - GHC_MAP # or use default settings @@ -113,10 +114,17 @@ When running with Docker see the `GHC Docker Readme `_ how to run `paver 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 cron-jobs. See also the :ref:`architecture` chapter +and :ref:`admin_running` and below. + Running ------- -Start using the built-in ``mod_wsgi`` server: +Start using Flask's built-in WSGI server: .. code-block:: bash @@ -125,11 +133,25 @@ Start using the built-in ``mod_wsgi`` server: python 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 + python GeoHealthCheck/scheduler.py & + + # run GHC Webapp for http://localhost:8000 + python 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. @@ -141,10 +163,56 @@ Below is an example of how to use nginx and gunicorn to run GeoHealthCheck in a 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 `GHC 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. + +Use virtualenv +.............. + +This is a general Python-recommendation. Save yourself from classpath and library hells by using `virtualenv`! + +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 `_.