#510 fixes to allow install in plain Python venv

Author: justb4

README.md

@@ -10,15 +10,20 @@ See also the [full GHC documentation](http://docs.geohealthcheck.org/).
 
 Easiest is [to run GHC using Docker](https://github.com/geopython/GeoHealthCheck/blob/master/docker/README.md).
 
-## Manual Install
-Below a quick overview of a manual install on Unix-based systems like Apple MacOS and Linux.
+## Standard Install
+
+Below an overview of an installation on Unix-based systems like Apple MacOS and Linux with just plain Python. 
+NB works with Python 3.12.*, other Python versions need tweaking [pyproject.toml](pyproject.toml).
 
 ```bash
-virtualenv GeoHealthCheck && cd $_
+
+python -m venv ghc && cd ghc
 . bin/activate
 git clone https://github.com/geopython/GeoHealthCheck.git
 cd GeoHealthCheck
-pip3 install Invoke
+pip install --no-cache-dir -U pip setuptools wheel Invoke
+pip install --no-cache-dir -e . 
+
 # setup installation
 invoke setup
 # generate secret key
@@ -27,6 +32,7 @@ invoke create-secret-key
 vi instance/config_site.py
 # edit at least secret key:
 # - SECRET_KEY  # copy/paste result string from `invoke create-secret-key`
+# - SQLALCHEMY_DATABASE_URI = 'sqlite:///../instance/data.db' - put in instance dir
 
 # Optional: edit other settings or leave defaults
 # - SQLALCHEMY_DATABASE_URI
@@ -38,32 +44,32 @@ vi instance/config_site.py
 # - GHC_MAP (or use default settings)
 
 # setup database and superuser account interactively 
-invoke create
+invoke create -u admin -p admin -e a@a.com
 
 # start webserver with healthcheck runner daemon inside 
 # (default is 0.0.0.0:8000)
-python3 GeoHealthCheck/app.py  
+python GeoHealthCheck/app.py  
 # or start webserver on another port
-python3 GeoHealthCheck/app.py 0.0.0.0:8881
+python GeoHealthCheck/app.py 0.0.0.0:8881
 # or start webserver on another IP
-python3 GeoHealthCheck/app.py 192.168.0.105:8001
+python GeoHealthCheck/app.py 192.168.0.105:8001
 
 # OR start webserver and separate runner daemon (scheduler) process
 vi instance/config_site.py
 # GHC_RUNNER_IN_WEBAPP = False
-python3 GeoHealthCheck/scheduler.py & 
-python3 GeoHealthCheck/app.py  
+python GeoHealthCheck/scheduler.py & 
+python GeoHealthCheck/app.py  
 
 # next: use a real webserver or preferably Docker for production
 
 # other commands
 #
 # drop database
-python3 GeoHealthCheck/models.py drop
+python GeoHealthCheck/models.py drop
 
 # load data in database (WARN: deletes existing data!)
 # See example data .json files in tests/data
-python3 GeoHealthCheck/models.py load <.json data file> [y/n]
+python GeoHealthCheck/models.py load <.json data file> [y/n]
 
 ```
 
@@ -72,7 +78,8 @@ python3 GeoHealthCheck/models.py load <.json data file> [y/n]
 [Pixi](https://pixi.sh) manages the environment; tasks run via `pixi run`,
 so no shell activation is needed.
 
-```
+```bash
+
 git clone https://github.com/geopython/GeoHealthCheck.git
 cd GeoHealthCheck
 
@@ -92,7 +99,7 @@ vi instance/config_site.py
 # 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
+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
@@ -106,7 +113,8 @@ pixi run -e prod run
 
 ### Development and tests
 
-```
+```bash
+
 # install the dev environment (adds flake8, pytest, ...)
 pixi install -e dev
 

VERSION

@@ -1 +1 @@
-0.9.0
+0.9.1dev

docs/install.rst

@@ -31,7 +31,7 @@ These dependencies are automatically installed (see below). `Invoke <https://doc
 for installation and management. ``Cron`` was used for scheduling the actual
 healthchecks before v0.5.0.
 
-Starting from version v0.8.0.0 GeoHealthCheck requires **python3 3**. Previous
+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.
 
@@ -40,24 +40,26 @@ Install
 
 .. note::
 
-  It is strongly recommended to install GeoHealthCheck in a Python ``virtualenv``.
-  a ``virtualenv`` is self-contained and provides the flexibility to install /
+  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.
-  If installing on Ubuntu, you may need to install the python-dev package for installation to complete successfully.
-  
+  settings. The installation is driven by the standard config file `pyproject.toml`.
+  It is recommended to use `pixi <https://pixi.prefix.dev/>`_ to manage the entire installation and
+  further management.
+
 - Download a GeoHealthCheck release from
   https://github.com/geopython/GeoHealthCheck/releases, or clone manually from GitHub. 
 
+The following local install works with Python 3.12, other (lower) Python versions may need changes in `pyproject.toml`.
+
 .. code-block:: bash
 
-  python3 -m venv ghc && cd ghc
-  source ./bin/activate
+  python -m venv ghc && cd ghc
+  . bin/activate
   git clone https://github.com/geopython/GeoHealthCheck.git
   cd GeoHealthCheck
-
-  # install Invoke dependency for admin tool
-  pip3 install invoke
+  pip install --no-cache-dir -U pip setuptools wheel Invoke
+  pip install --no-cache-dir -e .
 
   # setup app
   invoke setup
@@ -68,8 +70,8 @@ Install
   # almost there!  Customize config
   vi instance/config_site.py
   # edit:
-  # - SQLALCHEMY_DATABASE_URI
-  # - SECRET_KEY  # from invoke create-secret-key
+  # - 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
@@ -84,17 +86,52 @@ Install
   # - GHC_MAP  # or use default settings
   # - GEOIP  # or use the default settings
 
-  # init database
-  python3 GeoHealthCheck/models.py create
+  # setup database and superuser account directly
+  invoke create -u admin -p admin -e a@a.com
 
   # start web-app
-  python3 GeoHealthCheck/app.py  # http://localhost:8000/
+  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.
 
+It is strongly recommended to install `pixi <https://pixi.prefix.dev/>`_ and
+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 at least secret key:
+    # - SECRET_KEY  # copy/paste result string from the command above
+
+    # 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
+
 .. _upgrade:
 
 Upgrade
@@ -269,12 +306,11 @@ See for example the `GHC Docker run.sh <https://github.com/geopython/GeoHealthCh
 script to run the GHC Webapp with `gunicorn` and the `GHC Runner run-runner.sh <https://github.com/geopython/GeoHealthCheck/blob/master/docker/scripts/run-runner.sh>`_ script
 to run the scheduled healthchecks.
 
-Use virtualenv
-..............
+Virtual Environment
+...................
 
-This is a general Python-recommendation. Save yourself from classpath and library hells by using `virtualenv`! Starting with python3 3.3
-a `venv script <https://docs.python.org/3.3/library/venv.html>`_ is provided and from python3 3.6 the `venv module <https://docs.python.org/3/library/venv.html>`_
-is included in the standard library.
+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 <https://docs.python.org/3.12/library/venv.html>`_ is provided in the standard library.
 
 Use SSL (HTTPS)
 ...............

pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "GeoHealthCheck"
-version = "0.9.0"
+version = "0.9.1dev"
 description = "Monitor uptime and availability of OGC web services and REST APIs"
 readme = "README.md"
-requires-python = ">=3.12,<3.13"
-license = { text = "MIT" }
+requires-python = ">=3.12,<3.14"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     { name = "Just van den Broecke", email = "just@justobjects.nl" },
     { name = "Tom Kralidis", email = "tomkralidis@gmail.com" },
@@ -49,6 +50,15 @@ Homepage = "https://geohealthcheck.org"
 Documentation = "https://docs.geohealthcheck.org"
 Repository = "https://github.com/geopython/GeoHealthCheck"
 
+[build-system]
+requires = ["setuptools", "pip", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+exclude = ["tests*"]
+include = ["GeoHealthCheck*"]
+
 # Pixi workspace configuration (replaces pixi.toml)
 # No [build-system] on purpose: GeoHealthCheck runs from source
 # (via `invoke setup`), so pixi manages the environment but does not

tasks.py

@@ -67,10 +67,7 @@ def setup(c):
         data_dir.chmod(0o777)
         shutil.copy2(config_file, config_site)
 
-    # setup deps
-    # c.run('pip3 install -r requirements.txt')
-
-    skin = 'http://github.com/BlackrockDigital/startbootstrap-sb-admin-2/archive/v3.3.7+1.zip'  # noqa
+    skin = 'https://github.com/BlackrockDigital/startbootstrap-sb-admin-2/archive/v3.3.7+1.zip'  # noqa
 
     skin_dirs = ['dist', 'vendor']
     need_to_fetch = False