taler-windows

CLAUDE.md (19325B)

---

 # CLAUDE.md
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## What this is
 
 A Windows **installer** for the GNU Taler merchant backend. There is no Taler source code
 here — the backend is installed from the `deb.taler.net` APT repository *inside WSL*. This
 repo is only the orchestration layer: an NSIS wizard that collects user choices, a batch
 script that drives `wsl.exe`, and three bash scripts that run inside the WSL distro.
 
 Twelve tracked files, no build system, no test suite. It is also the odd one out in the
 `/home/claude` workspace: nothing here links against `~/target`, and the build-order and
 `make install` rules in the parent `CLAUDE.md` do not apply.
 
 ## Building
 
 ```sh
 makensis taler-installer-taler.nsi      # produces taler-installer.exe (gitignored)
 ```
 
 `makensis` is not installed in this workspace, but it does **not** have to be: the Debian
 package can be unpacked into the scratchpad without root and run from there, which does
 compile this installer (verified with 3.11). That catches every syntax error, missing
 `LangString` and encoding problem — do it instead of reviewing the `.nsi` by eye:
 
 ```sh
 cd "$SCRATCH" && apt-get download nsis nsis-common
 for f in *.deb; do dpkg-deb -x "$f" root; done
 cd /home/claude/taler-windows
 NSISDIR="$SCRATCH/root/usr/share/nsis" "$SCRATCH/root/usr/bin/makensis" -WX \
     taler-installer-taler.nsi && rm -f taler-installer.exe
 ```
 
 Only *running* the result needs Windows with WSL. Required at compile time in the same
 directory: `logo-header.ico`, `logo-header.bmp`, `logo-welcome.bmp`, and the four scripts
 listed in the `File` directives.
 
 ## Control flow
 
 ```
 taler-installer.exe  (NSIS, RequestExecutionLevel admin)
   wizard pages: Welcome → Directory → Distro → Domain → ReverseProxy → INSTFILES
   Section "Install Taler-Merchant"  installs the 4 scripts to $INSTDIR, then:
      setup-wsl-debian.bat 1   ""            <distro>                 → steps 1 only
      setup-wsl-debian.bat ALL ""            <distro>                 → steps 1..8
      setup-wsl-debian.bat 8   <domain>      <distro> <proxy_mode>     → step 8 only
   post-install pages: AskExternalDB → DBUrl  → calls test-db.sh / set-db.sh in WSL
   .onGUIEnd: restarts apache2, opens http(s)://<domain> in the browser
 ```
 
 `setup-wsl-debian.bat` is a **step dispatcher**: `%1` is a step number (`1`-`8`) or `ALL`.
 It `goto`s the matching `:stepN` label and each step ends with
 `if not "%STEP%"=="ALL" exit /b`, so a numeric argument runs one step and `ALL` falls
 through all of them. Arguments are positional: `STEP DOMAIN DISTRO PROXY_MODE`.
 
 The steps: (1) enable `Microsoft-Windows-Subsystem-Linux` + `VirtualMachinePlatform`,
 `wsl --update`; (2) `wsl --install -d <distro>`; (3) create the `taleruser` account,
 grant it `NOPASSWD` sudo, make it the default in `/etc/wsl.conf`, terminate the distro to
 apply; (4) add it to `www-data`; (5) copy the three `.sh` files through `%TEMP%` into
 `/home/taleruser/taler-installer` via `type | wsl tee`, `dos2unix`, `chmod +x`;
 (6) verify format/permissions; (7) `wsl --shutdown`, then run
 `install-taler-from-apt.sh`; (8) install Apache and run `taler-merchant-rproxy-setup`.
 
 `install-taler-from-apt.sh` is likewise **multi-mode on `$1`**: `8 <domain>` does the
 HTTPS reverse proxy only, `http <domain>` the HTTP-only proxy only, and no recognised first
 argument means the full install (postgres, Taler APT repo keyring for the detected
 Debian/Ubuntu codename, `taler-merchant`, certbot, `taler-merchant-dbconfig`, enable the
 systemd units). Both proxy branches are currently dead from the batch path, because step 8
 calls `taler-merchant-rproxy-setup` itself.
 
 Fixed identities the scripts assume everywhere: WSL user `taleruser`, Taler DB role
 `taler-merchant-httpd`, scripts at `/home/taleruser/taler-installer/`.
 
 ## The contract with the taler-merchant package
 
 Most of this installer's history of breakage came from fighting the Debian package
 instead of using it, so know what `taler-merchant` already provides:
 
 - **`/etc/taler-merchant/taler-merchant.conf` is an entry point, not a settings file.**
   It carries `[paths]` and three include directives: `@inline-matching@ conf.d/*.conf`
   (which is where `[merchant] SERVE = systemd` lives), `@inline@ overrides.conf`, and
   `@inline-secret@ merchantdb-postgres ../secrets/merchant-db.secret.conf`.
   **Put overrides in a `conf.d/` drop-in**, never in this file.
   Overwriting it is *not* immediately fatal — measured, not assumed: the defaults under
   `/usr/share/taler-merchant/config.d/` still supply `SERVE = tcp` and
   `CONFIG = postgres:///taler-merchant`, and systemd socket activation overrides
   `SERVE = tcp` anyway, so the backend still answers. What is lost is everything an
   administrator puts under `/etc/taler-merchant`: every `conf.d/` drop-in, `overrides.conf`,
   and the database secret are silently no longer included.
 - **`SERVE` must be `tcp`, `unix` or `systemd`** (`exchange/src/mhd/mhd_config.c:194`);
   if it resolves nowhere at all, `taler-merchant-httpd` aborts with *"serve type (tcp,
   unix or systemd) required"*. When `LISTEN_FDS` is set, systemd activation wins over
   `SERVE` and only logs a warning. There is no `UNIX_DOMAIN_SOCKETS` option anywhere in
   the Taler codebase.
 - **The backend is socket-activated.** `taler-merchant-httpd.socket` listens on
   `/run/taler-merchant/httpd/merchant-http.sock` (`taler-merchant-httpd:www-data`, mode
   0660) and the service has `Requires=` it. Enable the *socket* (or the target), not the
   service. There is no need for a TCP port such as 8888.
 - **The package ships the Apache vhost** at `/etc/apache2/sites-available/taler-merchant.conf`,
   already proxying to that unix socket, with `%%your.domain%%` placeholders that
   `taler-merchant-rproxy-setup` substitutes.
 - **The database URI** goes in `secrets/merchant-db.secret.conf` as
   `[merchantdb-postgres] CONFIG=postgres://...`.
 
 `taler-merchant-rproxy-setup` (in the `merchant` checkout) accepts **only** `--domain`,
 `--nginx|--apache`, `--httponly|--httpsonly` and `-h`. Any other argument is a hard
 `exit 1`. It runs `certbot certonly --webroot -w /var/www/html`, so plain `certbot` is
 the only certbot package needed — **never** `python3-certbot-nginx`, which `Depends: nginx`
 and leaves nginx holding port 80 so the apache2 installed in step 8 cannot start.
 
 ## Logs
 
 Scattered, and worth knowing before debugging a user report:
 
 | Path | Written by |
 | --- | --- |
 | `C:\Users\Public\install.log` | the `.nsi` itself, via `TalerLog` (truncated at each start) |
 | `C:\Users\Public\taler-bat.log` | `setup-wsl-debian.bat` (truncated at each start) |
 | `C:\Users\Public\taler-sh.log` | `install-taler-from-apt.sh` (via `exec > >(tee -a)`) |
 | `C:\Users\Public\install-bat.log` | copied out of WSL at the end of step 7 |
 | `/home/taleruser/taler-installer/install-sh.log`, `test-db.log` | the bash scripts |
 | `/tmp/dbtest.log` | `test-db.sh` |
 
 `install.log` is the Windows-side timeline that `readme.txt`, `MSG_INSTALL_FAILED` and
 `.onInstFailed` have always promised: the machine and Windows build, the four wizard
 answers, the exit code of every `nsExec` call, the reverse-proxy probe, the verdict, and a
 closing list of the other log paths. It exists because when WSL is what failed, every log
 in the table below it is unreachable. Rules for extending it:
 
 - **Write through `${TLog}` (log only) or `${TSay}` (log *and* details view),** never a
   bare `DetailPrint` for anything diagnostic. `TalerLog` reopens the file per line on
   purpose — the installer can be killed inside a ten-minute `nsExec` call, and what was
   written before that has to already be on disk.
 - **Nothing secret may be written there.** `C:\Users\Public` is readable by every account
   on the machine. The external-database URL carries a password, so it goes through
   `RedactDbUrl` (drop everything through the last `@`) before it reaches either the log or
   the details view; `test-db.sh` does the same with `${1##*@}` for its own two logs.
 - **Do not log the `[2/8]`..`[6/8]` lines.** They are cosmetic `DetailPrint`s; all of that
   work actually happens in the single `setup-wsl-debian.bat ALL` call, and a log claiming
   six steps that never individually ran would be worse than no log.
 - `nsExec::ExecToLog` pushes one value, `ExecToStack` pushes the output *and then* the exit
   code, so the latter needs two `Pop`s (verified in `Contrib/nsExec/nsexec.c`; it pushes a
   single value only when it cannot build a command line at all, which needs an empty
   command string). Several calls here used to pop nothing and both lost the diagnostic and
   left entries on the global stack.
 
 ## Test harness
 
 There is a working harness on `tripwire.taler.net` under `/srv/winstall-test`
 (not in this repo yet). It is the only way these scripts get exercised, since nothing
 here can run on the development workstation.
 
 ```
 harness/run-debian-test.sh <fresh|twice|reinstall> <ssh-port> <repo-dir> <domain> [label]
 ```
 
 It boots a throwaway Debian 13 cloud image under qemu (user-mode networking, qcow2
 overlay destroyed afterwards), creates `taleruser` the way the batch file would, runs
 `install-taler-from-apt.sh` plus `taler-merchant-rproxy-setup`, and asserts the result —
 ending with a real `GET /config` both over the backend's unix socket and through Apache.
 `twice` runs the installer a second time on a dirty system; `reinstall` purges
 `taler-merchant` in between. Point `<repo-dir>` at a checkout of `master` or of a fix
 branch to get a before/after.
 
 Two traps cost time when extending it: `ssh` inside the driver needs `-n` or it eats the
 script's stdin and hangs forever, and assertion patterns must use `grep -F` — `[paths]`
 as a regex is a character class that matches almost any line.
 
 ## Verified end to end on Windows
 
 Three scenarios, each from a fresh overlay of a clean Windows 11 Enterprise
 Evaluation (build 26300) with the WSL features *disabled* and no WSL runtime --
 i.e. a real first install.  All three pass 14/14, ending with
 `http://localhost/config` answered **from Windows**, which is what a merchant's
 browser hits:
 
 | scenario | what it does | result |
 | --- | --- | --- |
 | `fresh` | enable features, reboot, MSI bootstrap, distro + user, Taler, HTTP proxy | 14/0 |
 | `twice` | the above, then the whole installer again over existing state | 14/0 |
 | `reinstall` | the above, then `wsl --unregister` and install again | 14/0 |
 
 Run them with `harness/win-test.sh run <fresh|twice|reinstall>`; they use
 separate ports, overlays and firmware vars, so all three run in parallel.
 
 Two traps when editing the batch file, both of which silently aborted a run:
 `cmd` parses `%~` substitutions **even inside `::` comments**, and `start`,
 `timeout` and `pause` all refuse to run with redirected stdin.
 
 ## What the Windows VM proved
 
 Measured on a clean Windows 11 Enterprise Evaluation (build 26300, 26H2) under
 qemu/KVM, not inferred:
 
 - **Step 1 is fine.** Both optional features go `Disabled` -> `Enabled`, the
   reboot gate works, and the machine comes back.
 - **WSL2 itself runs** in that nested setup: `vmmemWSL` live, `wsl -l -v`
   reporting `Debian / Running / VERSION 2`. WSL prints *"nested virtualization is
   not supported on this machine"*, which concerns nesting *inside* WSL and is not
   fatal.
 - **`cmd`'s `start` and `timeout` refuse redirected stdin**, printing
   *"Input redirection is not supported, exiting the process immediately"*. nsExec
   runs this batch file exactly that way, so `wsl --update` never executed and all
   five `timeout` delays were silent no-ops. Use `ping -n N 127.0.0.1 >nul` for a
   delay in this file, never `timeout`.
 - **`wsl --install -d <distro>` blocks on an invisible prompt** --
   *"Please create a default UNIX user account"* -- observed hung for 54 minutes.
   `--no-launch` is required; step 3 creates `taleruser` itself anyway.
 - **The in-box `wsl.exe` is only a stub.** Before the WSL runtime is present it
   answers *"The Windows Subsystem for Linux is not installed"* to every form
   except a bare `--install`, prints no `--help` at all, and cannot reliably
   bootstrap itself on an image without the Store. Installing the official MSI
   (`wsl.<ver>.x64.msi` from `microsoft/WSL` releases) with
   `msiexec /i wsl.msi /quiet /norestart` works silently and returns 0 — that is
   the deterministic way to get WSL onto a merchant machine.
 - **`wsl --install` cannot create the UNIX account.** Its complete option set is
   `--enable-wsl1 --fixed-vhd --from-file --legacy --location --name
   --no-distribution --no-launch --version --vhd-size --web-download`. The
   account is only ever created by the distro's interactive first-run. The
   supported non-interactive sequence, verified end to end in the VM, is:
   `wsl --install -d <Distro> --no-launch --web-download`, then
   `wsl -d <Distro> -u root -- useradd -m <user>`, then
   `wsl --manage <Distro> --set-default-user <user>`.
 - **systemd is already PID 1 in the Debian WSL image.** It ships `/etc/wsl.conf`
   containing `[boot] systemd=true`, `ps -p 1 -o comm=` returns `systemd` and
   `systemctl is-system-running` returns `running`. The `systemctl` calls these
   scripts make are therefore fine — but hand-appending `[user]` to that file
   risks clobbering the `[boot]` stanza, which is why `--set-default-user` is
   preferred.
 - **The installer always claims success.** The final
   *"GNU Taler-Merchant installed successfully"* line prints unconditionally, two
   seconds after the log records `return code 1` from the reverse-proxy step.
 
 ## Known rough edges
 
 Fixed on the current review branch (see `git log`): the non-existent
 `--acme`/`--merchant-url` arguments, the `%errorlevel%` expansion bug that hid every
 reverse-proxy failure, the `taler-merchant.conf` overwrite, the `python3-certbot-nginx`
 port-80 conflict, enabling the service instead of the socket, `set-db.sh` writing a
 `DATABASE_URL` key that nothing reads, the mid-step `exit /b` that made `STEP=3` do only
 half of step 3, and `$DOMAIN_INPUT` being used both as an nsDialogs control handle and as
 the domain text (which broke the "localhost implies HTTP-only" guard).
 
 Still open, and worth knowing before debugging a user report:
 
 - **`rproxy-setup` requires the domain to resolve to a local IP.** It runs
   `dig +short A "$DOMAIN"` and compares against `hostname -I`, exiting 1 on a mismatch.
   Inside WSL the interface is NAT'd (172.x), so a real public domain never matches, and
   `localhost` has no A record at all. The check is skipped entirely when `dig` is absent
   — `bind9-dnsutils` is priority-standard but not a dependency of `taler-merchant`,
   `certbot`, `apache2` or `postgresql`, so whether this fires depends on the WSL image.
   Fixing it properly means relaxing the check to a warning in the `merchant` checkout
   (its own comment suggests exactly that), which is a separate repo and review.
 - **`certbot certonly` is interactive** (email, TOS) and `rproxy-setup` passes no
   `--non-interactive --agree-tos -m`, so HTTPS mode can block on a prompt that nobody
   sees behind `nsExec`. Also a `merchant`-side change.
 - **No silent/unattended mode.** All four inputs come from `nsDialogs` pages, which `/S`
   skips, leaving the variables empty; the ~8 `MessageBox` calls block regardless of `/S`
   (NSIS does not suppress them). `FileFunc.nsh` is already included, so `GetOptions` for
   `/DOMAIN=` etc. is close at hand.
 - **Step 1 demands a reboot and a full re-run**, persisting no state, so the wizard
   re-asks everything. For automated runs, snapshot a VM with the WSL features already
   enabled.
 - **`.onGUIEnd` shows a MessageBox and opens a browser on any exit**, including user
   cancel and failure. (It now at least logs which of those happened.)
 - **Progress percentages are fake** — `Sleep`-driven `DetailPrint` lines, because the
   long `nsExec` calls block the GUI.
 - **Start-menu shortcut** points at `$INSTDIR\taler-installer.exe`, which the section
   never installs.
 - **`%DATE%`/`%TIME%` inside parenthesised blocks** all expand at parse time, so every
   log line in one block shares a timestamp.
 - Timestamps aside, `MessageBox`/`DetailPrint` text and the log messages are a mix of
   English and French.
 
 ## Conventions
 
 - Shell scripts are committed **LF**; `.bat` and `.nsi` are **CRLF** (NSIS and `cmd.exe`
   want it). Step 5 runs `dos2unix` in WSL as a belt-and-braces measure, so a stray CRLF in
   a `.sh` survives — keep them LF anyway.
 - GPLv2.1+ header with `Author: Léa Oualli` on the `.bat`/`.nsi`/`.sh` files that have one.
 - Comments and some log messages are in **French**; user-facing strings are localised into
   six languages. Every new wizard string needs a `LangString` for all of
   `${LANG_ENGLISH}`, `${LANG_FRENCH}`, `${LANG_GERMAN}`, `${LANG_ITALIAN}`,
   `${LANG_SPANISH}` and `${LANG_DUTCH}` — an id missing from one language falls back to
   the first declared language (English) with no warning, so keep the six lines per id
   adjacent and check with
   `grep -c 'LANG_GERMAN}' taler-installer-taler.nsi` against the other five.
 - **`taler-installer-taler.nsi` must keep its UTF-8 BOM.** `Unicode true` governs the
   *output*, not how the *source* is read. The BOM is what makes the source decode as UTF-8
   unconditionally: measured with `makensis` 3.11, a BOM'd script compiles as UTF-8 even
   when overridden with `-INPUTCHARSET CP1252` (all accents intact), while the same script
   with the BOM stripped obeys that codepage and turns 3 of 4 probe strings into mojibake.
   BOM-less UTF-8 is merely auto-detected as a fallback, which is why it happens to work on
   a Linux host whose ACP is already UTF-8 and cannot be relied on for a Windows build.
   Dropping the BOM therefore corrupts every `ä ö ü ß è à á í ñ ¿ ¡ ï` in a `LangString` —
   that is why the French strings used to be written unaccented ("Etape", "redemarrer").
   They may now be accented properly; several still are not.
 - Never put U+202F (narrow no-break space, the French space before `?`/`!`) in a
   `LangString`. It exists in no Windows ANSI codepage and renders as three stray glyphs
   if the BOM is ever lost.
 - Translated terminology comes from the workspace glossary `../dictionary.csv`, not from
   taste: `merchant` is Händler / comerciante / commerçant / venditore / verkoper, and
   `backend` stays an English loanword inflected natively.
 - `.onInit` exists only to `!insertmacro MUI_LANGDLL_DISPLAY`. The `MUI_LANGDLL_*` defines
   near the top configure that dialog but do not show it; drop the `.onInit` and the
   installer silently runs in the system language, or English, and every translation
   becomes unreachable.
 - `test-if.bat` is a scratch file for checking the `MODE`/`TYPE` branch logic, not part of
   the installer. `run-admin.bat` just re-launches `setup-wsl-debian.bat` elevated via
   PowerShell for manual testing outside the wizard.
 
 ## Git
 
 Same workspace rule as the sibling checkouts: `origin` is a read-only mirror; work goes on
 `dev/phoenix-bot/<topic>` pushed to the `durian` remote, via the **`taler-push`** skill.
 This repo's history, unlike the other checkouts', is a handful of informal French commit
 messages — follow the skill's format for new commits rather than that precedent.