warehouse13/frontend/REGISTRY-EXAMPLES.md

# 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"
```