From eec79aeaec70b08eeed5b25c48cc30f91498196c Mon Sep 17 00:00:00 2001 From: John Cardinal Date: Mon, 2 Feb 2026 02:48:54 +0000 Subject: [PATCH] Case 4641 AI era starts now --- BUILD-ENVIRONMENT.md | 271 +++++++++++++++++++++++++++++++++++++++++++ Dockerfile.docs | 29 +++++ 2 files changed, 300 insertions(+) create mode 100644 BUILD-ENVIRONMENT.md create mode 100644 Dockerfile.docs diff --git a/BUILD-ENVIRONMENT.md b/BUILD-ENVIRONMENT.md new file mode 100644 index 00000000..ca4a76d4 --- /dev/null +++ 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 | diff --git a/Dockerfile.docs b/Dockerfile.docs new file mode 100644 index 00000000..3f463f90 --- /dev/null +++ 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"]