2026-02-03 04:02:17 +00:00
parent eec79aeaec
commit 95c2abe449
1 changed files with 374 additions and 0 deletions
--- a/BACKEND-BUILD-ENVIRONMENT.md
+++ 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 Condition=" '$(SUBSCRIPTION_BUILD)' == 'true' ">$(DefineConstants);SUBSCRIPTION_BUILD</DefineConstants>
+```
+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
+<Content Include=".\resource\*.*">
+  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+</Content>
+```
+
+### 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` | `<Version>8.2.4</Version>` |
+| `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 |