switch between arti and default

frontend/REGISTRY-EXAMPLES.md

@@ -0,0 +1,339 @@
+# NPM Registry - Usage Examples
+
+## Quick Reference
+
+### Use Public NPM (Default)
+```bash
+# Linux/Mac
+./quickstart.sh
+
+# Windows
+.\quickstart.ps1
+```
+
+### Use Artifactory
+```bash
+# Linux/Mac
+export ARTIFACTORY_AUTH_TOKEN="your_token_here"
+./quickstart.sh -bsf
+
+# Windows
+$env:ARTIFACTORY_AUTH_TOKEN = "your_token_here"
+.\quickstart.ps1 -Bsf
+```
+
+### Rebuild with Artifactory
+```bash
+# Linux/Mac
+export ARTIFACTORY_AUTH_TOKEN="your_token_here"
+./quickstart.sh --rebuild -bsf
+
+# Windows
+$env:ARTIFACTORY_AUTH_TOKEN = "your_token_here"
+.\quickstart.ps1 -Rebuild -Bsf
+```
+
+## Local Development (Without Docker)
+
+### Switch Registry for Local Development
+
+**Linux/Mac:**
+```bash
+cd frontend
+
+# Switch to public npm
+./switch-registry.sh public
+npm ci --force
+npm start
+
+# Switch to Artifactory
+./switch-registry.sh artifactory
+export ARTIFACTORY_AUTH_TOKEN="your_token"
+npm ci --force
+npm start
+```
+
+**Windows:**
+```powershell
+cd frontend
+
+# Switch to public npm
+.\switch-registry.ps1 public
+npm ci --force
+npm start
+
+# Switch to Artifactory
+.\switch-registry.ps1 artifactory
+$env:ARTIFACTORY_AUTH_TOKEN = "your_token"
+npm ci --force
+npm start
+```
+
+**Using NPM Scripts (Cross-platform):**
+```bash
+cd frontend
+
+# Switch to public npm
+npm run registry:public
+npm ci --force
+npm start
+
+# Switch to Artifactory
+npm run registry:artifactory
+npm ci --force
+npm start
+```
+
+## Docker Build Examples
+
+### Build Specific Service with Registry
+
+**Public NPM:**
+```bash
+docker compose build app
+```
+
+**Artifactory:**
+```bash
+# Without auth
+docker compose build app --build-arg NPM_REGISTRY=artifactory
+
+# With auth
+docker compose build app \
+  --build-arg NPM_REGISTRY=artifactory \
+  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token"
+```
+
+**Windows PowerShell:**
+```powershell
+docker compose build app `
+  --build-arg NPM_REGISTRY=artifactory `
+  --build-arg ARTIFACTORY_AUTH_TOKEN="your_token"
+```
+
+## Common Workflows
+
+### Corporate Network Development
+When working from a corporate network that requires Artifactory:
+
+1. **First time setup:**
+   ```bash
+   # Edit .npmrc.artifactory with your Artifactory URL
+   nano frontend/.npmrc.artifactory
+
+   # Set auth token (get from your Artifactory admin)
+   export ARTIFACTORY_AUTH_TOKEN="your_base64_token"
+
+   # Start with Artifactory
+   ./quickstart.sh -bsf
+   ```
+
+2. **Daily development:**
+   ```bash
+   export ARTIFACTORY_AUTH_TOKEN="your_token"
+   ./quickstart.sh -bsf
+   ```
+
+### Home/Public Network Development
+When working from home or a network with npm access:
+
+```bash
+# Just run without -bsf flag
+./quickstart.sh
+```
+
+### Switching Between Environments
+
+**Moving from Corporate to Home:**
+```bash
+# Stop existing containers
+docker compose down
+
+# Rebuild with public npm
+./quickstart.sh --rebuild
+```
+
+**Moving from Home to Corporate:**
+```bash
+# Stop existing containers
+docker compose down
+
+# Rebuild with Artifactory
+export ARTIFACTORY_AUTH_TOKEN="your_token"
+./quickstart.sh --rebuild -bsf
+```
+
+## Handling Multiple package-lock.json Files
+
+### Save lockfiles for both registries:
+
+```bash
+cd frontend
+
+# Generate public lockfile
+./switch-registry.sh public
+rm package-lock.json
+npm install
+cp package-lock.json package-lock.public.json
+
+# Generate artifactory lockfile
+./switch-registry.sh artifactory
+rm package-lock.json
+npm install
+cp package-lock.json package-lock.artifactory.json
+
+# Add to git
+git add package-lock.public.json package-lock.artifactory.json
+```
+
+### Use the appropriate lockfile:
+
+```bash
+# When using public npm
+cp package-lock.public.json package-lock.json
+npm ci
+
+# When using Artifactory
+cp package-lock.artifactory.json package-lock.json
+npm ci
+```
+
+## CI/CD Examples
+
+### GitHub Actions
+
+**.github/workflows/build.yml**
+```yaml
+name: Build
+
+on: [push, pull_request]
+
+jobs:
+  build-public:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build with public npm
+        run: |
+          docker compose build app
+          docker compose up -d
+
+  build-artifactory:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build with Artifactory
+        env:
+          ARTIFACTORY_AUTH_TOKEN: ${{ secrets.ARTIFACTORY_TOKEN }}
+        run: |
+          ./quickstart.sh -bsf
+```
+
+### GitLab CI
+
+**.gitlab-ci.yml**
+```yaml
+variables:
+  NPM_REGISTRY: "public"
+
+build:public:
+  stage: build
+  script:
+    - docker compose build app
+    - docker compose up -d
+  only:
+    - main
+
+build:artifactory:
+  stage: build
+  variables:
+    NPM_REGISTRY: "artifactory"
+  script:
+    - export ARTIFACTORY_AUTH_TOKEN="${CI_ARTIFACTORY_TOKEN}"
+    - ./quickstart.sh -bsf
+  only:
+    - develop
+```
+
+### Jenkins Pipeline
+
+**Jenkinsfile**
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        ARTIFACTORY_AUTH_TOKEN = credentials('artifactory-npm-token')
+    }
+
+    stages {
+        stage('Build with Artifactory') {
+            steps {
+                sh './quickstart.sh -bsf'
+            }
+        }
+    }
+}
+```
+
+## Troubleshooting
+
+### Build fails with "Cannot find .npmrc.public"
+
+**Problem:** Registry config files are missing.
+
+**Solution:**
+```bash
+cd frontend
+# Verify files exist
+ls -la .npmrc.*
+
+# If missing, they should be committed to git
+git status
+```
+
+### "ENOENT: no such file or directory, open '/frontend/dist/frontend/browser'"
+
+**Problem:** Frontend build failed due to registry issues.
+
+**Solution:**
+```bash
+# Check build logs
+docker compose logs app | grep npm
+
+# Try rebuilding with verbose logging
+docker compose build app --no-cache --progress=plain
+```
+
+### npm ci fails with 404 errors
+
+**Problem:** Wrong registry is configured.
+
+**Solution:**
+```bash
+cd frontend
+cat .npmrc  # Check which registry is active
+
+# If using wrong one, switch:
+npm run registry:public   # or registry:artifactory
+npm ci --force
+```
+
+### Authentication fails with Artifactory
+
+**Problem:** Token is invalid or not set.
+
+**Solution:**
+```bash
+# Check token is set
+echo $ARTIFACTORY_AUTH_TOKEN  # Linux/Mac
+echo $env:ARTIFACTORY_AUTH_TOKEN  # Windows
+
+# Get new token from Artifactory UI:
+# Artifactory -> User Profile -> Generate Token
+
+# Set the token
+export ARTIFACTORY_AUTH_TOKEN="your_new_token"
+```