cube-ms/NPM-REGISTRY-SETUP.md

Production-ready microservice framework with health monitoring, validation, error handling, and Docker Swarm support

# 🔐 CCN NPM Registry Setup Guide

Panduan lengkap untuk setup akses ke CCN Platform Registry yang diperlukan untuk menggunakan `ccn-logging` dan dependencies lainnya.

## 🚨 **Important: Token Expiration**

CCN Registry menggunakan authentication token yang **dapat expired**. Framework cube-ms menggunakan sistem **dynamic token management** untuk menghindari masalah expired token di version control.

---

## 🚀 **Quick Setup (Recommended)**

### 1. **Automatic Setup**
```bash
# Setelah clone/create project cube-ms
npm run setup-npmrc
```

Script ini akan:
- ✅ Guide Anda mendapatkan token dari CCN DevOps Portal
- ✅ Setup `.npmrc` dengan token Anda
- ✅ Validate token dan test registry access
- ✅ Otomatis add `.npmrc` ke `.gitignore`

### 2. **Install Dependencies**
```bash
npm install
```

Jika sukses, `ccn-logging` akan terinstall dan siap digunakan.

---

## 🛠️ **Manual Setup Process**

### Step 1: Get Your CCN Token

1. **Buka CCN DevOps Portal:**
   ```
   http://devops.ccn/
   ```

2. **Navigate ke Package Feed:**
   ```
   CCN Platform Collection → _packaging → CCN.Platform
   ```

3. **Generate Connection:**
   - Click **"Connect to Feed"**
   - Select **"npm"**
   - Copy **`_password`** value (long base64 string)

4. **Example Token:**
   ```
   cnZxbW91a3NwcWEyZ3d0YmlmdTczNW9kYnBucGJ2ZnRreWxseGpvaXF4bmoyZGFqYmhtYQ==
   ```

### Step 2: Create .npmrc

1. **Copy Template:**
   ```bash
   cp .npmrc.template .npmrc
   ```

2. **Replace Token:**
   ```bash
   # Open .npmrc and replace YOUR_TOKEN_HERE with your actual token
   vim .npmrc
   ```

3. **Final .npmrc Should Look Like:**
   ```ini
   registry=http://devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/
   always-auth=true
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:username=CCN.Platform
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:_password=YOUR_ACTUAL_TOKEN_HERE
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:email=npm requires email to be set but doesn't use the value
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/:username=CCN.Platform
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/:_password=YOUR_ACTUAL_TOKEN_HERE
   //devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/:email=npm requires email to be set but doesn't use the value
   ```

### Step 3: Validate Setup

```bash
# Test registry access
npm run validate-npmrc

# Or manual test
npm ping --registry http://devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/
```

---

## 🔒 **Security Best Practices**

### ✅ **What Framework Does Automatically:**

1. **Git Ignore**: `.npmrc` otomatis ditambahkan ke `.gitignore`
2. **Template System**: Menggunakan `.npmrc.template` instead of committed `.npmrc`
3. **Validation**: Automatic token validation di `postinstall`
4. **Fallback**: Graceful handling jika token expired

### ⚠️ **Developer Responsibilities:**

1. **Never commit `.npmrc`** to version control
2. **Update token before expiration** (biasanya 90 hari)
3. **Don't share token** dengan developer lain
4. **Use personal token** untuk setiap developer

### 🚫 **Security Violations:**

```bash
# ❌ NEVER DO THIS:
git add .npmrc
git commit -m "add npmrc"

# ❌ NEVER DO THIS:
echo "MY_TOKEN=abc123" >> .env

# ❌ NEVER DO THIS:
const hardcodedToken = "cnZxbW91a3NwcWEyZ3d0...";
```

---

## 🔄 **Token Management Lifecycle**

### **When You Get New Token:**

```bash
# Update existing .npmrc
npm run setup-npmrc

# Validate new token
npm run validate-npmrc

# Clean install with new token
npm ci
```

### **When Token Expires:**

```bash
# Symptoms:
npm install
# Error: Unable to authenticate, need: Basic realm="..."

# Solution:
npm run setup-npmrc  # Get new token
npm install           # Retry install
```

### **Team Collaboration:**

```bash
# Each developer needs their own token:
# 1. Developer A: Gets token A, creates .npmrc
# 2. Developer B: Gets token B, creates .npmrc  
# 3. CI/CD: Uses service account token

# ✅ Good: Each has personal .npmrc (not committed)
# ❌ Bad: Sharing one .npmrc file
```

---

## 🤖 **Automation & CI/CD**

### **GitHub Actions Example:**

```yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Setup CCN Registry
        run: |
          echo "registry=http://devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/" > .npmrc
          echo "always-auth=true" >> .npmrc
          echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:username=CCN.Platform" >> .npmrc
          echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:_password=${{ secrets.CCN_NPM_TOKEN }}" >> .npmrc
          echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:email=ci@company.com" >> .npmrc
      
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests
        run: npm test
```

### **Docker Example:**

```dockerfile
# Dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Setup CCN Registry (use ARG for build-time secret)
ARG CCN_NPM_TOKEN
RUN echo "registry=http://devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/" > .npmrc && \
    echo "always-auth=true" >> .npmrc && \
    echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:username=CCN.Platform" >> .npmrc && \
    echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:_password=${CCN_NPM_TOKEN}" >> .npmrc && \
    echo "//devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/:email=docker@company.com" >> .npmrc

# Install dependencies
RUN npm ci --only=production

# Remove .npmrc after install (security)
RUN rm .npmrc

# Copy app source
COPY . .

# Start app
CMD ["npm", "start"]
```

```bash
# Build with token
docker build --build-arg CCN_NPM_TOKEN="your-token" -t my-app .
```

---

## 🆘 **Troubleshooting**

### **1. "Cannot resolve 'ccn-logging'"**

```bash
# Check registry configuration
cat .npmrc

# Validate token
npm run validate-npmrc

# Test registry access
npm ping --registry http://devops.ccn/CCN%20Platform%20Collection/_packaging/CCN.Platform/npm/registry/

# If fails, get new token:
npm run setup-npmrc
```

### **2. "Authentication failed"**

```bash
# Token expired or invalid
npm run setup-npmrc  # Get new token

# Clear npm cache
npm cache clean --force

# Retry install
npm install
```

### **3. "403 Forbidden"**

```bash
# Check if you have access to CCN Platform Collection
# Contact DevOps team for access

# Verify correct registry URL
grep registry .npmrc
```

### **4. "502 Bad Gateway"**

```bash
# CCN registry might be down
# Check with DevOps team

# Temporary: Use fallback registry
npm install --registry https://registry.npmjs.org/
```

### **5. "Module not found" in Production**

```bash
# Ensure .npmrc is available during production build
# For Docker: use build args
# For CI/CD: use secrets
```

---

## 📋 **Quick Commands Reference**

| Command | Purpose |
|---------|---------|
| `npm run setup-npmrc` | Interactive .npmrc setup |
| `npm run validate-npmrc` | Check if token is valid |
| `cp .npmrc.template .npmrc` | Manual template copy |
| `npm ping --registry http://devops.ccn/...` | Test registry connectivity |
| `npm cache clean --force` | Clear npm cache |
| `rm .npmrc && npm run setup-npmrc` | Reset .npmrc completely |

---

## 🎯 **Best Practices Summary**

### ✅ **Do:**
- Use `npm run setup-npmrc` for setup
- Keep `.npmrc` in `.gitignore`
- Use personal tokens for each developer
- Update tokens before expiration
- Test registry access after setup

### ❌ **Don't:**
- Commit `.npmrc` to git
- Share tokens between developers
- Hardcode tokens in code
- Use expired tokens
- Skip token validation

### 🔄 **Regular Maintenance:**
- Check token expiry monthly
- Update team tokens quarterly
- Monitor registry access in CI/CD
- Keep backup of working `.npmrc`

---

*Remember: Token management adalah responsibility setiap developer. Framework hanya menyediakan tools untuk memudahkan proses ini.*