warehouse13/docs/DEPLOYMENT.md

# Deployment Options

This project supports two deployment strategies for the Angular frontend, depending on your environment's network access.

## Option 1: Standard Build (Internet Access Required)

Use the standard `Dockerfile.frontend` which builds the Angular app inside Docker.

**Requirements:**
- Internet access to npm registry
- Docker build environment

**Usage:**
```bash
./quickstart.sh
# or
docker-compose up -d --build
```

This uses `Dockerfile.frontend` which:
1. Installs npm dependencies in Docker
2. Builds Angular app in Docker
3. Serves with nginx

---

## Option 2: Pre-built Deployment (Air-Gapped/Restricted Environments) ⭐ RECOMMENDED

Use `Dockerfile.frontend.prebuilt` for environments with restricted npm access.

**Requirements:**
- Node.js 18+ installed locally (on a machine with npm access)
- npm installed locally
- No internet required during Docker build

**Note:** This project uses Angular 17 with webpack bundler (not Vite) for better compatibility with restricted npm environments.

**Usage:**

### Quick Start (Recommended)
```bash
./quickstart-airgap.sh
```

This script will:
1. Build the Angular app locally
2. Start all Docker containers
3. Verify the deployment

### Manual Steps

### Step 1: Build Angular app locally
**IMPORTANT:** You MUST run this step BEFORE `docker-compose up`!

```bash
# Option A: Use the helper script
./scripts/build-for-airgap.sh

# Option B: Build manually
cd frontend
npm install  # Only needed once or when dependencies change
npm run build:prod
cd ..
```

This creates `frontend/dist/frontend/browser/` which Docker will copy.

### Step 2: Update docker-compose.yml
Edit `docker-compose.yml` and change the frontend dockerfile:

```yaml
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend.prebuilt  # <-- Change this line
    ports:
      - "4200:80"
    depends_on:
      - api
```

### Step 3: Build and deploy
```bash
docker-compose up -d --build
```

This uses `Dockerfile.frontend.prebuilt` which:
1. Copies pre-built Angular files from `frontend/dist/`
2. Serves with nginx
3. No npm/node required in Docker

---

## Troubleshooting

### Build Tool Package Issues

If you see errors about missing packages like:
```
Cannot find package "vite"
Cannot find package "esbuild"
Cannot find package "rollup"
```

**Solution:** This project uses Angular 17 with webpack bundler specifically to avoid these issues. If you still encounter package access problems in your restricted environment, use Option 2 (Pre-built) deployment above, which eliminates all npm dependencies in Docker.

### Custom NPM Registry

For both options, you can use a custom npm registry:

```bash
# Set in .env file
NPM_REGISTRY=http://your-npm-proxy:8081/repository/npm-proxy/

# Or inline
NPM_REGISTRY=http://your-proxy ./quickstart.sh
```

---

## Recommendation

- **Development/Cloud**: Use Option 1 (standard)
- **Air-gapped/Enterprise**: Use Option 2 (pre-built) ⭐ **RECOMMENDED**
- **CI/CD**: Use Option 2 for faster, more reliable builds
- **Restricted npm access**: Use Option 2 (pre-built) ⭐ **REQUIRED**

---

## Build Strategy for Restricted Environments

**This project uses Angular 17 with webpack** instead of Angular 19 with Vite specifically for better compatibility with restricted npm environments. Webpack has fewer platform-specific binary dependencies than Vite.

If you encounter any package access errors during builds:
- `Cannot find package "vite"`
- `Cannot find package "rollup"`
- `Cannot find package "esbuild"`
- Any platform-specific binary errors

**Solution:** Use Option 2 (Pre-built) deployment. This completely avoids npm installation in Docker and eliminates all build tool dependency issues.