raven/BACKEND-BUILD-ENVIRONMENT.md

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

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)

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)

cd c:\data\code\raven-client\ayanova
call npm run build
xcopy dist\* ..\raven\server\AyaNova\wwwroot\ /e

4. Build Subscription Linux x64

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:

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

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)

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

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

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)

ISCC.exe standalone.iss
ISCC.exe lan.iss

---

Project-Specific Notes

AyaNova Server (AyaNova.csproj)

Conditional Compilation:

<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:

<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.

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:

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