Reorganize developer docs into devdocs/; new CLAUDE.md and .NET 10 port plan

2026-10-22 11:52:52 -07:00
parent 47c3f9bc28
commit 2dd8a4bb04
10 changed files with 716 additions and 692 deletions
--- a/devdocs/build/BUILD.md
+++ b/devdocs/build/BUILD.md
@@ -0,0 +1,134 @@
+# AyaNova v8 release build
+
+How a full release is built: tools, folder layout, what `build-release.bat` does, and where
+version numbers live. Written for .NET 8 (8.2.4); the .NET 10 port updates it.
+
+To set up a machine that can run this from scratch, see `DEV-VM-SETUP.md`.
+
+## What gets built
+
+| Project | Framework | Output |
+|---|---|---|
+| AyaNova server (`raven/server/AyaNova`) | .NET 8 | Five packages, below |
+| Launcher (`raven-launcher`) | .NET 8, self-contained, `PublishTrimmed` | Inside the Windows standalone installer |
+| QBI (`ravenqbi/AyaNovaQBI`) | .NET Framework 4.8 | `ayanova-qbi-setup.exe`, built separately |
+
+| Package | Build |
+|---|---|
+| `ayanova-subscription-linux-x64-server.zip` | linux-x64, framework-dependent, `SUBSCRIPTION_BUILD=true`, server `config.json` |
+| `ayanova-linux-x64-server.zip` | linux-x64, framework-dependent, server `config.json` |
+| `ayanova-linux-x64-desktop.zip` | Same build, desktop `config.json` |
+| `ayanova-windows-x64-single-setup.exe` | win-x64 self-contained server, launcher, embedded PostgreSQL |
+| `ayanova-windows-x64-lan-setup.exe` | win-x64 framework-dependent server |
+
+## Tools
+
+| Tool | Version | Used for |
+|---|---|---|
+| .NET SDK | 8.0.x | Server and launcher |
+| Node.js | **12.22.9 exactly** | Front end. Newer versions break `fibers` |
+| Python | 3.11 | MkDocs |
+| MkDocs + mkdocs-material | current | Customer manual (`pip install mkdocs mkdocs-material`) |
+| Inno Setup | 6.x | Windows installers |
+| 7-Zip | current | Linux zips |
+| Visual Studio | **[unverified: 2022 or 18/2026]** | QBI only |
+
+The scripts hardcode these paths:
+
+- `C:\data\code\raven\`, `C:\data\code\raven-client\ayanova\`, `C:\data\code\raven-launcher\`, `C:\data\code\ravenqbi\`
+- `C:\Program Files\7-Zip\7z.exe`
+- `C:\Program Files (x86)\Inno Setup 6\ISCC.exe`
+
+## Folder layout
+
+```
+C:\data\code\
+├── raven\
+│   ├── build-release.bat           master build script
+│   ├── raven.sln
+│   ├── server\AyaNova\             AyaNova.csproj, wwwroot\ (generated), resource\
+│   ├── docs\8.0\ayanova\           customer manual, mkdocs.yml
+│   ├── docs\8.0\customer\          customer portal docs, mkdocs.yml
+│   ├── devdocs\                    developer docs (this file)
+│   ├── dist\
+│   │   ├── assets\                 LICENSE, license.rtf, logo.ico, lan-install-config.json,
+│   │   │                           linux-server\config.json, linux-desktop\config.json
+│   │   ├── install\windows\x64\    standalone.iss, lan.iss
+│   │   ├── win-x64\postgres-standalone\   embedded PostgreSQL (maintained by hand)
+│   │   └── installers\             final packages (generated)
+│   │       (also generated: linux-x64\, subscription-build-linux-x64\, win-x64\ayanova\..., win-x64\launcher\)
+│   └── graphics\
+├── raven-client\ayanova\           Vue front end
+├── raven-launcher\                 raven-launcher.csproj, config.json
+└── ravenqbi\                       AyaNovaQBI\AyaNovaQBI.csproj, install\qbi.iss
+```
+
+## `build-release.bat`, step by step
+
+1. **Clean** `raven\server\AyaNova\wwwroot` and `raven\dist\installers`.
+2. **Customer manual**: `mkdocs build` in `docs\8.0\ayanova` and `docs\8.0\customer`. Output goes straight to `wwwroot\docs` (`site_dir` in `mkdocs.yml`).
+3. **Front end**: `npm run build` in `raven-client\ayanova`, then `xcopy dist\* ...\raven\server\AyaNova\wwwroot\ /e`. The .NET build does not produce `wwwroot`: whatever is there is what ships.
+4. **Subscription Linux**:
+   ```bat
+   dotnet publish --property:PublishDir=C:\data\code\raven\dist\subscription-build-linux-x64\ -c Release -r linux-x64 --no-self-contained -p:SUBSCRIPTION_BUILD=true
+   ```
+   Zipped with `assets\linux-server\config.json`.
+5. **Perpetual Linux**: the same with `-p:SUBSCRIPTION_BUILD=false` into `dist\linux-x64\`. One build, two zips: desktop and server `config.json`.
+6. **Windows standalone**: `-r win-x64 --self-contained` into `dist\win-x64\ayanova\standalone\` (includes the .NET runtime, about 150 MB more).
+7. **Windows framework-dependent**: `-r win-x64 --no-self-contained` into `dist\win-x64\ayanova\framework-dependent\`. Needs the .NET runtime on the target.
+8. **Launcher**: `dotnet publish -c Release -r win-x64 --self-contained` in `raven-launcher` into `dist\win-x64\launcher\`.
+9. **Installers**: `ISCC.exe standalone.iss` and `ISCC.exe lan.iss`.
+
+`raven-client\ayanova\buildrelease.bat` runs steps 1–3 alone (main manual only, not the
+customer portal docs).
+
+### Windows installers
+
+- **Standalone** (`standalone.iss`): self-contained server, launcher, embedded PostgreSQL, empty database template, desktop shortcut to the launcher. App in `{autopf}\ayanova`; data in `{commonappdata}\ayanova\database`; logs in `{commonappdata}\ayanova\logs`. The launcher starts PostgreSQL, starts the server, opens the browser at the login page and waits.
+- **LAN** (`lan.iss`): framework-dependent server plus network config. No PostgreSQL. Prompts the user to download the ASP.NET Core Hosting Bundle and PostgreSQL.
+
+### QBI (separate)
+
+```bat
+cd C:\data\code\ravenqbi\AyaNovaQBI
+msbuild /p:Configuration=Release
+cd C:\data\code\ravenqbi\install
+"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" qbi.iss
+```
+
+Output: `ravenqbi\install\output\ayanova-qbi-setup.exe`. Has a pre-build event that runs a
+timestamp utility.
+
+## Version numbers
+
+Set in five places for every release:
+
+| File | Setting | At 8.2.4 |
+|---|---|---|
+| `raven\server\AyaNova\AyaNova.csproj` | `<Version>` | 8.2.4 |
+| `raven\dist\install\windows\x64\standalone.iss` | `#define MyAppVersion` | 8.2.4 |
+| `raven\dist\install\windows\x64\lan.iss` | `#define MyAppVersion` | 8.2.4 |
+| `raven-client\ayanova\package.json` | `"version"` | 8.2.4 |
+| `ravenqbi\install\qbi.iss` | `#define MyAppVersion` | 8.0.2 (own cycle) |
+
+## Front-end build notes
+
+- Install dependencies with `npm ci`, never `npm install`: it installs the exact versions in `package-lock.json`.
+- Warnings that appear on every build and are harmless: Browserslist "caniuse-lite is outdated"; Dart Sass "Using / for division is deprecated" (from Vuetify); asset size warnings (Monaco's `ts.worker.js` is about 4.5 MB).
+- Webpack content-hash file names change on every build even when contents do not. Compare file contents, not names.
+
+## Docker builds
+
+`Dockerfile.frontend` and `Dockerfile.docs` build the front end and the manual in containers
+**[unverified: where they live]**. The Linux server packages and the Windows
+framework-dependent build could also build in Docker. Windows self-contained builds, Inno
+Setup, QBI and the embedded PostgreSQL need Windows.
+
+## Troubleshooting
+
+- **`fibers` fails to install**: it needs Python, Visual Studio Build Tools, and Node exactly 12.22.9. Last resort: remove `"fibers"` from `package.json` and the `fiber: require("fibers")` line from `webpack.config.js`; the build still works, a little slower.
+- **Node version errors**: `node -v` must print `v12.22.9`.
+- **"Module not found"**: delete `node_modules`, then `npm ci`.
+- **PuppeteerSharp cannot download the browser**: check connectivity, or point the server at an installed browser through its browser-path setting.
+- **`SUBSCRIPTION_BUILD` not applied**: the flag is `-p:SUBSCRIPTION_BUILD=true` on `dotnet publish`.
+- **Inno Setup errors**: an earlier step failed, or 7-Zip / Inno Setup are not at the expected paths.