frugal-iot-server 2.0.8 → 2.0.10

package/{INSTALL-OPENSEARCH.md → docs/INSTALL-OPENSEARCH.md}

@@ -1,25 +1,22 @@
 # Installing OpenSearch, Grafana and Dashboards
 
 This is for **browsing and charting your readings**. All of it is optional - the server and logger work
-without any of it, and the readings are always safe in the CSV files under `data/`.
+without any of it, and the readings are always safe in the CSV files under `data/`, 
+and the client has its own graphing. 
 
 ## What the pieces are
 
-OpenSearch is **two programs**, and it matters which is which:
+OpenSearch is **two programs**:
 
 - **OpenSearch** is the database. It stores and searches the readings, and listens on port 9200.
-- **OpenSearch Dashboards** is a separate web app for searching and charting what is in OpenSearch. It
-  holds no readings: it asks OpenSearch for them, over port 9200, using one login in its own
+- **OpenSearch Dashboards** is a separate web app for searching and charting what is in OpenSearch. 
+  It access readings from OpenSearch at port 9200, using one login in its own
   configuration file. (It also keeps its own saved dashboards *inside* OpenSearch, in an index.)
 
-**Grafana** is a third, unrelated program that makes charts. It can read the server directly
-([GRAFANA.md](GRAFANA.md)), needing no OpenSearch at all.
-
 ## The ways to use it
 
 | | Readings are kept in | You look at them with | Set up |
 |---|---|---|---|
-| **Grafana, reading the server** *(start here)* | the server's CSV files, all of them | Grafana on your computer | [GRAFANA.md](GRAFANA.md); needs no OpenSearch |
 | **(a) OpenSearch on the server** | OpenSearch on the production server | OpenSearch Dashboards on **your own computer** | sections 2, 3, 4, 5 |
 | **(b) OpenSearch on your own machine** | OpenSearch on a machine you run, which the server sends readings to | whatever you like - you run it all | section 6 |
 
@@ -28,9 +25,8 @@ Either of (a) and (b) can be used with Grafana too.
 **None of this is for the Raspberry Pi bridge.**
 
 > **Status:** the Grafana and Mac steps were followed on macOS with Homebrew (OpenSearch 3.9.0,
-> Dashboards 3.9.0, Grafana 13.3.0). The Linux steps, the logins for Dashboards, and the Apache setup
-> are written from OpenSearch's documentation and have **not been run on a Linux server** - correct them
-> where they differ. [Open questions](#open-questions) lists what to check first.
+> Dashboards 3.9.0, Grafana 13.3.0). The Linux steps, the logins for Dashboards, and the Apache setup 
+> have been run on the production server at frugaliot.naturalinnovation.org
 
 We use **OpenSearch**, not Elasticsearch: it is Apache-licensed, installs with Homebrew and apt, and
 Grafana can read it. OpenSearch Dashboards is its fork of Kibana, so Kibana guides are close but not
@@ -38,117 +34,122 @@ identical. (The reasoning is also in a comment above the `OpenSearch` class in f
 `index.js`, in case the decision is revisited.)
 
 How heavy is each? OpenSearch is the heavy one: a Java program with its own 1 GB heap by default.
-Grafana and Dashboards are small by comparison (about 60 MB and 20 MB resident on a Mac, which
+Dashboards are small by comparison (about 60 MB and 20 MB resident on a Mac, which
 under-reports, so read that loosely).
 
----
-
-## 1. On your own computer: Grafana
+## 1. (a) On the server: OpenSearch
 
-On a Mac:
+**Debian or Ubuntu.**
 
+**First, check there is room.** OpenSearch with its default 1 GB heap takes about 1.4 GB of RAM in
+total (measured on a 2.4 GB server, where it became by far the biggest process). Run this *before*
+installing:
 ```sh
-brew install grafana
-brew services start grafana
+free -h
 ```
+The `available` column is what is left for OpenSearch; you want at least 1.5 GB. If you have less, either add
+memory or give OpenSearch a smaller heap (the step before starting it, below). Run it again after
+OpenSearch is started and `available` will, of course, be much lower; `top` (press `M` to sort by
+memory, `q` to quit) shows what is using it.
 
-Open <http://localhost:3000>. Grafana's default login is `admin` / `admin`, and it asks you to change it.
-Then add the Infinity plugin - in Grafana, Administration → Plugins → "Infinity" - or from the shell:
-
+Install the prerequisites
 ```sh
-/opt/homebrew/opt/grafana/bin/grafana cli --homepath /opt/homebrew/opt/grafana/share/grafana \
-  --pluginsDir /opt/homebrew/var/lib/grafana/plugins plugins install yesoreyeram-infinity-datasource
-brew services restart grafana
+sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2
 ```
-
-For other systems, Grafana's own download page has installers for [Windows, Linux and others](https://grafana.com/grafana/download).
-
-Then continue at [GRAFANA.md](GRAFANA.md) to make a token and chart your readings.
-
-To stop it: `brew services stop grafana` (Homebrew restarts it at login until you do).
-
----
-
----
-
-## 2. (a) On the server: OpenSearch
-
-Debian or Ubuntu.
-
-`apt-get` does the installing. The `curl` line just downloads the signing key for OpenSearch's
-repository, which apt needs in order to trust it:
-
+Fetch the signing key for OpenSearch's repository
 ```sh
-sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2
 sudo mkdir -p /etc/apt/keyrings
 curl -fsSL https://artifacts.opensearch.org/publickeys/opensearch-release.pgp \
   | sudo gpg --dearmor -o /etc/apt/keyrings/opensearch.gpg
 ```
+Add OpenSearch's apt repository
+```sh
+echo "deb [signed-by=/etc/apt/keyrings/opensearch.gpg] https://artifacts.opensearch.org/releases/bundle/opensearch/3.x/apt stable main" \
+  | sudo tee /etc/apt/sources.list.d/opensearch-3.x.list
+```
 
-Then add OpenSearch's apt repository - the `3.x/apt` line from
-[their Debian guide](https://docs.opensearch.org/latest/install-and-configure/install-opensearch/debian/),
-which is printed there for your architecture - and install, choosing an admin password now:
-
+Choose a strong password to replace `<strong password>` with below. Installing does not start it yet.
 ```sh
 sudo apt-get update
-sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD='<choose-a-strong-password>' apt-get install opensearch
+sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD='<strong password>' apt-get install opensearch
 sudo systemctl enable opensearch
-sudo systemctl start opensearch
-curl https://localhost:9200 -u 'admin:<that password>' --insecure
 ```
 
-(That last `curl` only checks that it is answering. `--insecure` here means "do not check the
-certificate", because the one it ships with is self-signed.)
+**Set the memory before starting.** It is set in `/etc/opensearch/jvm.options`, which ships with `-Xms1g`
+and `-Xmx1g` (a 1 GB heap). If `free -h` above showed less than 1.5 GB available, change both lines to
+`512m`, which is enough for a little data: all 598,000 readings of the `dev` organization came to about
+35 MB. More heap helps with a lot of history, but the machine needs the whole amount free *beyond* what
+the server, broker, database and logger already use. You can change it later, then
+`sudo systemctl restart opensearch`.
+
+The other settings, in `/etc/opensearch/opensearch.yml`, need no change.
+
+Now start it. This can take a couple of minutes.
+```sh
+sudo systemctl start opensearch
+```
+Check it is answering (`--insecure` means "do not check the certificate", because the one it ships with
+is self-signed):
+```sh
+curl https://localhost:9200 -u 'admin:<strong password>' --insecure
+```
 
 This install **has the security plugin switched on**: HTTPS, a login, and that self-signed certificate.
-The password is only used to set up that demo security configuration. Config is in
-`/etc/opensearch/opensearch.yml` and the memory setting in `/etc/opensearch/jvm.options`.
+The password is only used to set up that demo security configuration.
 
-- **Memory:** the file ships with `-Xms1g` and `-Xmx1g` (a 1 GB heap). Give both lines the same value;
-  more helps with a lot of history, and the machine needs that much free *beyond* what the server,
-  broker and logger use. The data is small: all 598,000 readings of the `dev` organization came to
-  about 35 MB.
 - **If it will not start**, look at `journalctl -u opensearch`. A common cause on Linux is the kernel
   setting `vm.max_map_count` being below 262144; `sudo sysctl -w vm.max_map_count=262144` fixes it until
   reboot, and a line in `/etc/sysctl.d/` makes it permanent.
 - **Leave OpenSearch listening on the machine itself** (the default). Only Apache, below, is open to the
   internet - never port 9200 directly. Check under [Keeping it safe](#keeping-it-safe).
 
-### Tell the server about it
+### Tell the Frugal IoT Server about it
 
-Make `config.d/opensearch.yaml` in the server's directory (a commented example ships there), and restart
-the server:
+Make `config.d/opensearch.yaml` in the server's directory (a commented example ships there),
 
 ```yaml
-opensearch:
-  node: https://localhost:9200       # where THIS server reaches OpenSearch: on this machine
-  username: admin                    # what the forwarder writes readings as
-  password: <the password you chose>
-  insecure: true                     # OpenSearch's demo certificate cannot be checked; fine on this machine
-  admin:                             # the account that makes the per-organization logins (section 4)
-    username: admin
-    password: <the same>
-  public: https://search.example.org # the address people outside reach it at - section 3
+node: https://localhost:9200       # where THIS server reaches OpenSearch: on this machine
+username: admin                    # what the forwarder writes readings as
+password: <the password you chose>
+insecure: true                     # OpenSearch's demo certificate cannot be checked; fine on this machine
+admin:                             # the account that makes the per-organization logins (section 4)
+  username: admin
+  password: <the same>
+public: https://search.example.org # the address people outside reach it at - section 3
 ```
+ and restart the Frugal IoT server:
+ 
+ ```sh
+ sudo service frugaliot restart
+ ```
+
+The lines go at the top level of the file - the file's name already says they are about `opensearch`.
 
-This file is never sent to a browser. Using `admin` for everything is the simplest thing that works, not
+This file is never sent to a browser. `username:` and `password:` at the top must be an account OpenSearch
+knows - the `admin` one you chose when installing - or every send fails with "Response Error" and the
+logger's journal says so. Using `admin` for everything is the simplest thing that works, not
 the best: a role that can only write `frugaliot-*` for the forwarder would be better, and is not yet
 written. Leave `admin:` and `public:` out until you have done sections 3 and 4.
 
 ### Send readings to it
 
-In the dashboard, open the project's back, then the **Forwarders** card, and add **OpenSearch on this
+In the dashboard, open the project's back, then the **Forwarders** card (not the **OpenSearch** card), and add **OpenSearch on this
 server**. There is no address or password to type: they come from the file above. Optionally set *Only
 these topics*, e.g. `dev/lotus/#`; leave it empty to send everything that is logged.
 
-It applies at once, with no restart, and creates what it needs in OpenSearch (an index template that
+Readings are sent in batches every few minutes, so the first ones take a few minutes to show up. It applies at once, with no restart, and creates what it needs in OpenSearch (an index template that
 makes `value` a number) the first time it sends. An organization's administrator can add it for their own
 organization, so only do this if you are happy for them to have their readings in OpenSearch.
 
 ### Loading the history you already have
 
-A forwarder only sends readings from the moment it is switched on. To bring in everything already on
-disk, from the server's directory (safe to repeat, and safe while the server is running):
+A forwarder only sends readings from the moment it is switched on. To bring in what is already recorded,
+open the **Forwarders** card, and on the OpenSearch forwarder's row press **Send earlier readings...**.
+Pick the day to start from (leave it empty for everything), optionally tick *Only count them* to see how
+many there are first, and press **Start**. It runs in the background and the card shows how many it has
+sent so far. It is safe to repeat, and safe while the server is running.
+
+The same thing from a terminal, in the server's directory, if you prefer:
 
 ```sh
 npx --no frugal-iot-backfill-opensearch dev dry-run     # count what would be sent
@@ -158,12 +159,22 @@ npx --no frugal-iot-backfill-opensearch dev 2026-09-01  # only files from that d
 
 ### Looking after it
 
+Run these on the server, in a terminal. `admin:<strong password>` is the login and password you chose when
+installing OpenSearch; `--insecure` is the same "don't check the certificate" as before.
+
+- **See what is there.** One line per index, with its size:
+  ```sh
+  curl -s 'https://localhost:9200/_cat/indices/frugaliot-*?v' -u 'admin:<strong password>' --insecure
+  ```
 - **Old months.** Readings go into one index per organization per month, named like
-  `frugaliot-dev-2026.09`. To drop a month: `curl -X DELETE https://localhost:9200/frugaliot-dev-2026.02 -u admin:... --insecure`.
-  The CSV files are untouched.
+  `frugaliot-dev-2026.09` (that name is in the first column above). To drop one:
+  ```sh
+  curl -X DELETE 'https://localhost:9200/frugaliot-dev-2026.02' -u 'admin:<strong password>' --insecure
+  ```
+  The CSV files are untouched, so nothing is lost for good.
 - **A gap while OpenSearch was down.** The forwarder does not retry a batch it could not send; the CSV
-  files have everything, and the backfill above fills the gap.
-- **Starting afresh.** Delete the indices (`frugaliot-*`) and run the backfill again.
+  files have everything, and *Send earlier readings* (above) fills the gap.
+- **Starting afresh.** Delete each index listed above, as for an old month, and send the earlier readings again.
 
 ---
 
@@ -171,15 +182,25 @@ npx --no frugal-iot-backfill-opensearch dev 2026-09-01  # only files from that d
 
 ## 3. (a) Apache: HTTPS in front of OpenSearch
 
-Dashboards on someone's computer reaches OpenSearch across the internet, so its login and the readings
-must travel over HTTPS. OpenSearch itself stays on the machine (port 9200, loopback); **Apache is put
-in front of OpenSearch**, not in front of Dashboards. It is the same Apache that already sits in front
-of this server - add one more site to it, on its own name, e.g. `search.example.org`.
+Dashboards on someone's computer reach OpenSearch across the internet, it needs HTTPS. 
+
+While opensearch ships with HTTP and some self-signed certificates, for most practical installs it will be behind an Apache proxy.
 
+We'll add a domain name to it - e.g. `opensearch.naturalinnovation.org`
+
+Add components needed for Apache
 ```sh
 sudo a2enmod ssl proxy proxy_http headers
 ```
 
+You need a DNS record pointing `search.example.org` (use your own name) at this server, and a
+certificate for it, made the way you made the server's own, e.g. `sudo certbot certonly --apache -d search.example.org`.
+
+Your certificate may be a wildcard one (e.g. `*.example.org`) you already have; then use its files in
+the two `SSLCertificate...` lines below.
+
+Make a new file for this site, `/etc/apache2/sites-available/opensearch.conf` (Debian and Ubuntu keep
+every Apache site in that folder; it is separate from your existing site's file), with:
 ```apache
 <VirtualHost *:443>
   ServerName search.example.org
@@ -205,10 +226,17 @@ sudo a2enmod ssl proxy proxy_http headers
   </LocationMatch>
 </VirtualHost>
 ```
+Switch the site on, then test and reload Apache:
+```sh
+sudo a2ensite opensearch
+sudo apachectl configtest && sudo systemctl reload apache2
+```
+Check from your own computer:
+`curl https://search.example.org` should answer 401 (it wants a login) - not a block of JSON, or HTML, and not a
+timeout. 
 
-Then `sudo apachectl configtest && sudo systemctl reload apache2`. Check from your own computer:
-`curl https://search.example.org` should answer 401 (it wants a login) - not a block of JSON, and not a
-timeout. Put the address in `public:` in `config.d/opensearch.yaml`.
+Put the address (with the `https://`) in `public:` in `config.d/opensearch.yaml`, with the `admin:` lines
+from section 1, then restart the server so it reads the file: `sudo systemctl restart frugaliot`.
 
 Port 9200 itself stays closed to the network (firewall) - only Apache's 443 is open.
 
@@ -256,17 +284,80 @@ on a Mac), start it (`brew services start opensearch-dashboards`) and open <http
 
 ```yaml
 opensearch.hosts: [ "https://search.example.org" ]
-opensearch.username: "frugaliot_dev"
+opensearch.username: "frugaliot_dev_mitra"
 opensearch.password: "..."
 opensearchDashboards.index: ".kibana_dev"
-opensearch.requestHeadersAllowlist: [ authorization ]
+opensearch.requestHeadersAllowlist: []
+opensearch.customHeaders: { authorization: "Basic <the login, encoded - the card writes this line for you>" }
 ```
 
 The `opensearchDashboards.index` line is what gives the organization its own place to keep saved
-dashboards; without it Dashboards uses `.kibana`, which this login cannot touch. Then, in Dashboards:
-**Dashboards Management → Index patterns → Create**, enter `frugaliot-*`, and choose `@timestamp` as the
+dashboards; without it Dashboards uses `.kibana`, which this login cannot touch. The last two lines stop Dashboards asking your browser for a login: Dashboards uses the login above
+only for its own housekeeping, so they add the same login to every request. Copy the whole block from
+the card - the `Basic ...` line is the username and password encoded, which you cannot easily write by
+hand. Nothing is typed when you open Dashboards. Keep Dashboards on your own computer: it listens on
+`localhost` by default, and anyone who can reach its port acts as this login. 
+
+Open opensearch - by default it will be on `http://localhost:5601`
+
+Then, in Dashboards:
+**Dashboards Management → Index patterns → Create**, enter `frugaliot-<org>-*` (e.g. `frugaliot-dev-*`; your login can read only your own organization's), and choose `@timestamp` as the
 time field.
 
+If it says the pattern **"doesn't match any indices"**, OpenSearch has no readings for your organization yet:
+the forwarder (section 2, "Send readings to it") is not added, or nothing has been sent. Readings only
+arrive once the forwarder is on, so send the earlier ones as in "Loading the history you already have".
+You can check from your own computer with the login that is in the Dashboards file - the generated one the card
+showed (not the OpenSearch `admin` password). This reads it from the file on a Mac; use your own address
+and organization:
+```sh
+curl -s -u "$(awk -F'"' '/^opensearch.username/{u=$2} /^opensearch.password/{p=$2} END{print u":"p}' /opt/homebrew/etc/opensearch-dashboards/opensearch_dashboards.yml)" 'https://search.example.org/frugaliot-dev-*/_count'
+```
+`"count":0` with `"total":0` shards means none are there; a number above 0 means they are.
+
+If it says **"OpenSearch Dashboards server is not ready yet"**, look at its log
+(`/opt/homebrew/var/log/opensearch-dashboards.log` on a Mac): it names what it could not do. A
+`security_exception ... no permissions for [...]` line means the organization's role on the server is
+missing that permission - press **Replace the password** on the OpenSearch card once (the server rewrites
+the role), then restart Dashboards. A stalled "Another OpenSearch Dashboards instance appears to be
+migrating" means a first start was interrupted; as the message says, delete the index it names
+(`.kibana_<org>_1`, see "Looking after it" for the command) and restart it.
+
+### Seeing your readings as a chart
+
+Checked step by step against OpenSearch Dashboards 3.9 in a browser. Each reading has these fields:
+`value` (the number), `@timestamp`, and `topic` split into `node` (the device), `module` and `leaf`
+(e.g. `temperature`). First look at **Discover** (☰ menu, top left): with `frugaliot-<org>-*` chosen you
+see a bar chart of how many readings arrived, and the readings below it.
+
+Now a chart of one kind of reading, a line per device:
+
+1. Go to **Visualize** (<http://localhost:5601/app/visualize>) and press **Create new visualization**.
+   Choose **Line**, then your `frugaliot-<org>-*` index pattern.
+2. At the top right, click the calendar icon beside the time and choose **Last 24 hours**. The default
+   is the last 15 minutes, which is nearly always empty.
+3. In the right-hand panel, under **Metrics**, open **Y-axis**. Set **Aggregation** to **Average**
+   (type "Average" and pick it). **Field** fills itself in with `value`.
+4. Under **Buckets** press **Add**, choose **X-axis**, and set **Aggregation** to **Date Histogram**
+   (**Field** fills itself in with `@timestamp`). Press **Update** at the bottom right.
+   You now have one line, but it averages every kind of reading together (temperature, humidity,
+   wifi...), so the numbers mean nothing.
+5. In the search bar above the chart type `leaf:temperature` and press Enter. Now only temperatures
+   are charted.
+6. Under **Buckets** press **Add** again, choose **Split series**, set **Sub aggregation** to **Terms**
+   and **Field** to `node`. Press **Update**. You get one line per device, with its name in the legend.
+7. Press **Save** (top right), give it a title such as `Temperature by device`, and **Save**.
+
+Put it on a dashboard:
+
+1. Go to **Dashboards** (<http://localhost:5601/app/dashboards>) and **Create new dashboard**.
+2. Press **Add** (top right), click your chart in the list, and close the list with the **X**.
+3. Press **Save**, give it a title, switch on **Store time with dashboard** (otherwise it opens on the
+   last 15 minutes and looks empty), and **Save**.
+
+To chart something else, change `temperature` in step 5 to `humidity` or another `leaf`, or leave the
+search empty and split by `topic` instead of `node`.
+
 You can use the same login in **Grafana** instead, with its OpenSearch data source and the same address.
 
 ---
@@ -368,8 +459,7 @@ and only your own machine can reach it. Make `config.d/opensearch.yaml` in your
 just:
 
 ```yaml
-opensearch:
-  node: http://localhost:9200
+node: http://localhost:9200
 ```
 
 and restart the server. The Forwarders card then offers **OpenSearch on this server**. The Dashboards
@@ -397,11 +487,7 @@ To stop them: `brew services stop opensearch-dashboards opensearch`.
 
 Please add what you find:
 
-- **The Linux steps have not been run**: the exact `apt` repository line, and the Apache site above.
-- **The role in section 4 is untried.** Its actions are the ones OpenSearch's documentation names for
-  Dashboards, and may be missing one - symptoms are Dashboards failing to start, or an index pattern that
-  cannot be created. If so, OpenSearch's log names the refused action; add it to `roleFor` in
-  `lib/opensearch-access.js`.
+- **The Linux steps have not been run for the opensource-dashboards**: the exact `apt` repository line, and the Apache site above.
 - **`opensearchDashboards.index`** is meant to give each organization its own saved-objects index. Check
   that two organizations' Dashboards do not see each other's saved dashboards, and that neither can open
   the other's `.kibana_<org>`.

package/docs/OPENWRT.md

@@ -0,0 +1,208 @@
+# Running a Frugal IoT server on an OpenWrt router
+
+**Status: worked once, on one router, after fixes.** The Raspberry Pi installation
+([INSTALLATION.md](INSTALLATION.md)) is proven; this is the same thing re-done for OpenWrt. The first
+real run - an OpenWrt One, OpenWrt 25.12.5, see [Tested on](#tested-on) - needed five attempts and
+found ten problems, which are fixed or described below. Expect the next router to find more. This
+document says what a router needs, how to prepare it, gives two scripts, and says what to send back.
+
+## What you are installing
+
+A Frugal IoT server is three programs on one machine:
+
+* **mosquitto**, an MQTT broker. Small sensor boards (ESP32s) publish readings to it, and the
+  dashboard in your browser listens to it.
+* **the Frugal IoT server**, a Node.js program. It serves the dashboard on port 8080, keeps the
+  user logins and settings in an SQLite database, and writes every reading to disk.
+* nothing else. No cloud, no internet needed once it is installed.
+
+The router is simply where they run. It does not stop being a router.
+
+## What the router needs
+
+Run the preflight script (below) and it checks every line of this table for you.
+
+| | Needed | Why |
+| --- | --- | --- |
+| **CPU** | **aarch64 or x86_64.** 32-bit ARM might work. MIPS will not. | OpenWrt's `node` package is only built for some CPUs, and the database module (`sqlite3`) is a compiled binary that has to exist for that CPU and for OpenWrt's C library (musl). Both are most likely on 64-bit. |
+| **Memory** | 512 MB or more (256 MB at the very least) | The server uses about 250 MB once running. |
+| **Storage** | **About 400 MB free** on ext4, f2fs or btrfs | The software is ~100 MB; npm needs room to work; readings accumulate. **Most routers' own flash is far too small**, so this means a USB stick or SSD, set up as extroot or just mounted, and `--dir` pointing at it. Not FAT, exFAT or NTFS: the install needs symlinks and Unix permissions. The image may also lack the USB storage driver - see [Preparing the router](#preparing-the-router). |
+| **Node.js** | **20.17 or later**, and npm | From OpenWrt's feed if it has one - **OpenWrt 25.12 has none for aarch64**, in which case it is unpacked by hand from a musl build ([how](#if-the-feed-has-no-node)). The preflight and the installer accept either. |
+| **mosquitto** | A build with **websockets** | The browser dashboard connects over websockets. If the router's mosquitto has none, the dashboard cannot work. |
+| | Ideally the **dynamic security plugin** | It gives every node and every user its own broker password. Without it the server falls back to one shared password per organization: it works, but it is the older and weaker scheme. |
+| **Network** | Internet access while installing | opkg and npm download from their own servers. |
+| **Free ports** | 1883 (nodes), 9012 (dashboard websocket), 8080 (dashboard) | Nothing on OpenWrt uses these by default; LuCI is on 80/443. |
+
+Better to have, not required: a fixed LAN address (a router has one already), and a drive that
+tolerates constant small writes - the server logs readings all day, which is hard on a cheap USB stick.
+
+## Preparing the router
+
+Two things a router often lacks, both found on the first real run. Commands are shown for `apk`
+(OpenWrt 25.12 and later); on older releases use `opkg install` instead of `apk add`.
+
+### A drive the router can see
+
+The preflight tells you when none is visible. A USB drive formatted ext4 was invisible on the test
+router because the image carried no USB storage driver:
+
+```sh
+apk add kmod-usb-storage kmod-fs-ext4 block-mount
+block info                          # is the drive listed now? what is it called?
+block detect > /etc/config/fstab    # NOTE: replaces your mount configuration - if you already have
+block mount                         #   mounts there, add the new one by hand (LuCI: System > Mount Points)
+df -h /mnt/sda1
+```
+
+Check that the drive is mounted again after a reboot (`uci show fstab`, or LuCI's Mount Points), or
+the server will not find its files and will not start.
+
+### If the feed has no node
+
+The preflight's feed check says `no node package in this feed` when this applies. Node.js publishes
+musl builds, which is what OpenWrt uses, at <https://unofficial-builds.nodejs.org/download/release/>.
+Pick a version of 20.17 or later (24.9.0 worked) and the file for your CPU: `linux-arm64-musl` for
+aarch64, `linux-x64-musl` for x86_64. **Take the `.tar.gz`, not the `.tar.xz`** - BusyBox `tar` cannot
+unpack xz. Put it on the drive, not the router's flash:
+
+```sh
+cd /mnt/sda1
+wget https://unofficial-builds.nodejs.org/download/release/v24.9.0/node-v24.9.0-linux-arm64-musl.tar.gz
+tar xzf node-v24.9.0-linux-arm64-musl.tar.gz
+for t in node npm npx; do ln -sf /mnt/sda1/node-v24.9.0-linux-arm64-musl/bin/$t /usr/bin/$t; done
+apk add libstdcpp6 libatomic1       # the musl build needs both
+node -v; npm -v
+```
+
+If `node -v` says a library is missing, that is the `apk add` line. The preflight and installer then
+see node on the router and do not look for a package.
+
+## Doing it
+
+You need `ssh` access to the router as root. On the router, fetch the two scripts from the `main` branch:
+
+```sh
+B=https://raw.githubusercontent.com/mitra42/frugal-iot-server/main/scripts
+wget -O openwrt-preflight.sh $B/openwrt-preflight.sh
+wget -O install-openwrt.sh   $B/install-openwrt.sh
+```
+
+If `wget` complains about https, the router has no TLS support for it yet
+(`apk add ca-bundle libustream-mbedtls`, or `opkg update && opkg install ...` on older releases), or download the files on your computer
+and copy them across with `scp`.
+
+### 1. Preflight - on each candidate router
+
+```sh
+sh openwrt-preflight.sh --dir /mnt/sda1/frugal-iot --install 2>&1 | tee preflight.txt
+```
+
+* `--dir` is where you intend to put the server: a path on the drive. The default is `/opt/frugal-iot`.
+* Without `--install` it only reads things, and refreshes the package list. **With `--install` it
+  installs node, mosquitto and the other packages**, after asking, so that it can try mosquitto and
+  sqlite3 for real rather than guess. That is the same set the installer would put there anyway, but it
+  does use the router's own flash: it prints how much is free first. If the flash is nearly full, run
+  it without `--install` first.
+* It ends with `PASS`/`WARN`/`FAIL` counts and a verdict. **Please send the whole of `preflight.txt`
+  for every router you try**, including the ones that fail - which ones fail, and why, is the most
+  useful thing this stage can tell us.
+
+Which router to choose is then mostly: one with no `FAIL`, a USB port with a decent drive in it, and
+512 MB or more.
+
+### 2. Install - on the one you pick
+
+```sh
+sh install-openwrt.sh --org myfarm --name "My Farm" --email you@example.com \
+     --phone +61123456789 --dir /mnt/sda1/frugal-iot
+```
+
+* `--org` is 1-10 lower-case letters or digits. It becomes the first part of every MQTT topic, and
+  the sensor boards must be flashed with the same one. Pick something you will keep.
+* Passwords you do not give are generated and printed at the end. The whole run is also logged to
+  `/root/frugal-iot-install-<date>.log` (readable only by root; the generated passwords are in it).
+* `--dry-run` checks the arguments and the router and says what it would do, changing nothing.
+* It is safe to run again after a failure: steps already done are skipped. Give it the **same**
+  `--org` and `--dir` as before - a different `--org` creates a second organization. Passwords already
+  set are left alone, and the summary says "unchanged" rather than printing a made-up one.
+* It runs the server as root, as most OpenWrt services do. `--user frugal` creates and uses a
+  separate account instead, which is tidier but is another thing that has not been tried.
+
+When it finishes it prints the dashboard address and the settings the sensor boards need.
+
+### 3. If something goes wrong
+
+Send back:
+
+1. `preflight.txt`
+2. the install log (`/root/frugal-iot-install-*.log`) - or just the end of the terminal output
+3. `logread -e frugaliot | tail -50` and `logread -e mosquitto | tail -50`
+4. the output of `apk list -I | grep -E 'mosquitto|node|sqlite|zsh'` (`opkg list-installed | grep ...`
+   on older releases)
+
+## What is different from a Raspberry Pi, and why it might fail
+
+The installer is the Pi one, redone, so these are the places it can be wrong:
+
+* **No systemd.** The service is a procd init script, `/etc/init.d/frugaliot`. Control it with
+  `service frugaliot restart`. Logs go to the system log: `logread -e frugaliot`.
+* **`/var` is RAM.** On OpenWrt `/var` is `/tmp`, emptied at every reboot. The broker's password file
+  and account database would normally live in `/var/lib/mosquitto`, which would lose every account on
+  restart, so the installer keeps them in `/etc/mosquitto/state` and points the configuration there.
+  It also moves mosquitto's own persistence (the retained values) there if it was set to a
+  RAM path; the original configuration is kept as `/etc/mosquitto/mosquitto.conf.pre-frugal`.
+* **No bash, no zsh, no sudo, no apt.** The installer is plain `sh` and installs zsh itself (the
+  server's own commands are zsh scripts). BusyBox lacks `install(1)` (it is in `coreutils-install`),
+  which stopped the first run, so the installer places files with `cp`, `chown`, `chmod` and `mv`
+  instead; and its `tar` cannot unpack `.xz`. `stat`, `sed`, `grep` and `su` worked.
+* **The sqlite3 module.** The most likely single failure. If a binary does not exist for your CPU
+  and musl, `npm install` will try to compile it, and there is no compiler. The installer stops there
+  with the error. A fix exists (compile it on another machine, or use a build environment) but it
+  is a different project.
+* **The mosquitto package.** Which parts OpenWrt builds in - websockets, the dynamic security plugin,
+  `mosquitto_ctrl`, `mosquitto_passwd` - is the main thing nobody here knows. The preflight tries each
+  one, and the installer lists every mosquitto package the feed offers into the log.
+* **No WiFi fallback network.** On the Pi, a setup network is raised if its WiFi is lost. A router is
+  the access point, so this is skipped.
+* **Time.** Routers without a battery clock start at an old date until NTP runs. The server stamps
+  readings when they arrive, so check the router has the right time.
+
+## After it is running
+
+* **Do not open the ports to the internet.** OpenWrt accepts LAN connections and refuses WAN ones by
+  default; leave 1883, 9012 and 8080 that way. HTTPS (needed for over-the-air firmware updates to the
+  boards) is not covered here.
+* **Upgrading:**
+  ```sh
+  cd /mnt/sda1/frugal-iot && npm update frugal-iot-server && service frugaliot restart
+  ```
+  (and re-run `install-openwrt.sh` with the same arguments afterwards, which brings the broker
+  configuration up to date.)
+* **If `http://<router>:8080/` answers 404** (the dashboard at `/dashboard` may still work), the
+  server cannot find its own web pages. An install whose `frugal-iot-init` failed part-way and was
+  re-run - as on the first OpenWrt run, before `init` was fixed - keeps a `config.d/server.yaml`
+  with `publicdir: ./public`. Set these in `<install dir>/config.d/server.yaml`, then
+  `service frugaliot restart`:
+  ```yaml
+  htmldir: ./node_modules/frugal-iot-client
+  nodemodulesdir: ./node_modules
+  publicdir: ./node_modules/frugal-iot-server/public
+  privatedir: ./node_modules/frugal-iot-server/private
+  ```
+  Without `publicdir` the home page, `/about.html` and the PWA's `service-worker.js` are missing too.
+* **`npx --no frugal-iot-diagnostic`** was written for systemd and will report some things that do
+  not apply here. Treat it as a hint, not a verdict.
+* **Removing it:**
+  ```sh
+  service frugaliot stop; /etc/init.d/frugaliot disable; rm /etc/init.d/frugaliot
+  rm -rf /mnt/sda1/frugal-iot                     # your install directory: this deletes the readings too
+  rm /etc/mosquitto/conf.d/frugal-iot.conf /etc/mosquitto/aclfile; rm -rf /etc/mosquitto/state
+  cp /etc/mosquitto/mosquitto.conf.pre-frugal /etc/mosquitto/mosquitto.conf   # if it exists
+  /etc/init.d/mosquitto restart
+  ```
+
+## Tested on
+
+| Date | Router | OpenWrt | Node | Server | Result |
+| --- | --- | --- | --- | --- | --- |
+| 2026-11 | OpenWrt One (Banana Pi), MediaTek Filogic, aarch64_cortex-a53, 986 MB; USB drive, ext4, mounted at `/mnt/sda1` | 25.12.5 with LibreMesh, `apk`, kernel 6.12.94 | v24.9.0 and npm 11.6.0, unpacked by hand (no node in the aarch64 feed) | 2.0.8 | Installed and running: broker (websockets and dynamic security both present), organization, procd service, dashboard. Took five runs: no USB storage driver; no node package; no `install` command; `frugal-iot-init` failing on `extras/grafana`, which also left `server.yaml` unconfigured and made `/` answer 404. All now handled by the scripts or described above, except the `init` fix, which needs a server release to reach a router. |

package/extras/frugaliot.service

@@ -1,6 +1,6 @@
 # Systemd unit for the Frugal IoT server.
 #
-# As shipped this matches the Raspberry Pi installation in INSTALLATION.md: user "pi", installed
+# As shipped this matches the Raspberry Pi installation in docs/INSTALLATION.md: user "pi", installed
 # with npm into /home/pi/frugal-iot. If that is what you have, install it unedited:
 #   sudo cp extras/frugaliot.service /etc/systemd/system/frugaliot.service
 #   sudo systemctl daemon-reload

package/extras/mosquitto.conf

@@ -6,7 +6,7 @@ protocol websockets
 # Kept under /var/lib/mosquitto, which belongs to the mosquitto user, rather than /etc/mosquitto,
 # which belongs to root. Both the broker and mosquitto_passwd warn unless the file belongs to
 # whoever opened it, and mosquitto_passwd also writes a temporary backup beside it, so the
-# directory has to be writable by that same user. See INSTALLATION.md step A5.
+# directory has to be writable by that same user. See docs/INSTALLATION.md step A5.
 password_file /var/lib/mosquitto/passwords
 
 # Which topics each account may reach. Without this, every account that can log in can publish and