raven/BUILD-ENVIRONMENT.md

AyaNova v8 Build Environment Documentation

Purpose: This document captures the exact build environment for AyaNova v8 as of February 2026. Use this to recreate the build environment on a new machine or in a container.

Overview

AyaNova v8 consists of three main build components:

1. Frontend - Vue.js 2 application (JavaScript, not TypeScript)
2. Documentation - MkDocs with Material theme
3. Backend - ASP.NET Core 8.0 server (C#)

The frontend and docs are built first, then copied into the backend project's wwwroot folder before the backend is built and packaged for distribution.

---

Current Build Machine Specifications

Component	Version	Notes
Operating System	Windows 11	ThinkPad X13 Gen 3
Node.js	v12.22.9	End-of-life - do not upgrade without testing
npm	(check with npm -v)	Comes with Node
Python	3.11.1	For MkDocs
.NET SDK	8.0.x	For backend build

---

Frontend Build Environment

Directory Structure

c:\data\code\
├── raven-client\
│   └── ayanova\          # Vue.js frontend project
│       ├── src\          # Source code
│       ├── public\       # Static assets
│       ├── dist\         # Build output (generated)
│       ├── package.json
│       ├── vue.config.js
│       └── buildrelease.bat
├── raven\
│   ├── server\
│   │   └── AyaNova\
│   │       └── wwwroot\  # Frontend files copied here after build
│   └── docs\
│       └── 8.0\
│           └── ayanova\  # MkDocs source
│               └── mkdocs.yml

Node.js Version: Critical Information

Current version: Node.js 12.22.9

This project uses an old Node version because:

1. The fibers package (used by sass-loader for faster Sass compilation) is a native C++ addon that stopped being maintained and doesn't compile on newer Node versions
2. Various other dependencies have peer dependency requirements that break on Node 14+

Do not upgrade Node without first testing in an isolated environment.

Key Dependencies

From package.json:

Package	Version	Purpose
vue	2.6.14	Core framework (Vue 2, end-of-life Dec 2023)
vuetify	2.6.6	UI component library
@vue/cli-service	4.5.15	Build tooling
webpack	4.46.0	Module bundler
sass	1.52.3	Sass compiler
fibers	4.0.3	Problematic - native addon for Sass
monaco-editor	0.30.1	Code editor component

Build Process

The frontend build is executed via buildrelease.bat:

@echo **************************************************************
@echo ******************** BUILD CLIENT ****************************
@echo **************************************************************
rmdir c:\data\code\raven\server\AyaNova\wwwroot /s/q
mkdir c:\data\code\raven\server\AyaNova\wwwroot
cd c:\data\code\raven\docs\8.0\ayanova
mkdocs build
cd c:\data\code\raven-client\ayanova
call npm run build
xcopy c:\data\code\raven-client\ayanova\dist\* C:\data\code\raven\server\AyaNova\wwwroot\ /e
pause

This does:

1. Clears and recreates the backend's wwwroot folder
2. Builds the MkDocs documentation (output goes directly to wwwroot/docs via mkdocs.yml config)
3. Runs npm run build which calls vue-cli-service build
4. Copies the built frontend from dist/ to the backend's wwwroot/

Known Build Warnings (Safe to Ignore)

These warnings appear during every build and do not affect the output:

1. Browserslist warning: "caniuse-lite is outdated"

   • Harmless - just means browser compatibility database is old

2. Dart Sass division warnings: "Using / for division is deprecated"

   • Come from Vuetify's stylesheets, not your code
   • Will continue working until Dart Sass 2.0

3. Asset size warnings: Various files exceed 244 KiB

   • Expected with Monaco editor (ts.worker.js is 4.5MB)
   • Application still works correctly

NPM Scripts

{
  "serve": "vue-cli-service serve",   // Development server
  "build": "vue-cli-service build",   // Production build
  "lint": "vue-cli-service lint"      // Code linting
}

---

Documentation Build Environment

MkDocs Configuration

From mkdocs.yml:

Setting	Value
Theme	Material
Output directory	../../../server/AyaNova/wwwroot/docs
Site URL	https://ayanova.com/docs/

Required Python Packages

pip install mkdocs mkdocs-material

The pymdownx extensions (highlight, superfences) come bundled with mkdocs-material.

Build Command

cd c:\data\code\raven\docs\8.0\ayanova
mkdocs build

Output goes directly to the backend's wwwroot/docs folder.

---

Backend Build Environment

.NET Version

• Target Framework: .NET 8.0
• Project Type: ASP.NET Core

Build Tools Required

• .NET 8.0 SDK
• Visual Studio 2022 or VS Code with C# extension

Build Outputs

The backend build produces multiple deployment targets:

1. Linux hosted (DigitalOcean service)
2. Windows networked (IIS hosted)
3. Windows single-user (self-contained)
4. Linux server
5. Linux desktop

Windows installers are created with Inno Setup.

---

Recreating the Build Environment

Option 1: Native Installation (Windows)

1. Install Node.js 12.22.9 specifically:

   • Download from https://nodejs.org/dist/v12.22.9/
   • Or use nvm-windows: nvm install 12.22.9 && nvm use 12.22.9

2. Install Python 3.11:

   • Download from python.org
   • Ensure it's in PATH

3. Install MkDocs:

   pip install mkdocs mkdocs-material
   

4. Install .NET 8.0 SDK:

   • Download from https://dotnet.microsoft.com/download

5. Clone/checkout repository from SVN

6. Install frontend dependencies:

   cd c:\data\code\raven-client\ayanova
   npm ci
   

   Note: Use npm ci (not npm install) to install exact versions from package-lock.json

Option 2: Docker (Recommended for Reproducibility)

See Dockerfile.frontend and Dockerfile.docs in this repository for containerized builds that don't require any local installation except Docker.

---

Troubleshooting

"fibers" fails to install

This native module requires:

• Python 2.7 or 3.x
• Visual Studio Build Tools (Windows) or build-essential (Linux)
• Specific Node.js version compatibility

If it fails, you can try removing it (it's optional):

1. Remove "fibers": "^4.0.3" from package.json
2. Remove the fiber: require("fibers") line from webpack.config.js
3. Run npm install again

The build will be slightly slower but should work.

Node version mismatch

If you see errors about incompatible Node versions:

1. Check your Node version: node -v
2. It must be 12.22.9 for guaranteed compatibility
3. Use nvm to switch versions if needed

"Module not found" errors

Try:

rm -rf node_modules
rm package-lock.json
npm install

---

Future Modernization Notes

When time permits, consider:

1. Remove fibers dependency - It's optional and causes most build issues
2. Upgrade to Vue 3 + Vite - Much faster builds, better tooling, active support
3. Migrate to TypeScript - Better IDE support and fewer runtime errors
4. Update Node to LTS - Current LTS is Node 20.x

These are significant changes that should be done incrementally with thorough testing.

---

Version History

Date	Change
2026-02-01	Initial documentation created