diff --git a/BACKEND-BUILD-ENVIRONMENT.md b/BACKEND-BUILD-ENVIRONMENT.md new file mode 100644 index 00000000..9ecb7e6e --- /dev/null +++ b/BACKEND-BUILD-ENVIRONMENT.md @@ -0,0 +1,374 @@ +# AyaNova v8 Backend Build Environment Documentation + +> **Purpose**: This document captures the complete backend build process for AyaNova v8, including all deployment targets and installers. + +## Overview + +The backend build produces **6 deployment packages** from **3 projects**: + +### Projects + +| Project | Framework | Purpose | +|---------|-----------|---------| +| AyaNova (server) | .NET 8.0 | Main ASP.NET Core web server | +| raven-launcher | .NET 8.0 | Windows launcher for standalone mode | +| AyaNovaQBI | .NET Framework 4.8 | QuickBooks Desktop integration (separate build) | + +### Deployment Targets + +| Target | Description | Output | +|--------|-------------|--------| +| Subscription Linux x64 | Your hosted service (DigitalOcean) | `ayanova-subscription-linux-x64-server.zip` | +| Perpetual Linux Server | Self-hosted Linux server | `ayanova-linux-x64-server.zip` | +| Perpetual Linux Desktop | Single-user Linux desktop | `ayanova-linux-x64-desktop.zip` | +| Windows Standalone | Self-contained single-user (includes .NET runtime + PostgreSQL) | `ayanova-windows-x64-single-setup.exe` | +| Windows LAN | Network server (requires separate .NET + PostgreSQL) | `ayanova-windows-x64-lan-setup.exe` | +| QuickBooks Integration | Windows desktop app | `ayanova-qbi-setup.exe` (separate build) | + +--- + +## Directory Structure + +``` +c:\data\code\ +├── raven\ # Main repository root +│ ├── build-release.bat # Master build script +│ ├── raven.sln # Visual Studio solution +│ ├── server\ +│ │ └── AyaNova\ # ASP.NET Core server project +│ │ ├── AyaNova.csproj +│ │ ├── Program.cs +│ │ ├── Startup.cs +│ │ ├── wwwroot\ # Frontend files copied here +│ │ └── resource\ # Report templates, etc. +│ ├── docs\ +│ │ └── 8.0\ +│ │ ├── ayanova\ # Main documentation (MkDocs) +│ │ │ └── mkdocs.yml +│ │ └── customer\ # Customer portal documentation +│ │ └── mkdocs.yml +│ ├── dist\ +│ │ ├── assets\ # Shared assets (license, configs, icons) +│ │ │ ├── LICENSE +│ │ │ ├── license.rtf +│ │ │ ├── linux-desktop\config.json +│ │ │ ├── linux-server\config.json +│ │ │ ├── lan-install-config.json +│ │ │ └── logo.ico +│ │ ├── install\ +│ │ │ └── windows\x64\ # Inno Setup scripts +│ │ │ ├── standalone.iss +│ │ │ └── lan.iss +│ │ ├── installers\ # Build output (generated) +│ │ ├── linux-x64\ # Linux build output (generated) +│ │ ├── subscription-build-linux-x64\ # Subscription build output (generated) +│ │ └── win-x64\ # Windows build output (generated) +│ │ ├── ayanova\ +│ │ │ ├── standalone\ # Self-contained build +│ │ │ └── framework-dependent\ # Requires .NET installed +│ │ ├── launcher\ # Launcher build output +│ │ └── postgres-standalone\ # Embedded PostgreSQL for standalone +│ └── graphics\ # Icons, logos +│ +├── raven-client\ # Frontend (separate repo/folder) +│ └── ayanova\ +│ +├── raven-launcher\ # Launcher project +│ ├── raven-launcher.csproj +│ └── config.json +│ +└── ravenqbi\ # QuickBooks integration (separate) + ├── AyaNovaQBI\ + │ └── AyaNovaQBI.csproj + └── install\ + └── qbi.iss +``` + +--- + +## Build Requirements + +### Software + +| Tool | Version | Purpose | +|------|---------|---------| +| .NET SDK | 8.0.x | Build ASP.NET Core projects | +| Node.js | 12.22.9 | Build frontend (see frontend docs) | +| Python | 3.11.x | Build MkDocs documentation | +| MkDocs | Latest | Documentation generator | +| Inno Setup | 6.x | Windows installer creation | +| 7-Zip | Latest | Create Linux distribution zips | +| Visual Studio 2022 | Latest | Build QBI project (.NET Framework 4.8) | + +### Paths (hardcoded in build scripts) + +The build scripts expect these exact paths: +- `C:\data\code\raven\` - Main repository +- `C:\data\code\raven-client\ayanova\` - Frontend project +- `C:\data\code\raven-launcher\` - Launcher project +- `C:\data\code\ravenqbi\` - QuickBooks integration +- `C:\Program Files\7-Zip\7z.exe` - 7-Zip +- `C:\Program Files (x86)\Inno Setup 6\ISCC.exe` - Inno Setup compiler + +--- + +## Build Process (build-release.bat) + +The master build script executes in this order: + +### 1. Clean Output Folders +```batch +rmdir c:\data\code\raven\server\AyaNova\wwwroot /s/q +mkdir c:\data\code\raven\server\AyaNova\wwwroot +rmdir C:\data\code\raven\dist\installers /s/q +mkdir C:\data\code\raven\dist\installers +``` + +### 2. Build Documentation (MkDocs) +```batch +cd c:\data\code\raven\docs\8.0\ayanova +mkdocs build + +cd c:\data\code\raven\docs\8.0\customer +mkdocs build +``` +Output goes to `wwwroot/docs` (configured in mkdocs.yml). + +### 3. Build Frontend (Vue.js) +```batch +cd c:\data\code\raven-client\ayanova +call npm run build +xcopy dist\* ..\raven\server\AyaNova\wwwroot\ /e +``` + +### 4. Build Subscription Linux x64 +```batch +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 +``` +Key flag: `-p:SUBSCRIPTION_BUILD=true` sets a compile-time constant for subscription-specific features. + +Then packages to zip with config: +```batch +7z a ayanova-subscription-linux-x64-server.zip subscription-build-linux-x64\* +7z a ayanova-subscription-linux-x64-server.zip assets\linux-server\config.json +``` + +### 5. Build Perpetual Linux x64 +```batch +dotnet publish --property:PublishDir=C:\data\code\raven\dist\linux-x64\ \ + -c Release -r linux-x64 --no-self-contained -p:SUBSCRIPTION_BUILD=false +``` + +Creates two packages (same build, different config): +- `ayanova-linux-x64-desktop.zip` (with desktop config) +- `ayanova-linux-x64-server.zip` (with server config) + +### 6. Build Windows Standalone (Self-Contained) +```batch +dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\ayanova\standalone\ \ + -r win-x64 --self-contained +``` +This includes the .NET runtime in the output (~150MB larger). + +### 7. Build Windows Framework-Dependent +```batch +dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\ayanova\framework-dependent\ \ + -r win-x64 --no-self-contained +``` +Requires .NET 8 runtime installed on target machine. + +### 8. Build Launcher +```batch +cd C:\data\code\raven-launcher\ +dotnet publish -c Release --property:PublishDir=C:\data\code\raven\dist\win-x64\launcher\ \ + -r win-x64 --self-contained +``` +The launcher is always self-contained (uses `PublishTrimmed` to reduce size). + +### 9. Create Windows Installers (Inno Setup) +```batch +ISCC.exe standalone.iss +ISCC.exe lan.iss +``` + +--- + +## Project-Specific Notes + +### AyaNova Server (AyaNova.csproj) + +**Conditional Compilation:** +```xml +$(DefineConstants);SUBSCRIPTION_BUILD +``` +Use `#if SUBSCRIPTION_BUILD` in code for subscription-only features. + +**Key Dependencies:** +- Entity Framework Core 8.0 with Npgsql (PostgreSQL) +- PuppeteerSharp for PDF report generation (downloads Chromium on first run) +- MailKit for email +- JWT authentication + +**Resource Files:** +Report templates and other resources are copied to output: +```xml + + Always + +``` + +### Launcher (raven-launcher.csproj) + +Simple console app that: +1. Starts embedded PostgreSQL (standalone mode only) +2. Starts the AyaNova server +3. Opens default browser to the login page +4. Waits for user to close + +Uses `PublishTrimmed` to reduce self-contained size. + +### QuickBooks Integration (AyaNovaQBI.csproj) + +**Important:** This is a .NET Framework 4.8 Windows Forms application, NOT .NET Core. + +- Requires Visual Studio 2022 (not VS Code) for the Windows Forms designer +- References `interop.QBFC14.dll` from QuickBooks SDK (must be installed) +- Targets x86 (32-bit) because QuickBooks SDK is 32-bit only +- Has a pre-build event that runs a timestamp utility + +**Why Visual Studio is required:** +The Windows Forms designer only works in Visual Studio. The code could theoretically be edited in VS Code, but the designer is essential for the UI work. + +--- + +## Windows Installer Details + +### Standalone (standalone.iss) + +Includes: +- Self-contained AyaNova server (with .NET runtime) +- Self-contained launcher +- Embedded PostgreSQL (`postgres-standalone` folder) +- Empty database template + +Creates desktop shortcut to launcher. User clicks one icon, everything starts. + +**Key paths:** +- App: `{autopf}\ayanova` +- Data: `{commonappdata}\ayanova\database` +- Logs: `{commonappdata}\ayanova\logs` + +### LAN (lan.iss) + +Includes: +- Framework-dependent AyaNova server (no .NET runtime) +- Config file for network mode + +Does NOT include PostgreSQL - user must install separately. + +Prompts user to download: +- ASP.NET Core Runtime Hosting Bundle +- PostgreSQL + +--- + +## Embedded PostgreSQL (Windows Standalone) + +The standalone installer includes a portable PostgreSQL in `dist\win-x64\postgres-standalone\`. + +This is a pre-configured PostgreSQL installation that: +- Runs without system installation +- Stores data in `{commonappdata}\ayanova\database` +- Is started/stopped by the launcher + +**Source:** You'll need to maintain this - it's a copy of a PostgreSQL Windows binary distribution with a pre-initialized data directory. + +--- + +## QuickBooks Integration Build (Separate) + +The QBI is built separately and not included in the main build script. + +```batch +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: `c:\data\code\ravenqbi\install\output\ayanova-qbi-setup.exe` + +--- + +## Version Management + +Versions must be updated in multiple places: + +| File | Location | +|------|----------| +| `AyaNova.csproj` | `8.2.4` | +| `standalone.iss` | `#define MyAppVersion "8.2.4"` | +| `lan.iss` | `#define MyAppVersion "8.2.4"` | +| `qbi.iss` | `#define MyAppVersion "8.0.2"` | +| `package.json` (frontend) | `"version": "8.2.4"` | + +Consider creating a version file or script to update all at once. + +--- + +## Containerization Considerations + +### What CAN be containerized (for build): + +1. **Frontend build** - Already done (Dockerfile.frontend) +2. **Documentation build** - Already done (Dockerfile.docs) +3. **Linux server builds** - .NET SDK in Docker can cross-compile for Linux +4. **Windows framework-dependent build** - Can be built in Docker + +### What CANNOT be easily containerized: + +1. **Windows self-contained builds** - Need Windows container or Windows host +2. **Inno Setup installers** - Windows-only tool +3. **QuickBooks Integration** - .NET Framework 4.8, Windows Forms, requires Visual Studio +4. **Embedded PostgreSQL** - Windows-specific binaries + +### Recommendation: + +For a VPS-based build: +- Use Docker/Linux for: Frontend, Docs, Linux targets +- Keep Windows laptop for: Windows installers, QBI +- Or: Use a Windows VM/GitHub Actions for Windows builds + +--- + +## Troubleshooting + +### "PuppeteerSharp failed to download Chromium" + +The server downloads Chromium on first run for PDF generation. If this fails: +1. Check internet connectivity +2. Check firewall/proxy settings +3. Pre-download Chrome and set `REPORT_RENDER_BROWSER_PATH` environment variable + +### "SUBSCRIPTION_BUILD not defined" + +Ensure you're passing the flag correctly: +```batch +dotnet publish ... -p:SUBSCRIPTION_BUILD=true +``` + +### Inno Setup errors + +- Ensure all source paths exist +- Check that previous build steps completed +- Verify 7-Zip and Inno Setup are installed at expected paths + +--- + +## Version History + +| Date | Change | +|------|--------| +| 2026-02-01 | Initial documentation created |