Case 4641 AI era starts now

2026-02-02 02:48:54 +00:00
parent d96942a296
commit eec79aeaec
2 changed files with 300 additions and 0 deletions
--- a/BUILD-ENVIRONMENT.md
+++ b/BUILD-ENVIRONMENT.md
@@ -0,0 +1,271 @@
+# 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`:
+
+```batch
+@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
+
+```json
+{
+  "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
+
+```bash
+pip install mkdocs mkdocs-material
+```
+
+The `pymdownx` extensions (highlight, superfences) come bundled with mkdocs-material.
+
+### Build Command
+
+```bash
+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:
+   ```bash
+   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:
+   ```bash
+   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:
+```bash
+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 |
--- a/Dockerfile.docs
+++ b/Dockerfile.docs
@@ -0,0 +1,29 @@
+# AyaNova v8 Documentation Build Environment
+#
+# This Dockerfile creates a reproducible build environment for the MkDocs documentation.
+#
+# Usage:
+#   Build the image:
+#     docker build -f Dockerfile.docs -t ayanova-docs-build .
+#
+#   Run a build (mount your docs source and output):
+#     docker run --rm -v "c:/data/code/raven/docs/8.0/ayanova:/docs" -v "c:/data/code/raven/server/AyaNova/wwwroot/docs:/output" ayanova-docs-build
+#
+#   Serve docs locally for preview (on port 8000):
+#     docker run --rm -p 8000:8000 -v "c:/data/code/raven/docs/8.0/ayanova:/docs" ayanova-docs-build mkdocs serve -a 0.0.0.0:8000
+#
+
+FROM python:3.11-slim-bullseye
+
+# Install MkDocs and the Material theme
+# pymdownx extensions come bundled with mkdocs-material
+RUN pip install --no-cache-dir \
+    mkdocs==1.5.* \
+    mkdocs-material==9.*
+
+WORKDIR /docs
+
+# Default command: build the documentation
+# Note: The output directory is configured in mkdocs.yml (site_dir)
+# For containerized builds, you may want to override site_dir
+CMD ["mkdocs", "build"]