@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/getting-started/installation.mdx

@@ -0,0 +1,780 @@
+---
+title: Installation Guide
+description: Detailed installation instructions for the Blue Alba Platform including system requirements, repository structure, and troubleshooting
+---
+
+import { Steps, Aside, Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
+
+This comprehensive guide covers everything you need to install and configure the Blue Alba Platform for local development.
+
+## System Requirements
+
+Before installing the platform, ensure your system meets these requirements:
+
+### Required Software
+
+<CardGrid>
+  <Card title="Node.js" icon="seti:nodejs">
+    **Version**: 20.0.0 or higher (LTS recommended)
+
+    **Why**: Platform services and UIs are built with Node.js
+
+    **Verification**:
+    ```bash
+    node --version
+    # Expected: v20.x.x or higher
+    ```
+
+    **Installation**:
+    - macOS: `brew install node@20` or use [nvm](https://github.com/nvm-sh/nvm)
+    - Linux: Use nvm or your package manager
+    - Windows: Download from [nodejs.org](https://nodejs.org/)
+  </Card>
+
+  <Card title="npm" icon="seti:npm">
+    **Version**: 10.8.2 (enforced by package.json)
+
+    **Why**: Platform requires specific npm version for consistency
+
+    **Verification**:
+    ```bash
+    npm --version
+    # Expected: 10.8.2
+    ```
+
+    **Installation**:
+    ```bash
+    npm install -g npm@10.8.2
+    ```
+  </Card>
+
+  <Card title="Docker Desktop" icon="docker">
+    **Version**: Latest stable release
+
+    **Why**: Required for databases, Kafka, and containerized services
+
+    **Verification**:
+    ```bash
+    docker --version
+    docker-compose --version
+    ```
+
+    **Installation**:
+    - macOS: [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
+    - Linux: [Docker Engine](https://docs.docker.com/engine/install/)
+    - Windows: [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
+
+    **Requirements**:
+    - At least 4GB RAM allocated to Docker
+    - 20GB+ free disk space
+  </Card>
+
+  <Card title="Git" icon="github">
+    **Version**: 2.x or higher
+
+    **Why**: Version control for source code
+
+    **Verification**:
+    ```bash
+    git --version
+    ```
+
+    **Installation**:
+    - macOS: Pre-installed or `brew install git`
+    - Linux: `sudo apt install git` or `sudo yum install git`
+    - Windows: [Git for Windows](https://git-scm.com/download/win)
+  </Card>
+</CardGrid>
+
+### Recommended Software
+
+- **IDE**: VS Code with TypeScript, ESLint, and Prettier extensions
+- **Terminal**: iTerm2 (macOS), Windows Terminal, or any modern terminal
+- **Database Client**: DBeaver, pgAdmin, or TablePlus for PostgreSQL inspection
+- **API Client**: Postman, Insomnia, or Thunder Client for API testing
+
+### Hardware Requirements
+
+- **CPU**: 4+ cores recommended (2 minimum)
+- **RAM**: 8GB minimum, 16GB recommended
+- **Disk**: 20GB free space for code, dependencies, and Docker images
+- **Network**: Broadband internet for downloading dependencies
+
+<Aside type="tip">
+  **Performance Tip**: The platform builds faster with SSDs and more RAM. If you have limited resources, consider closing other applications during the initial build.
+</Aside>
+
+---
+
+## Understanding the Repository Structure
+
+The Blue Alba Platform uses a **Turborepo monorepo** structure. Understanding this layout is crucial for effective development.
+
+### High-Level Structure
+
+```
+bluealba-platform/
+├── apps/                     # Applications (services and UIs)
+├── packages/                 # Shared libraries
+├── scripts/                  # Utility scripts
+├── .changeset/               # Changesets for versioning
+├── turbo.json                # Turborepo configuration
+├── package.json              # Workspace root package.json
+├── package-lock.json         # Dependency lock file
+├── tsconfig.json             # TypeScript configuration
+└── README.md                 # Repository readme
+```
+
+### Apps Directory
+
+The `apps/` directory contains deployable applications:
+
+```
+apps/
+├── pae-nestjs-gateway-service/    # Main API Gateway
+│   ├── src/                       # Source code
+│   ├── test/                      # E2E tests
+│   ├── Dockerfile                 # Production image
+│   ├── Dockerfile.development     # Development image
+│   └── package.json
+│
+├── pae-habits-service/            # Habits tracking service
+│   ├── src/
+│   ├── bootstrap/                 # Service bootstrap
+│   └── package.json
+│
+├── pae-scheduler-service/         # Scheduling service
+│
+├── pae-shell-ui/                  # Main Shell UI (React)
+│   ├── src/
+│   ├── public/
+│   └── package.json
+│
+├── pae-admin-ui/                  # Administration UI (React)
+│
+└── pae-documentation/             # Documentation site (Astro)
+    ├── src/
+    └── astro.config.mjs
+```
+
+### Packages Directory
+
+The `packages/` directory contains shared libraries:
+
+```
+packages/
+├── pae-core-lib/                  # Core domain logic
+│   ├── src/
+│   │   ├── entities/              # Domain entities
+│   │   ├── authorization/         # Authorization logic
+│   │   └── catalog/               # Catalog types
+│   └── package.json
+│
+├── pae-ui-react-sdk/              # React build tools
+│   ├── config/                    # Webpack configs
+│   ├── bin/                       # CLI tools
+│   └── package.json
+│
+├── pae-ui-react-core/             # Shared React components
+│   ├── src/
+│   │   ├── components/            # UI components
+│   │   ├── hooks/                 # Custom hooks
+│   │   └── context/               # React contexts
+│   └── package.json
+│
+├── pae-service-nestjs-sdk/        # NestJS utilities
+│   ├── src/
+│   │   ├── decorators/            # Custom decorators
+│   │   ├── guards/                # Auth guards
+│   │   └── filters/               # Exception filters
+│   └── package.json
+│
+├── pae-bootstrap-lib/             # Bootstrap utilities
+│
+└── pae-microservices-runtime-sdk/ # Runtime SDK
+```
+
+### Key Configuration Files
+
+<Tabs>
+  <TabItem label="turbo.json">
+    **Purpose**: Configures Turborepo's build pipeline
+
+    ```json
+    {
+      "pipeline": {
+        "build": {
+          "dependsOn": ["^build"],
+          "outputs": ["dist/**", "build/**"]
+        },
+        "test": {
+          "dependsOn": ["build"],
+          "outputs": ["coverage/**"]
+        },
+        "dev": {
+          "cache": false,
+          "persistent": true
+        }
+      }
+    }
+    ```
+
+    **Key Features**:
+    - Defines task dependencies
+    - Specifies caching strategies
+    - Configures parallel execution
+  </TabItem>
+
+  <TabItem label="package.json">
+    **Purpose**: Workspace root configuration
+
+    ```json
+    {
+      "name": "bluealba-platform",
+      "private": true,
+      "workspaces": [
+        "apps/*",
+        "packages/*"
+      ],
+      "packageManager": "npm@10.8.2",
+      "scripts": {
+        "build": "turbo build",
+        "dev": "turbo dev",
+        "test": "turbo test",
+        "changeset": "changeset"
+      }
+    }
+    ```
+
+    **Key Features**:
+    - Defines workspace structure
+    - Enforces npm version
+    - Provides common scripts
+  </TabItem>
+
+  <TabItem label="tsconfig.json">
+    **Purpose**: TypeScript configuration
+
+    ```json
+    {
+      "compilerOptions": {
+        "target": "ES2022",
+        "module": "commonjs",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true
+      }
+    }
+    ```
+
+    **Note**: Individual packages extend this base config
+  </TabItem>
+</Tabs>
+
+---
+
+## Installation Steps
+
+Follow these steps to install the Blue Alba Platform on your local machine.
+
+<Steps>
+
+1. **Create a workspace directory**
+
+   Create a parent directory to hold both the platform code and the sandbox product:
+
+   ```bash
+   mkdir bluealba-workspace
+   cd bluealba-workspace
+   ```
+
+   <Aside>
+     This file system convention is important - the Sandbox Product expects the platform code to be in a sibling directory.
+   </Aside>
+
+2. **Clone the repository**
+
+   Clone the Blue Alba Platform repository:
+
+   ```bash
+   git clone https://github.com/bluealba/bluealba-platform.git
+   cd bluealba-platform
+   ```
+
+   Verify the clone was successful:
+
+   ```bash
+   ls -la
+   # Should see: apps/, packages/, turbo.json, package.json, etc.
+   ```
+
+3. **Install dependencies**
+
+   Install all dependencies for the monorepo:
+
+   ```bash
+   npm install
+   ```
+
+   This command:
+   - Installs root dependencies
+   - Installs dependencies for all packages
+   - Links workspace packages together
+   - May take 5-10 minutes depending on your internet speed
+
+   <Aside type="note">
+     npm will enforce the required version (10.8.2) due to the `packageManager` field in package.json. If you have a different version, npm will prompt you to upgrade/downgrade.
+   </Aside>
+
+4. **Build all packages**
+
+   Build all packages and applications:
+
+   ```bash
+   npx turbo build
+   ```
+
+   What happens during build:
+   - Packages are built in dependency order
+   - TypeScript is compiled to JavaScript
+   - Build artifacts are output to `dist/` directories
+   - Turborepo caches successful builds
+   - First build takes 10-15 minutes
+
+   <Aside type="tip">
+     **Turborepo Caching**: After the first build, subsequent builds are much faster. Turborepo only rebuilds changed packages and their dependents.
+   </Aside>
+
+5. **Verify the build**
+
+   Check that all packages built successfully:
+
+   ```bash
+   # Check for dist directories
+   ls apps/pae-nestjs-gateway-service/dist
+   ls packages/pae-core-lib/dist
+
+   # Run turbo's build again (should be instant due to cache)
+   npx turbo build
+   ```
+
+   If you see "cache hit" messages, the build completed successfully.
+
+6. **Run tests (optional)**
+
+   Verify everything works by running tests:
+
+   ```bash
+   npx turbo test
+   ```
+
+   This runs all unit tests across packages and services.
+
+</Steps>
+
+---
+
+## File System Conventions
+
+For local development, the platform expects a specific file system layout:
+
+### Required Directory Structure
+
+```
+bluealba-workspace/
+├── bluealba-platform/           # This repository (platform code)
+│   ├── apps/
+│   ├── packages/
+│   └── ...
+│
+└── sandbox-product/             # Recommended for development
+    └── pae-sandbox-local/
+        ├── docker-compose-pae.yaml         # Platform services
+        ├── docker-compose-infra.yaml       # Infrastructure
+        ├── docker-compose-bootstrap.yaml   # Bootstrap
+        └── .env                            # Environment variables
+```
+
+### Why This Structure?
+
+The Docker Compose files in the Sandbox Product use **relative paths** to mount source code:
+
+```yaml
+# docker-compose-pae.yaml
+volumes:
+  - ${PWD}/../../bluealba-platform:/app/out
+```
+
+This assumes:
+- Sandbox Product is at `./sandbox-product/pae-sandbox-local/`
+- Platform code is at `./bluealba-platform/`
+- Both are siblings in the same parent directory
+
+<Aside type="caution">
+  If you use a different directory structure, you'll need to update the volume paths in `docker-compose-pae.yaml`.
+</Aside>
+
+---
+
+## Setting Up the Sandbox Product
+
+The Sandbox Product provides a complete development environment with Docker Compose.
+
+<Steps>
+
+1. **Clone the Sandbox Product**
+
+   From your workspace directory:
+
+   ```bash
+   cd bluealba-workspace
+   git clone https://github.com/bluealba/sandbox-product.git
+   cd sandbox-product/pae-sandbox-local
+   ```
+
+2. **Configure environment variables**
+
+   Copy the example environment file:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` to customize settings:
+
+   ```bash
+   # Database Configuration
+   PAE_DB_HOST=postgres
+   PAE_DB_PORT=5432
+   PAE_DB_USER=postgres
+   PAE_DB_PASSWORD=postgres
+   PAE_DB=pae_dev
+
+   # JWT Configuration
+   PAE_AUTH_JWT_SECRET=your-super-secret-jwt-key-here
+
+   # Service Secrets
+   PAE_GATEWAY_SERVICE_ACCESS_SECRET=another-secret-key
+
+   # Service URLs
+   PAE_AUTHN_SERVICE_URL=http://pae-nestjs-gateway-service:80
+   ```
+
+   <Aside type="caution" title="Security Warning">
+     **Never commit the `.env` file to version control.** It should be in `.gitignore`. Use strong secrets in production environments.
+   </Aside>
+
+3. **Start infrastructure services**
+
+   Start PostgreSQL, Kafka, Zookeeper:
+
+   ```bash
+   docker-compose -f docker-compose-infra.yml up -d
+   ```
+
+   Wait 30-60 seconds for services to initialize:
+
+   ```bash
+   docker-compose -f docker-compose-infra.yml ps
+   # All services should show "Up"
+   ```
+
+4. **Bootstrap the platform**
+
+   Initialize the database schema and seed data:
+
+   ```bash
+   docker-compose -f docker-compose-bootstrap.yml up
+   ```
+
+   This command:
+   - Creates database tables
+   - Inserts initial users (admin@platform.com)
+   - Creates roles and operations
+   - Registers applications in the catalog
+   - Seeds example data
+
+   The bootstrap should complete in 1-2 minutes. When finished, you'll see "Bootstrap complete" in the logs.
+
+5. **Start platform services**
+
+   Start all platform services and UIs:
+
+   ```bash
+   docker-compose -f docker-compose-pae.yml up -d
+   ```
+
+   Verify all services are running:
+
+   ```bash
+   docker-compose -f docker-compose-pae.yml ps
+   ```
+
+6. **Verify the installation**
+
+   Test the gateway health endpoint:
+
+   ```bash
+   curl -k https://localhost:9443/_/health
+   # Expected: {"status": "ok"}
+   ```
+
+   Open the platform in your browser:
+
+   ```
+   https://localhost:9443
+   ```
+
+   Login with default credentials:
+   - Username: `admin@platform.com`
+   - Password: `admin123`
+
+</Steps>
+
+---
+
+## Troubleshooting
+
+### Installation Issues
+
+#### npm install fails with version error
+
+**Problem**: npm complains about version mismatch
+
+```bash
+npm ERR! This version of npm is not compatible
+```
+
+**Solution**: Install the exact required version:
+
+```bash
+npm install -g npm@10.8.2
+```
+
+#### Build fails with "out of memory" error
+
+**Problem**: Node.js runs out of heap memory during build
+
+```bash
+FATAL ERROR: Ineffective mark-compacts near heap limit
+```
+
+**Solution**: Increase Node.js heap size:
+
+```bash
+export NODE_OPTIONS="--max-old-space-size=4096"
+npx turbo build
+```
+
+#### Cannot find module errors after install
+
+**Problem**: TypeScript can't find workspace packages
+
+```bash
+Cannot find module '@bluealba/pae-core-lib'
+```
+
+**Solution**: Rebuild packages:
+
+```bash
+npx turbo clean
+npm install
+npx turbo build
+```
+
+### Docker Issues
+
+#### Ports already in use
+
+**Problem**: Docker can't bind to required ports
+
+```bash
+Error: bind: address already in use
+```
+
+**Solution**: Find and kill processes using the ports:
+
+```bash
+# Check what's using port 9443
+lsof -i :9443
+
+# Kill the process
+kill -9 <PID>
+
+# Or change the port in docker-compose-pae.yml
+```
+
+#### Docker containers won't start
+
+**Problem**: Services fail to start with various errors
+
+**Solution**: Check Docker resource allocation:
+
+1. Open Docker Desktop
+2. Go to Settings → Resources
+3. Ensure at least:
+   - CPUs: 2 or more
+   - Memory: 4GB or more
+   - Swap: 1GB or more
+   - Disk: 20GB or more
+
+Restart Docker Desktop after changes.
+
+#### Cannot connect to PostgreSQL
+
+**Problem**: Services can't reach the database
+
+```bash
+Error: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+**Solution**: Ensure infrastructure services are running:
+
+```bash
+docker-compose -f docker-compose-infra.yml ps
+docker-compose -f docker-compose-infra.yml logs postgres
+```
+
+If PostgreSQL is down, restart it:
+
+```bash
+docker-compose -f docker-compose-infra.yml restart postgres
+```
+
+Wait 30 seconds for PostgreSQL to fully start.
+
+### Build Issues
+
+#### Turborepo cache issues
+
+**Problem**: Builds succeed but runtime fails with old code
+
+**Solution**: Clear Turborepo cache:
+
+```bash
+npx turbo clean
+rm -rf node_modules/.cache
+npx turbo build --force
+```
+
+The `--force` flag bypasses the cache.
+
+#### TypeScript compilation errors
+
+**Problem**: Build fails with TypeScript errors
+
+**Solution**:
+
+1. Ensure you're using TypeScript 5.8:
+
+```bash
+npm list typescript
+```
+
+2. Clean and rebuild:
+
+```bash
+npx turbo clean
+npm install
+npx turbo build
+```
+
+3. Check for missing peer dependencies:
+
+```bash
+npm run check-deps
+npm run fix-deps
+```
+
+#### Circular dependency warnings
+
+**Problem**: Warnings about circular imports
+
+```bash
+Warning: Circular dependency detected
+```
+
+**Solution**: These are usually harmless warnings. If they cause issues:
+
+1. Review the import chain
+2. Refactor to break the cycle
+3. Use dynamic imports if necessary
+
+### File System Issues
+
+#### Permission denied errors
+
+**Problem**: Can't write to directories
+
+```bash
+EACCES: permission denied
+```
+
+**Solution**: Fix directory permissions:
+
+```bash
+# Fix ownership
+sudo chown -R $USER:$USER bluealba-platform
+
+# Or run with appropriate permissions
+sudo npm install
+```
+
+#### Disk space issues
+
+**Problem**: Not enough space for dependencies and builds
+
+```bash
+ENOSPC: no space left on device
+```
+
+**Solution**:
+
+1. Clean Docker:
+
+```bash
+docker system prune -a
+```
+
+2. Clean npm cache:
+
+```bash
+npm cache clean --force
+```
+
+3. Clean builds:
+
+```bash
+npx turbo clean
+rm -rf node_modules
+```
+
+---
+
+## Next Steps
+
+Congratulations! You've successfully installed the Blue Alba Platform.
+
+Here's what to do next:
+
+1. **[Development Workflow](/_/docs/development/workflow/)** - Learn how to develop with the platform
+2. **[Core Concepts](/_/docs/getting-started/core-concepts/)** - Understand applications, modules, roles, and more
+3. **[Architecture Deep Dive](/_/docs/architecture/overview/)** - Explore the technical architecture
+4. **[Building Your First Service](/_/docs/guides/creating-services/)** - Create a custom service
+
+## Getting Help
+
+If you encounter issues not covered in this guide:
+
+1. **Check the logs**:
+   ```bash
+   docker-compose -f docker-compose-pae.yml logs <service-name>
+   ```
+
+2. **Review service READMEs**: Each app has a README in its directory
+
+3. **GitHub Issues**: Search or create issues in the repository
+
+4. **Documentation**: Browse other sections of this documentation site
+
+Happy coding!