Add better documentation and scripts for air-gapped deployment

Created new helper scripts:
- quickstart-airgap.sh: One-command deployment for restricted environments
- check-ready.sh: Validates that pre-built files exist before deployment

Updated documentation:
- Enhanced Dockerfile.frontend.prebuilt with clearer error messages
- Updated DEPLOYMENT.md with step-by-step quick start guide
- Updated README.md to distinguish standard vs air-gapped deployment

Key improvements:
- Clear warning that build must happen BEFORE docker-compose
- Helper script that combines build + deployment steps
- Readiness check to catch missing pre-built files early
- Better instructions for test environments with restricted npm access

This addresses the common error where Docker fails because
frontend/dist/frontend/browser doesn't exist yet.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

DEPLOYMENT.md

@@ -24,12 +24,12 @@ This uses `Dockerfile.frontend` which:
 
 ---
 
-## Option 2: Pre-built Deployment (Air-Gapped/Restricted Environments)
+## 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
+- Node.js 18+ installed locally (on a machine with npm access)
 - npm installed locally
 - No internet required during Docker build
 
@@ -37,14 +37,34 @@ Use `Dockerfile.frontend.prebuilt` for environments with restricted npm access.
 
 **Usage:**
 
-### Step 1: Build Angular app locally
+### 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
+./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:
 

Dockerfile.frontend.prebuilt

@@ -1,10 +1,15 @@
 # Dockerfile for pre-built Angular frontend (air-gapped/restricted environments)
-# Build the Angular app locally first: cd frontend && npm run build:prod
-# Then use this Dockerfile to package the pre-built files
+#
+# IMPORTANT: You must build the Angular app BEFORE running docker-compose!
+# Run this command first: ./build-for-airgap.sh
+# OR manually: cd frontend && npm install && npm run build:prod
+#
+# This Dockerfile expects frontend/dist/frontend/browser to exist
 
 FROM nginx:alpine
 
 # Copy pre-built Angular app to nginx
+# If this step fails, you need to run: ./build-for-airgap.sh
 COPY frontend/dist/frontend/browser /usr/share/nginx/html
 
 # Copy nginx configuration

README.md

@@ -36,7 +36,7 @@ A lightweight, cloud-native API for storing and querying test artifacts includin
 
 ## Quick Start
 
-### One-Command Setup
+### Standard Deployment (Internet Access)
 
 **Linux/macOS:**
 ```bash
@@ -53,6 +53,20 @@ A lightweight, cloud-native API for storing and querying test artifacts includin
 quickstart.bat
 ```
 
+### Air-Gapped/Restricted Environment Deployment
+
+**For environments with restricted npm access:**
+```bash
+./quickstart-airgap.sh
+```
+
+This script:
+1. Builds Angular locally (where npm works)
+2. Packages pre-built files into Docker
+3. Starts all services
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed instructions.
+
 ### Manual Setup with Docker Compose
 
 1. Clone the repository:

check-ready.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+echo "========================================="
+echo "Warehouse13 - Readiness Check"
+echo "========================================="
+echo ""
+
+errors=0
+
+# Check if pre-built files exist
+if [ -d "frontend/dist/frontend/browser" ]; then
+    echo "✓ Pre-built Angular files found"
+    echo "  Location: frontend/dist/frontend/browser"
+    file_count=$(ls -1 frontend/dist/frontend/browser | wc -l)
+    echo "  Files: $file_count"
+else
+    echo "✗ ERROR: Pre-built Angular files NOT found!"
+    echo "  Expected: frontend/dist/frontend/browser"
+    echo ""
+    echo "  You need to build the Angular app first:"
+    echo "  Run: ./build-for-airgap.sh"
+    echo "  OR:  cd frontend && npm install && npm run build:prod"
+    echo ""
+    errors=$((errors + 1))
+fi
+
+echo ""
+
+# Check if docker-compose.yml is configured for pre-built
+if grep -q "Dockerfile.frontend.prebuilt" docker-compose.yml; then
+    echo "✓ docker-compose.yml configured for pre-built deployment"
+else
+    echo "⚠ WARNING: docker-compose.yml may not be configured for pre-built deployment"
+    echo "  Current frontend dockerfile:"
+    grep "dockerfile:" docker-compose.yml | grep -A 1 "frontend:" | tail -1
+    echo ""
+    echo "  For air-gapped deployment, it should be: Dockerfile.frontend.prebuilt"
+fi
+
+echo ""
+
+# Check if Docker is running
+if docker info &> /dev/null; then
+    echo "✓ Docker is running"
+else
+    echo "✗ ERROR: Docker is not running or not accessible"
+    errors=$((errors + 1))
+fi
+
+echo ""
+echo "========================================="
+
+if [ $errors -eq 0 ]; then
+    echo "✓ Ready to deploy!"
+    echo ""
+    echo "Run: docker-compose up -d --build"
+    echo "Or:  ./quickstart-airgap.sh"
+    exit 0
+else
+    echo "✗ NOT ready - please fix the errors above"
+    exit 1
+fi

quickstart-airgap.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+set -e
+
+echo "========================================="
+echo "Warehouse13 - Air-Gapped Quick Start"
+echo "========================================="
+echo ""
+echo "This script is for restricted/air-gapped environments"
+echo "where npm packages cannot be downloaded during Docker build."
+echo ""
+
+# Check if we're in the right directory
+if [ ! -f "docker-compose.yml" ]; then
+    echo "Error: Must run from project root directory"
+    exit 1
+fi
+
+# Check if Docker is installed
+if ! command -v docker &> /dev/null; then
+    echo "Error: Docker is not installed. Please install Docker first."
+    exit 1
+fi
+
+# Check if Docker Compose is installed
+if ! command -v docker-compose &> /dev/null; then
+    echo "Error: Docker Compose is not installed. Please install Docker Compose first."
+    exit 1
+fi
+
+echo "Step 1: Building Angular frontend locally..."
+echo "==========================================="
+./build-for-airgap.sh
+
+echo ""
+echo "Step 2: Starting Docker containers..."
+echo "==========================================="
+docker-compose up -d --build
+
+echo ""
+echo "Step 3: Waiting for services to be ready..."
+sleep 15
+
+echo ""
+echo "========================================="
+echo "Services are running!"
+echo "========================================="
+echo ""
+echo "Frontend:         http://localhost:4200"
+echo "API:              http://localhost:8000"
+echo "API Docs:         http://localhost:8000/docs"
+echo "MinIO Console:    http://localhost:9001"
+echo "  Username: minioadmin"
+echo "  Password: minioadmin"
+echo ""
+echo "To view logs:     docker-compose logs -f"
+echo "To stop:          docker-compose down"
+echo ""
+echo "========================================="
+echo "Testing the API..."
+echo "========================================="
+
+# Wait a bit more for API to be fully ready
+sleep 5
+
+# Test health endpoint
+if curl -s http://localhost:8000/health | grep -q "healthy"; then
+    echo "✓ API is healthy!"
+    echo ""
+    echo "========================================="
+    echo "Setup complete! 🚀"
+    echo "========================================="
+else
+    echo "⚠ API is not responding yet. Please wait a moment and check http://localhost:8000/health"
+fi