docs: Add and document a working Lando setup for local Janeway development

.lando.yml

@@ -3,58 +3,96 @@ name: janeway
 
 # CAREFUL with this env file, Docker env files don't support interpolation!
 env_file:
-  - dockerfiles/lando_defaults.env
-  - dockerfiles/lando_local.env
+  - etc/defaults.env
+
+proxy:
+  appserver:
+    - janeway.lndo.site
 
 services:
   appserver:
     type: python:3.9
-    command: python /app/src/manage.py runserver 0.0.0.0:8000 -v 3
+    port: 8000
+    command: /bin/sh /app/dockerfiles/lando-runserver-loop.sh
     build_as_root:
-      - grep '^deb ' /etc/apt/sources.list | perl -pe 's/deb /deb-src /' >> /etc/apt/sources.list
-      - apt-get update -qq && apt-get install -y python3-lxml pylint libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev && apt-get build-dep -y lxml
+      - |
+          rm -f /etc/apt/sources.list.d/debian-src.sources
+          if [ -f /etc/apt/sources.list.d/debian.sources ]; then
+            sed 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/debian.sources > /etc/apt/sources.list.d/debian-with-src.sources
+            rm -f /etc/apt/sources.list.d/debian.sources
+            mv /etc/apt/sources.list.d/debian-with-src.sources /etc/apt/sources.list.d/debian.sources
+          fi
+      - |
+          set -eu
+          packages="python3-lxml pylint libxml2-dev libxslt1-dev python3-dev zlib1g-dev libffi-dev libssl-dev libjpeg-dev"
+          arch="$(dpkg --print-architecture)"
+          if [ "$arch" = "amd64" ] || [ "$arch" = "i386" ]; then
+            packages="$packages lib32z1-dev"
+          fi
+          apt-get update -qq
+          apt-get install -y $packages
+          apt-get build-dep -y lxml
     build:
-      - cd /app && pip install --upgrade pip && pip install Cython && pip install psycopg2-binary~=2.8.0 && pip install -r requirements.txt &&  pip install -r dev-requirements.txt
-    scanner: true
+      - cd /app && pip install --upgrade pip && pip install Cython && pip install psycopg2-binary~=2.8.0 && pip install -r requirements.txt && pip install -r dev-requirements.txt
+    scanner:
+      path: /
     overrides:
-      ports:
-        - '8000:8000'
       environment:
-        PYTHONPATH: "/app/src"
-        JANEWAY_SETTINGS_MODULE: "core.settings" # this is the path to the Janeway settings file, which is in src/core/settings.py
+        DB_HOST: "db"
+        # Include vendored editable package roots so Django app labels resolve
+        # to the actual package instead of a namespace package shell.
+        PYTHONPATH: "/app/src:/app/src/foundationform"
+        JANEWAY_SETTINGS_MODULE: "core.dev_settings"
+      labels:
+        # Janeway runs its Django development server on port 8000, but Lando's
+        # default proxy wiring for python services assumes port 80. Keep an
+        # explicit high-priority route to the real application port.
+        traefik.enable: "true"
+        traefik.docker.network: landoproxyhyperion5000gandalfedition_edge
+        traefik.http.routers.janeway.entrypoints: http
+        traefik.http.routers.janeway.rule: Host(`janeway.lndo.site`)
+        traefik.http.routers.janeway.priority: "100"
+        traefik.http.routers.janeway.service: janeway-service
+        traefik.http.services.janeway-service.loadbalancer.server.port: "8000"
     moreHttpPorts:
       - '8000'
+
   db:
     type: postgres:15
     portforward: true
     creds:
       user: postgres
-      password: 
+      password:
       database: janeway
 
 tooling:
   python:
     service: appserver
     cmd: python
     dir: /app/src
+
   pip:
     service: appserver
     description: run pip commands to manage Python package installation in this environment
     cmd: pip
     dir: /app/src
+
   manage:
     service: appserver
     cmd: python manage.py
     dir: /app/src
+
   restart-runserver:
     service: appserver
-    description: Quickly restarts the Django runserver process, follows logs, and enables interactive debugging
-    cmd: killall python || python /app/src/manage.py runserver 0.0.0.0:8000 -v 3
+    description: Restarts the Django runserver by stopping it and letting the appserver command relaunch it
+    cmd: pkill -f "/app/src/manage.py runserver" || true
     dir: /app/src
     user: root
+
   psql:
     service: db
     cmd: psql -U postgres
+
   'db-import <file>':
     service: :host
     description: Imports a dump file into a database service

README.md

@@ -9,20 +9,22 @@ Janeway is written in Python (3.10+) and utilises the Django framework (4.2).
 # Installation instructions
 Developer installation [instructions are available in our documentation site](https://janeway.readthedocs.io/en/latest/dev/installation.html).
 
+For local development with Lando, see the repository guide at [docs/source/dev/lando.rst](docs/source/dev/lando.rst).
+
 A guide for installing on the live environment with [apache and mod_wsgi](https://github.com/openlibhums/janeway/wiki/Janeway%2C-Apache-and-WSGI) is also available.
 
 ## Running Janeway with docker
 Janeway's development server can be run within a docker container, avoiding the need to install and run its dependencies from your machine. A docker compose file as well as a Makefile can be found at the root of the project wrapping the most common operations.
 Docker is compatible with multiple architectures and Operating systems, if you need help installing docker, have a look at the [docker documentation](https://docs.docker.com/install/).
 
 Simarly to the native installation, Janeway can be installed in a docker environment by running ``make install`` and following the installation steps described [above](https://github.com/openlibhums/janeway/wiki/Installation). As a result, a database volume will be populated under janeway/db/postgres-data
-Once installation is completed, just type ``make janeway`` to run janeway with a postgres backend (default behaviour).
+Once installation is completed, run ``make janeway`` to run janeway with a postgres backend (default behaviour).
 
 If a change to the dependencies for Janeway is required, the Janeway container can be re-created with ``make rebuild``. The database volume will be preserved.
 
 In order to run a different RDBMS, the environment variable ``DB_VENDOR`` can be set to one of ``postgres``, ``mysql`` or ``sqlite``. e.g: ``DB_VENDOR=mysql make install && make``
 
-Uninstalling Janeway is as simple as running ``make uninstall`` which will delete all docker related containers as well as wipe the database volume.
+To uninstall Janeway, run ``make uninstall``. This deletes the Docker-related containers and wipes the database volume.
 
 # Janeway design principles
 1. No code should appear to work "by magic". Readability is key.

dockerfiles/lando-runserver-loop.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+set -u
+
+while true; do
+  python3 /app/src/manage.py runserver 0.0.0.0:8000 -v 3 --noreload
+  echo "Janeway runserver exited, restarting in 2 seconds..."
+  sleep 2
+done

docs/source/dev/installation.rst

@@ -1,9 +1,16 @@
-Installation Guide
-==================
-There are a number of ways to get Janeway up and running. For development we recommend you use Docker with Postgres as the DB_VENDOR.
-
-Running Janeway with Docker and docker compose
-----------------------------------------------
+Installation Guide
+==================
+There are a number of ways to get Janeway up and running. For development we recommend you use Docker with Postgres as the DB_VENDOR.
+
+If you want to develop Janeway with Lando, use the dedicated guide:
+
+.. toctree::
+   :maxdepth: 1
+
+   lando
+
+Running Janeway with Docker and docker compose
+----------------------------------------------
 1. Install ``docker`` and ``GNU Make``.
 2. From the /path/to/janeway directory run ``make install``.
 3. A docker environment will be provisioned, and shortly after the janeway install script will run. Follow the instructions on screen to complete the installation.
@@ -33,11 +40,10 @@ The Makefile can be configured with a number of variables to change the way in w
 * By default, the database backend will come with a database named ``janeway``. If you want to Janeway against a different database (e.g.: you have multiple local databases) you can set the DB_NAME variable (e.g.: ``make install DB_NAME="janeway_staging"`` or ``make run DB_NAME=janeway_production``
 * The ``JANEWAY_PORT`` variable allows you to change the port to which the Janeway development server will be bound to on your host (set this if port 8000 is already in use by another service on your host)
 
-If you want to install custom python libraries for development, you can drop them into the dev_requirements.txt file and run ``make rebuild``. Rebuilding the container takes some time, so it is also possible to install python libraries in development mode. When installed in this manner, the library is mounted as a volume into the janeway container when you first run `make rebuild` and  you will be able to make changes to the library without having to run ``make rebuild``. In order to install a library in development mode, copy the code to ``/path/to/janeway/lib/`` and run ``make rebuild`` once.
-
-
-Native Install
---------------
+If you want to install custom python libraries for development, you can drop them into the dev_requirements.txt file and run ``make rebuild``. Rebuilding the container takes some time, so it is also possible to install python libraries in development mode. When installed in this manner, the library is mounted as a volume into the janeway container when you first run `make rebuild` and  you will be able to make changes to the library without having to run ``make rebuild``. In order to install a library in development mode, copy the code to ``/path/to/janeway/lib/`` and run ``make rebuild`` once.
+
+Native Install
+--------------
 
 The following is for Debian/Ubuntu-based systems (16.04).
 
@@ -51,11 +57,14 @@ The following is for Debian/Ubuntu-based systems (16.04).
 
 2. Install system dependencies.
 
-On Ubuntu systems:
-``sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev libmysqlclient-dev``
-
-On Debian systems:
-``sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev``
+On Ubuntu systems:
+``sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev libffi-dev libssl-dev libjpeg-dev libmysqlclient-dev``
+
+On Debian systems:
+``sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev libffi-dev libssl-dev libjpeg-dev``
+
+On ``amd64`` systems, you may also need ``lib32z1-dev``. It is not generally
+available on ``arm64`` systems such as Apple Silicon.
 
 3. Clone the janeway repo to your local machine:
    ``git clone https://github.com/BirkbeckCTP/janeway.git``