@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/getting-started/quick-start.mdx

@@ -0,0 +1,940 @@
+---
+title: Quick Start Guide
+description: Get the Blue Alba Platform up and running with your own white-label product
+---
+
+import { Steps, Aside, Card, CardGrid, Code } from '@astrojs/starlight/components';
+import PAEDockerComposeFile from '~/assets/quick-start/files/docker-compose-platform.yml?raw';
+import EnvExampleFile from '~/assets/quick-start/files/.env.example?raw';
+import GatewayServiceEnvFile from '~/assets/quick-start/files/environment/gateway-service.env?raw';
+import SchedulerServiceEnvFile from '~/assets/quick-start/files/environment/scheduler-service.env?raw';
+
+This guide will help you get the Blue Alba Platform running locally. You'll create your own minimal white-label product from scratch, giving you a solid foundation to build upon.
+
+<Aside type="tip" title="Use the Platform CLI">
+  The **Platform CLI** (`@bluealba/platform-cli`) automates the entire setup process described in this guide. If you prefer a guided experience over manual file creation, install the CLI and run `platform init` — it will scaffold the correct directory structure, generate configuration files, and walk you through each step interactively.
+
+  See the [Platform CLI Overview](/_/docs/platform-cli/overview/) and [Command Reference](/_/docs/platform-cli/commands/) to get started.
+</Aside>
+
+## Choose Your Setup Path
+
+There are two ways to get started with the Blue Alba Platform:
+
+<CardGrid>
+  <Card title="Path 1: Pre-built Images (RECOMMENDED)" icon="rocket">
+    **Best for most users** - Use pre-built Docker images from the registry.
+
+    - **Setup time**: ~10 minutes
+    - **Use case**: Building your product on the platform
+    - **What you need**: Docker, basic configuration files
+    - **What you don't need**: Platform source code, build tools
+
+    This is the fastest way to get started and is recommended for most users who want to focus on building their product features.
+  </Card>
+
+  <Card title="Path 2: Source Code (ADVANCED)" icon="rocket">
+    **For platform contributors** - Clone and build from source.
+
+    - **Setup time**: ~15 minutes
+    - **Use case**: Contributing to the platform or customizing core functionality
+    - **What you need**: Node.js, Docker, platform source code
+    - **When to use**: You need to modify platform internals
+
+    Choose this path only if you need to modify platform code or contribute to platform development.
+  </Card>
+</CardGrid>
+
+### Quick Comparison
+
+| Aspect | Path 1: Pre-built Images | Path 2: Source Code |
+|--------|-------------------------|---------------------|
+| **Platform Updates** | Change image tags | Pull + rebuild source |
+| **Platform Build Required** | No | Yes |
+| **Best For** | Product developers | Platform contributors |
+
+<Aside type="tip" title="Not Sure Which to Choose?">
+  If you're asking "which one should I use?", the answer is **Path 1**. You can always switch to Path 2 later if you need to modify platform internals.
+</Aside>
+
+## Prerequisites
+
+<CardGrid>
+  <Card title="Node.js 20+" icon="node">
+    Required for building the platform from source.
+
+    ```bash
+    node --version
+    # Should be >= v20.0.0
+    ```
+  </Card>
+
+  <Card title="Docker" icon="seti:docker">
+    Required for running platform services and infrastructure components.
+
+    ```bash
+    docker --version
+    docker-compose --version
+    ```
+  </Card>
+
+  <Card title="Git" icon="github">
+    Version control for cloning the platform repository.
+
+    ```bash
+    git --version
+    ```
+  </Card>
+</CardGrid>
+
+<Aside type="tip">
+  **macOS Users**: Install Node.js via [nvm](https://github.com/nvm-sh/nvm) for easy version management.
+
+  **Windows Users**: Use [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) and ensure WSL 2 is enabled.
+</Aside>
+
+## Path 1: Quick Setup with Pre-built Images (RECOMMENDED)
+
+This is the recommended path for most users. You'll create a minimal product called "my-product" that includes:
+- The Gateway Service (API and authentication)
+- The Shell UI (web interface)
+- An admin user for platform management
+- All necessary infrastructure
+
+<Steps>
+
+1. **Create your product directory structure**
+
+   Create a directory for your product:
+
+   ```bash
+   mkdir -p my-product/{my-product-local,environment}
+   cd my-product
+   ```
+
+2. **Create Base Docker files**
+
+   Inside `my-product-local/`, create the following files:
+
+   <Code lang="yaml" title="docker-compose-platform.yml" code={PAEDockerComposeFile}/>
+
+3. **Create environment configuration**
+
+   Inside `my-product-local/`, Create a `.env` file with all required environment variables:
+
+
+   <Code lang="dotenv" title=".env" code={EnvExampleFile}/>
+
+   Inside `my-product-local/environment`, create the following files:
+
+   <Code lang="dotenv" title="gateway-service.env" code={GatewayServiceEnvFile}/>
+
+   <Code lang="dotenv" title="scheduler-service.env" code={SchedulerServiceEnvFile}/>
+
+   <Aside type="tip">
+     Remember to change the secret keys before deploying to production. Generate strong random strings for **PAE_AUTH_JWT_SECRET** and **PAE_GATEWAY_SERVICE_ACCESS_SECRET**.
+   </Aside>
+
+4. **Create platform bootstrap service**
+   Inside `my-product-local/`, clone the platform bootstrap template repository:
+
+   <Code lang="bash" title="Clone Bootstrap Template" code={`git clone https://github.com/bluealba/pae-bootstrap-template.git bootstrap`}/>
+
+
+8. **Create bootstrap configuration files**
+
+    Create the basic bootstrap configurations for operations, roles, and the Shell application.
+
+    Each application folder inside `bootstrap/` must match the application name. In this example we use `my-app` — replace it with your own application name.
+
+    **Operations** (`bootstrap/my-app/operations.json`):
+
+    ```json title="bootstrap/my-app/operations.json"
+    {
+      "operations": [
+        {
+          "code": "CREATE",
+          "name": "Create",
+          "description": "Create new resources"
+        },
+        {
+          "code": "READ",
+          "name": "Read",
+          "description": "View and read resources"
+        },
+        {
+          "code": "UPDATE",
+          "name": "Update",
+          "description": "Modify existing resources"
+        },
+        {
+          "code": "DELETE",
+          "name": "Delete",
+          "description": "Remove resources"
+        },
+        {
+          "code": "ADMIN",
+          "name": "Administration",
+          "description": "Administrative operations"
+        }
+      ]
+    }
+    ```
+
+    **Roles** (`bootstrap/my-app/roles.json`):
+
+    ```json title="bootstrap/my-app/roles.json"
+    {
+      "roles": [
+        {
+          "code": "PLATFORM_ADMIN",
+          "name": "Platform Administrator",
+          "description": "Full platform administration access",
+          "permissions": [
+            {
+              "resource": "*",
+              "operations": ["*"]
+            }
+          ]
+        },
+        {
+          "code": "USER",
+          "name": "User",
+          "description": "Basic user access",
+          "permissions": [
+            {
+              "resource": "shell",
+              "operations": ["READ"]
+            }
+          ]
+        }
+      ]
+    }
+    ```
+
+    **Shell Application** (`bootstrap/shell/application.json`):
+
+    ```json title="bootstrap/shell/application.json"
+    {
+      "application": {
+        "code": "shell",
+        "name": "Shell",
+        "description": "Main application container",
+        "url": "http://localhost:8080",
+        "type": "shell",
+        "active": true,
+        "metadata": {
+          "icon": "home",
+          "order": 0
+        }
+      }
+    }
+    ```
+
+    **Shell Modules** (`bootstrap/shell/modules.json`):
+
+    ```json title="bootstrap/shell/modules.json"
+    {
+      "modules": [
+        {
+          "code": "home",
+          "name": "Home",
+          "description": "Home page module",
+          "route": "/home",
+          "component": "HomeModule",
+          "active": true,
+          "metadata": {
+            "icon": "home",
+            "showInMenu": true,
+            "order": 0
+          }
+        }
+      ]
+    }
+    ```
+
+9. **Start the infrastructure services**
+
+    Start PostgreSQL, Kafka, and Zookeeper:
+
+    ```bash
+    docker-compose -f docker-compose-infra.yml up -d
+    ```
+
+    Wait about 30 seconds for services to initialize properly.
+
+10. **Bootstrap the platform**
+
+    Initialize the database schema and create the admin user:
+
+    ```bash
+    docker-compose -f docker-compose-bootstrap.yml up
+    ```
+
+    <Aside>
+      This command creates the database schema, operations, roles, the Shell application, and your admin user. It should complete in about 1-2 minutes. The container will exit when finished.
+    </Aside>
+
+11. **Start the platform services**
+
+    Start the Gateway Service and Shell UI:
+
+    ```bash
+    docker-compose -f docker-compose-pae.yml up -d
+    ```
+
+12. **Verify everything is running**
+
+    Check that all services are healthy:
+
+    ```bash
+    docker-compose -f docker-compose-pae.yml ps
+    ```
+
+    You should see both services in the "Up" state.
+
+13. **Access the platform**
+
+    Open your browser and navigate to:
+
+    ```
+    https://localhost:9443
+    ```
+
+    <Aside type="caution" title="SSL Certificate Warning">
+      You'll see a security warning because the platform uses a self-signed certificate for local development. This is expected - click "Advanced" and "Proceed to localhost" to continue.
+    </Aside>
+
+    Default login credentials:
+
+    ```
+    Username: admin@platform.com
+    Password: admin123
+    ```
+
+</Steps>
+
+Congratulations! You've successfully set up the Blue Alba Platform using pre-built images. Skip to the [What You Just Created](#what-you-just-created) section to learn about your new environment.
+
+---
+
+## Path 2: Development Setup with Source Code (ADVANCED)
+
+<Aside type="caution" title="Advanced Users Only">
+  This path is only needed if you're contributing to the platform or need to modify platform internals. Most users should use Path 1 instead.
+</Aside>
+
+If you need to work with the platform source code, follow these steps:
+
+<Steps>
+
+1. **Create a workspace directory**
+
+   Create a directory to hold both the platform code and your product:
+
+   ```bash
+   mkdir bluealba-workspace
+   cd bluealba-workspace
+   ```
+
+2. **Clone the Blue Alba Platform**
+
+   Clone the main platform repository:
+
+   ```bash
+   git clone https://github.com/bluealba/bluealba-platform.git
+   cd bluealba-platform
+   ```
+
+3. **Install dependencies and build**
+
+   Install all dependencies:
+
+   ```bash
+   npm install
+   ```
+
+   Build all packages and applications:
+
+   ```bash
+   npx turbo build
+   ```
+
+   <Aside type="note">
+     The first build may take 5-10 minutes as Turborepo builds all packages and apps. Subsequent builds will be much faster thanks to caching.
+   </Aside>
+
+4. **Create your product directory structure**
+
+   Return to the workspace directory and create your product structure:
+
+   ```bash
+   cd ..
+   mkdir -p my-product/{bootstrap/my-app,bootstrap/shell,ssl}
+   cd my-product
+   ```
+
+5. **Generate SSL certificates**
+
+   Create self-signed certificates for local HTTPS:
+
+   ```bash
+   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+     -keyout ssl/private.key \
+     -out ssl/certificate.crt \
+     -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"
+   ```
+
+6. **Create environment configuration**
+
+   Create a `.env` file (same as Path 1 - see above for the complete file).
+
+7. **Create infrastructure configuration**
+
+   Create `docker-compose-infra.yml` (same as Path 1).
+
+8. **Create bootstrap service configuration**
+
+   Create `docker-compose-bootstrap.yml` for source-based bootstrap:
+
+   ```yaml title="docker-compose-bootstrap.yml"
+   version: '3.8'
+
+   services:
+     bootstrap:
+       image: node:20-alpine
+       container_name: pae-bootstrap
+       working_dir: /app
+       volumes:
+         - ../bluealba-platform:/app:ro
+         - ./bootstrap:/bootstrap:ro
+       environment:
+         PAE_DB_HOST: ${PAE_DB_HOST}
+         PAE_DB_PORT: ${PAE_DB_PORT}
+         PAE_DB_USER: ${PAE_DB_USER}
+         PAE_DB_PASSWORD: ${PAE_DB_PASSWORD}
+         PAE_DB: ${PAE_DB}
+         PAE_DB_SCHEMA: ${PAE_DB_SCHEMA}
+         BOOTSTRAP_ADMIN_EMAIL: ${BOOTSTRAP_ADMIN_EMAIL}
+         BOOTSTRAP_ADMIN_PASSWORD: ${BOOTSTRAP_ADMIN_PASSWORD}
+         BOOTSTRAP_ADMIN_FIRST_NAME: ${BOOTSTRAP_ADMIN_FIRST_NAME}
+         BOOTSTRAP_ADMIN_LAST_NAME: ${BOOTSTRAP_ADMIN_LAST_NAME}
+         BOOTSTRAP_CONFIG_PATH: /bootstrap
+       command: >
+         sh -c "
+         cd /app/packages/pae-bootstrap-lib &&
+         node dist/cli.js bootstrap
+         "
+       depends_on:
+         - postgres
+       networks:
+         - pae-network
+
+   networks:
+     pae-network:
+       external: true
+   ```
+
+9. **Create platform services configuration**
+
+   Create `docker-compose-pae.yml` for source-based services:
+
+   ```yaml title="docker-compose-pae.yml"
+   version: '3.8'
+
+   services:
+     pae-nestjs-gateway-service:
+       image: node:20-alpine
+       container_name: pae-nestjs-gateway-service
+       working_dir: /app
+       volumes:
+         - ../bluealba-platform:/app:ro
+         - ./ssl:/ssl:ro
+       ports:
+         - "9080:80"
+         - "9443:443"
+       environment:
+         NODE_ENV: development
+         PAE_DB_HOST: ${PAE_DB_HOST}
+         PAE_DB_PORT: ${PAE_DB_PORT}
+         PAE_DB_USER: ${PAE_DB_USER}
+         PAE_DB_PASSWORD: ${PAE_DB_PASSWORD}
+         PAE_DB: ${PAE_DB}
+         PAE_DB_SCHEMA: ${PAE_DB_SCHEMA}
+         PAE_AUTH_JWT_SECRET: ${PAE_AUTH_JWT_SECRET}
+         PAE_GATEWAY_SERVICE_ACCESS_SECRET: ${PAE_GATEWAY_SERVICE_ACCESS_SECRET}
+         PAE_GATEWAY_PORT: ${PAE_GATEWAY_PORT}
+         PAE_GATEWAY_HTTPS_PORT: ${PAE_GATEWAY_HTTPS_PORT}
+         KAFKA_BROKERS: ${KAFKA_BROKERS}
+         KAFKA_CLIENT_ID: ${KAFKA_CLIENT_ID}
+         SSL_KEY_PATH: /ssl/private.key
+         SSL_CERT_PATH: /ssl/certificate.crt
+       command: >
+         sh -c "
+         cd /app/apps/pae-nestjs-gateway-service &&
+         node dist/main.js
+         "
+       depends_on:
+         - postgres
+         - kafka
+       healthcheck:
+         test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:80/health"]
+         interval: 30s
+         timeout: 10s
+         retries: 3
+       networks:
+         - pae-network
+
+     pae-shell-ui:
+       image: nginx:alpine
+       container_name: pae-shell-ui
+       volumes:
+         - ../bluealba-platform/apps/pae-shell-ui/dist:/usr/share/nginx/html:ro
+         - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
+       ports:
+         - "8080:80"
+       depends_on:
+         - pae-nestjs-gateway-service
+       networks:
+         - pae-network
+
+   networks:
+     pae-network:
+       external: true
+   ```
+
+10. **Create Nginx configuration**
+
+    Create `nginx.conf` (same as Path 1).
+
+11. **Create bootstrap configuration files**
+
+    Create the bootstrap JSON files (same as Path 1).
+
+12. **Start infrastructure and bootstrap**
+
+    ```bash
+    docker-compose -f docker-compose-infra.yml up -d
+    # Wait 30 seconds
+    docker-compose -f docker-compose-bootstrap.yml up
+    ```
+
+13. **Start platform services**
+
+    ```bash
+    docker-compose -f docker-compose-pae.yml up -d
+    ```
+
+14. **Verify and access**
+
+    Verify services are running:
+
+    ```bash
+    docker-compose -f docker-compose-pae.yml ps
+    ```
+
+    Access at: https://localhost:9443
+
+</Steps>
+
+<Aside type="tip" title="Development Mode">
+  When working with source code, you can run services in development mode with hot reload:
+
+  ```bash
+  # Stop the Docker container first
+  docker-compose -f docker-compose-pae.yml stop pae-nestjs-gateway-service
+
+  # Run locally with hot reload
+  cd ../bluealba-platform/apps/pae-nestjs-gateway-service
+  npm run dev
+  ```
+</Aside>
+
+---
+
+## What You Just Created
+
+Your local environment now includes:
+
+### Backend Services
+
+- **Gateway Service** (ports 9080/9443): Main API gateway with authentication, authorization, and application catalog
+
+### Frontend Applications
+
+- **Shell UI** (port 8080): Main application container that hosts micro-frontend modules
+
+### Infrastructure
+
+- **PostgreSQL** (port 5432): Database server for platform data
+- **Kafka** (port 9092): Event streaming platform
+- **Zookeeper** (port 2181): Kafka coordination service
+
+### Your Product Structure
+
+**Path 1 (Pre-built Images)**:
+
+```
+my-product/
+├── docker-compose-infra.yml      # Infrastructure services
+├── docker-compose-bootstrap.yml  # One-time bootstrap
+├── docker-compose-pae.yml        # Platform services (using images)
+├── nginx.conf                     # Shell UI web server config
+├── .env                          # Environment variables
+├── ssl/                          # SSL certificates
+│   ├── private.key
+│   └── certificate.crt
+└── bootstrap/                    # Bootstrap configurations
+    ├── my-app/                   # Application folder (name must match your app)
+    │   ├── operations.json
+    │   └── roles.json
+    └── shell/
+        ├── application.json
+        └── modules.json
+```
+
+**Path 2 (Source Code)**:
+
+```
+bluealba-workspace/
+├── bluealba-platform/            # Platform source code
+│   ├── apps/
+│   ├── packages/
+│   └── ... (all platform code)
+└── my-product/
+    ├── docker-compose-infra.yml      # Infrastructure services
+    ├── docker-compose-bootstrap.yml  # One-time bootstrap
+    ├── docker-compose-pae.yml        # Platform services (mounting source)
+    ├── nginx.conf                     # Shell UI web server config
+    ├── .env                          # Environment variables
+    ├── ssl/                          # SSL certificates
+    │   ├── private.key
+    │   └── certificate.crt
+    └── bootstrap/                    # Bootstrap configurations
+        ├── my-app/               # Application folder (name must match your app)
+        │   ├── operations.json
+        │   └── roles.json
+        └── shell/
+            ├── application.json
+            └── modules.json
+```
+
+## First Steps in the Platform
+
+Now that you're logged in, let's explore:
+
+### 1. Explore the Shell UI
+
+The **Shell UI** is the main container that hosts all micro-frontend applications. You'll see a minimal interface - this is your blank canvas ready for customization.
+
+### 2. Check the API Documentation
+
+Visit the Swagger API documentation:
+
+```
+https://localhost:9443/docs
+```
+
+This shows all available API endpoints from the gateway. You can test endpoints directly from the Swagger UI.
+
+### 3. Verify Your Admin User
+
+Your admin user has the `PLATFORM_ADMIN` role with full permissions. You can use this account to:
+- Manage users and roles
+- Register new applications
+- Configure the platform
+
+## Development Workflow Quick Overview
+
+### For Path 1 Users (Pre-built Images)
+
+If you used pre-built images, your workflow focuses on building your product:
+
+#### Adding Your First Custom Service
+
+1. Create your service (can be in any language/framework)
+2. Build a Docker image for your service
+3. Register it in the application catalog via bootstrap configuration
+4. Add it to `docker-compose-pae.yml` in your product
+5. Restart to load the new service
+
+#### Updating Platform Versions
+
+To update to a newer version of the platform:
+
+```bash
+# In your product's docker-compose-pae.yml, update the image tags
+# From: ghcr.io/bluealba/pae-nestjs-gateway-service:v2.1.0
+# To:   ghcr.io/bluealba/pae-nestjs-gateway-service:v2.2.0
+
+# Then restart services
+docker-compose -f docker-compose-pae.yml pull
+docker-compose -f docker-compose-pae.yml up -d
+```
+
+### For Path 2 Users (Source Code)
+
+If you're working with platform source code:
+
+#### Running Services in Dev Mode
+
+To work on the Gateway Service with hot reload:
+
+```bash
+# Stop the Docker container first
+docker-compose -f docker-compose-pae.yml stop pae-nestjs-gateway-service
+
+# Run locally with hot reload
+cd ../bluealba-platform/apps/pae-nestjs-gateway-service
+npm run dev
+```
+
+#### Running UIs in Dev Mode
+
+To work on the Shell UI with hot reload:
+
+```bash
+cd ../bluealba-platform/apps/pae-shell-ui
+npm run dev
+```
+
+The UI will be available at `http://localhost:8080` with hot module replacement enabled.
+
+#### Making Changes to Platform Code
+
+1. Make your code changes in the `bluealba-platform` directory
+2. Rebuild if needed: `npx turbo build`
+3. Restart the affected service in Docker
+4. Create a changeset before committing:
+
+```bash
+npm run changeset
+```
+
+## Troubleshooting
+
+### Services won't start
+
+**Issue**: Docker containers fail to start or show errors.
+
+**Solution**: Check the logs for specific errors:
+
+```bash
+docker-compose -f docker-compose-pae.yml logs pae-nestjs-gateway-service
+```
+
+Common issues:
+- Ports already in use (stop other services on ports 9443, 5432, 9092)
+- Insufficient Docker memory (allocate at least 4GB in Docker Desktop settings)
+- SSL certificate paths incorrect (verify ssl/ directory exists)
+
+### Cannot connect to database
+
+**Issue**: Services can't connect to PostgreSQL.
+
+**Solution**: Ensure the infrastructure is running:
+
+```bash
+docker-compose -f docker-compose-infra.yml ps
+```
+
+Check PostgreSQL logs:
+
+```bash
+docker-compose -f docker-compose-infra.yml logs postgres
+```
+
+Restart if needed:
+
+```bash
+docker-compose -f docker-compose-infra.yml restart postgres
+```
+
+### Bootstrap fails
+
+**Issue**: Bootstrap container exits with errors.
+
+**Solution**: Check bootstrap logs:
+
+```bash
+docker-compose -f docker-compose-bootstrap.yml logs
+```
+
+Common issues:
+- Database not ready (wait 30 seconds after starting infra)
+- Invalid JSON in bootstrap files (validate JSON syntax)
+- Missing environment variables (check .env file)
+
+To re-run bootstrap after fixing issues:
+
+```bash
+docker-compose -f docker-compose-bootstrap.yml up
+```
+
+### SSL certificate errors
+
+**Issue**: Browser shows SSL warnings or refuses to connect.
+
+**Solution**: This is expected for local development. The platform uses self-signed certificates. You can:
+- Accept the warning and proceed (recommended for dev)
+- Use HTTP on port 9080 instead: `http://localhost:9080`
+- Regenerate certificates if they're corrupted (run the openssl command again)
+
+### Gateway Service won't start
+
+**Issue**: Gateway container exits or shows health check failures.
+
+**Solution**:
+
+1. Check that SSL certificate paths are correct
+2. Verify database is accessible
+3. Check logs for specific errors:
+
+```bash
+docker-compose -f docker-compose-pae.yml logs pae-nestjs-gateway-service
+```
+
+**Path 2 only**: Verify the build completed successfully in bluealba-platform.
+
+### Shell UI shows blank page
+
+**Issue**: Shell UI loads but shows a blank page.
+
+**Solution**:
+
+1. Check browser console for errors (F12)
+2. Verify nginx configuration is correct
+3. Check Shell UI container logs:
+
+```bash
+docker-compose -f docker-compose-pae.yml logs pae-shell-ui
+```
+
+**Path 2 only**: Verify the Shell UI was built by checking that `bluealba-platform/apps/pae-shell-ui/dist/` exists.
+
+### Image pull failures (Path 1)
+
+**Issue**: Docker cannot pull platform images.
+
+**Solution**:
+
+1. Verify you have internet connectivity
+2. Check if the image version exists:
+
+```bash
+docker pull ghcr.io/bluealba/pae-nestjs-gateway-service:v2.1.0
+```
+
+3. If using a private registry, ensure you're authenticated:
+
+```bash
+docker login ghcr.io
+```
+
+### Port conflicts
+
+**Issue**: "Port already in use" errors.
+
+**Solution**: Find and kill processes using the ports:
+
+```bash
+# Find process on port 9443
+lsof -i :9443
+
+# Kill the process
+kill -9 <PID>
+```
+
+Or change the port mappings in the docker-compose files:
+
+```yaml
+ports:
+  - "9090:80"    # Change external port from 9080 to 9090
+  - "9444:443"   # Change external port from 9443 to 9444
+```
+
+### Build failures in bluealba-platform (Path 2)
+
+**Issue**: `turbo build` fails with errors.
+
+**Solution** (Path 2 users only):
+
+1. Ensure you're using Node.js 20+ and npm 10.8.2:
+
+```bash
+node --version
+npm --version
+```
+
+2. Clean and reinstall:
+
+```bash
+npx turbo clean
+rm -rf node_modules package-lock.json
+npm install
+npx turbo build
+```
+
+3. Check for disk space (build requires several GB)
+
+### Docker network issues
+
+**Issue**: Services can't communicate with each other.
+
+**Solution**: Ensure the Docker network exists:
+
+```bash
+docker network ls | grep pae-network
+```
+
+If missing, create it:
+
+```bash
+docker network create pae-network
+```
+
+Then restart all services.
+
+## Next Steps
+
+Congratulations! You now have a fully functional Blue Alba Platform running locally with your own white-label product.
+
+Here's what to explore next:
+
+1. **Add More Services** - Create microservices for your business logic
+2. **Customize the Shell UI** - Modify the look and feel to match your brand
+3. **Create Custom Modules** - Build micro-frontend modules for your features
+4. **Configure Multi-Tenancy** - Set up tenant isolation for your product
+5. **Integrate Authentication** - Add SSO, OAuth, or other auth providers
+
+### Recommended Learning Path
+
+1. **[Core Concepts](/_/docs/getting-started/core-concepts/)** - Understand applications, modules, operations, and roles
+2. **[Development Workflow](/_/docs/development/workflow/)** - Master the day-to-day development process
+3. **[Architecture Overview](/_/docs/architecture/overview/)** - Deep dive into the platform architecture
+4. **[Creating Services Guide](/_/docs/guides/creating-services/)** - Learn to build microservices
+5. **[Creating UI Modules Guide](/_/docs/guides/creating-ui-modules/)** - Build micro-frontend modules
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the detailed [Installation Guide](/_/docs/getting-started/installation/) for more context
+2. Examine Docker logs for error messages: `docker-compose logs <service-name>`
+3. Review the bootstrap logs if platform setup fails
+4. Consult the repository's GitHub Issues for known problems
+5. **Path 2 users**: Review service-specific README files in the `bluealba-platform/apps/` directories
+
+## What Makes This White-Label?
+
+The minimal product you just created is a foundation for building any type of application:
+
+- **No pre-built features** - Start with a clean slate
+- **Your branding** - Customize the UI, logos, and theme
+- **Your services** - Add only the microservices you need
+- **Your data model** - Define your own database schemas
+- **Your business logic** - Implement your unique requirements
+
+The platform provides the infrastructure (auth, routing, module loading, multi-tenancy) while you build the features that make your product unique.
+
+Happy building!