updated readme

README.md

@@ -13,11 +13,15 @@ Kiwix Hotspot Demo has implemented openZIM's [Python bootstrap, conventions and
 ## Pre-requisites
 
 Installing this demo requires:
+
 - a Linux machine (or VM)
 - with Docker (compose is required as well but it is now parted of docker)
 - with Python 3.12 and preferably a venv
+- root access
+- `loop` must be enabled in kernel or module loaded
 
 If you start from a bare machine, you can:
+
 - install Docker by following instructions at https://docs.docker.com/engine/install/debian/
 - compile Python from sources by executing the install.sh script
   - tested on Debian Buster 10
@@ -29,17 +33,18 @@ If you start from a bare machine, you can:
 ## Installation
 
 To install the demo, you have to:
+
 - install the demo Python tooling: run `pip install git+https://github.com/offspot/demo@main`
 - customize the environment:
   - copy the `contrib/environment` file to `/etc/demo/environment`
     - could be any other appropriate location, but then you have to modify `<src_path>/systemd-unit/demo-offspot.service`
   - customize this file as needed
-  - automatically load the environment data in your user session: `echo "export \$(grep -v '^#' /etc/demo/environment | xargs) && env | grep OFFSPOT_DEMO" | tee /etc/profile.d/demo-env.sh`
+  - automatically load the environment data in your user session: `source /etc/demo/environment`
 - setup the demo: run `demo-setup`
 
 ## Tooling
 
-This repository contains various scripts useful to setup / update the demo
+This repository contains various modules and scripts useful to setup / update the demo. Beside the single-use `setup` script, only running `watcher` periodically should be necessary in production. Developers can use individual scripts for each step to inspect output.
 
 ### setup script
 
@@ -51,71 +56,68 @@ This repository contains various scripts useful to setup / update the demo
 
 ### watcher script
 
-- runs forever
-- checks the special image endpoint on imager service (https://api.imager.kiwix.org/auto-images/demo/json)
+- runs once, launched periodically
+- checks the special image endpoint on imager service (https://api.imager.kiwix.org/auto-images/offspot-demo/json)
 - check if target URL has changed
-- call `deploy-script` if it did, otherwise sleeps
+- call `deploy` module if it did
 
-### toggle script
+### toggle module/script
 
 ```sh
-toggle-compose [image|maint]
+offspot-toggle [image|maint]
 ```
 
-- check symlink for active one (and docker ps?)
-- down docker-compose
+- stop docker-compose
 - change symlink
-- up docker-compose
+- start docker-compose
 
-### deploy script
+### deploy module/script
 
 ```sh
 deploy-demo-for http://xxxxx/xyz.img
 ```
 
 - check URL
-- `toggle-compose maint`
+- `offspot-toggle maint`
 - unmount old image `/data`
 - release loop-device
 - remove old image file `/demo/image.img`
-- purge docker images and containers for image
-- download new image `/demo/image.img`
-- prepare-image `/demo/image.img`
-- `toggle-compose image`
+- purge docker images and containers
+- download new image into `/demo/image.img` and check integrity
+- attach image to loop-device
+- mount 3rd partition to `/data`
+- `offspot-prepare /data`
+- attach image
+- `offspot-togglw image`
 
 
-### prepare script
+### prepare module/script
 
 ```sh
-prepare-image /demo/image.img
+offspot-prepare /data
 ```
 
-- setup loop-device
-- mount part3 onto `/data` (allows reusing all fs paths directly)
-- check if already prepared via `/data/demo_prepared`
+- check if already prepared via `/data/prepared.ok`
 - read and parse `/data/contents/dashboard.yaml`
   - read `fqdn` as `orig_fqdn`
   - rewrite metadata for `fqdn=demo.hotspot.kiwix.org`
   - rewrite all `url` and `download.url` for `packages` to replace `orig_fqdn` with `fqdn`
   - rewrite urls in `readers` and `links` as well
 - read and parse /image/image.yaml
-  - pull all OCI images from `oci_images`
-  - read timezome from `offspot.timezone`
-  - set timezone on host????
   - convert `offspot.containers` and write to `/data/compose.yaml`
     - for all volumes:
       - ensure all `source` is relative to `/data`.
       - Otherwise remove bind
       - Unless it's `/var/log` and image is `ghcr.io/offspot/reverse-proxy:` (for metrics)
     - for all services:
       - remove `cap_add` (will break captive portal but not an issue)
-      - if image doesnot start with `ghcr.io/offspot/reverse-proxy:`, remove `ports` else, limit to `80:80` and `443:443`
+      - if image does not start with `ghcr.io/offspot/reverse-proxy:`, remove `ports` else, limit to `80:80` and `443:443`
       - if image starts with `ghcr.io/offspot/captive-portal:` add ports `2080:2080` `2443:2443`
       - remove `privileged`
     - for all environment in all services (exclude `PROTECTED_SERVICES`?:
       - replace `old_fqdn` with `fqdn`
-    - remove any secu-related option that we don't set?
-- touch `/data/demo_prepared`
+  - pull all OCI images from `oci_images`
+- touch `/data/prepared.ok`
 
 ## Kiwix instance
 
@@ -132,9 +134,8 @@ Kiwix is running a demo instance at http://demo.hotspot.kiwix.org
 - Debian
 - node-like setup with bastion
 - docker install (comes with compose)
-- python install (3.12) + venv
-- few apt packages: mount coreutils aria2
-  - `apt install -y mount coreutils aria2`
+- python install (3.12) + venv (in `install.sh`)
+- `mount`, `coreutils` and `aria2` (in `install.sh`)
 - this project installed somewhere
   - `pip install git+https://github.com/offspot/demo@main`
 
@@ -143,7 +144,7 @@ Kiwix is running a demo instance at http://demo.hotspot.kiwix.org
 - Enhance/Remove dirty Python 3.12 installation
 - Rework the dirty systemd manipulations (mainly/only in setup.py)
 - Can access Captive portal (just for UI)? Via :2080 and :2443?
-- _Protect_ the service via a password (provided in-login page? as we want to prevent bots mostly)
+- *Protect* the service via a password (provided in-login page? as we want to prevent bots mostly)
 - Use LXC containers to isolate from host and allow restoring snapshots frequently to prevent any attack from persisting
 - Use Apache Guacamole to isolate the hotpost HTTP service(s) as users would access a VNC-like rendering of it
 - Add an FAQ/doc for end-users (in GH for now)