raven/devdocs/build/BUILD.md

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); updated for .NET 10 (8.3.0).

Releases are built on the workstation; the backup laptop is the fallback. To set up a machine that can run this from scratch, use the tool list and install commands in DEV-VM-SETUP.md (the VM itself is deprecated).

Backup laptop: still to bring in line with the workstation (John's notes, 2026-10-23):

• Install the .NET 10 SDK: winget install --id Microsoft.DotNet.SDK.10 -e --source winget (the .NET 8 SDK is no longer needed)
• Replace KeePass and KeeAgent with KeePassXC
• Install rclone and configure the S3 remote: an rclone remote named spaces for DigitalOcean Spaces (bucket gztw1)
• Copy over the backup batch file C:\data\biz-servers\weekly-copy-biz-server-backup-locally.bat (run weekly: copies the Sockeye and Gitea backups from Spaces into C:\data\biz-servers\data-backup-local-copy)
• Uninstall FileZilla
• Fix up TortoiseGit and Git SSH so both work

What gets built

Project	Framework	Output
AyaNova server (raven/server/AyaNova)	.NET 10	Five packages, below
Launcher (raven-launcher)	.NET 10, 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	10.0.x, newest	Server and launcher. Update before every release build (winget install --id Microsoft.DotNet.SDK.10 -e, or winget upgrade once installed that way): the Windows standalone server and the launcher are self-contained and ship the .NET runtime of the SDK that built them (SDK 10.0.103 → runtime 10.0.3; 10.0.402 → 10.0.13). The SDK that comes with Visual Studio is not updated by winget
Node.js	12.22.9 exactly	Front end. Newer versions break fibers
Python	3.11	MkDocs
MkDocs + mkdocs-material	MkDocs 1.x	Customer manual (pip install "mkdocs<2" mkdocs-material). Material for MkDocs does not work with MkDocs 2.0: keep the pin until the docs move to Zensical (see ../modernization/ROADMAP.md)
Inno Setup	6.x	Windows installers
7-Zip	current	Linux zips
Visual Studio	18 (2026) Community on the dev machine; no VS 2022 installed	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:

   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)

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

raven-client\ayanova\Dockerfile.frontend and raven\Dockerfile.docs build the front end and the manual in containers. A runtime image and compose file for the Linux server are in raven\dist\docker\linux-x64\. 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.