Job-Info/OPTION_2_DOCKER_COMPOSE.md

OPTION 2: DOCKER COMPOSE DEPLOYMENT - WHAT WE'VE GOT

Date: 2026-01-19
Status: Ready to Launch
Command: docker-compose up -d

---

🐳 DOCKER COMPOSE ARCHITECTURE

┌──────────────────────────────────────────────────────────────┐
│                    Docker Compose Network                     │
│                   (job-info-network)                          │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Backend Service (job-info-backend)                    │ │
│  │  ┌──────────────────────────────────────────────────┐  │ │
│  │  │ Container: Bun Runtime                          │  │ │
│  │  │ Framework: Hono Web Server                      │  │ │
│  │  │ Port: 3005                                      │  │ │
│  │  │ Health Check: /health endpoint (30s interval)   │  │ │
│  │  │                                                  │  │ │
│  │  │ Services:                                        │  │ │
│  │  │   ✓ OAuth2 authorize endpoint                  │  │ │
│  │  │   ✓ Token refresh endpoint                     │  │ │
│  │  │   ✓ Logout endpoint                            │  │ │
│  │  │   ✓ CORS configured for frontend              │  │ │
│  │  └──────────────────────────────────────────────────┘  │ │
│  └─────────────────────────────────────────────────────────┘ │
│                           ↑                                   │
│                       depends_on                              │
│                      (healthy)                                │
│                           ↓                                   │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Frontend Service (job-info-frontend)                  │ │
│  │  ┌──────────────────────────────────────────────────┐  │ │
│  │  │ Container: Node Runtime                         │  │ │
│  │  │ Framework: Vite + Svelte                        │  │ │
│  │  │ Port: 5173                                      │  │ │
│  │  │ Health Check: HTTP / (30s interval)             │  │ │
│  │  │                                                  │  │ │
│  │  │ Features:                                        │  │ │
│  │  │   ✓ Vite static serving                         │  │ │
│  │  │   ✓ OAuth2 sign-in flow                         │  │ │
│  │  │   ✓ IndexedDB job caching                       │  │ │
│  │  │   ✓ Service Worker registration                │  │ │
│  │  │   ✓ Error handling + logging                    │  │ │
│  │  │   ✓ Responsive design (mobile/tablet/desktop)  │  │ │
│  │  └──────────────────────────────────────────────────┘  │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                               │
└──────────────────────────────────────────────────────────────┘

Browser Access:
  → http://localhost:5173 (Frontend)
  → http://localhost:3005 (Backend API)

---

📦 WHAT GETS BUILT

Backend Container (Dockerfile.backend)

FROM oven/bun:latest as builder
  ↓ Installs dependencies
COPY Mode3Test/backend ./backend
COPY package.json, bunfig.toml
RUN bun install --production

FROM oven/bun:latest (Runtime stage)
  ↓ Minimal final image
COPY from builder
ENV NODE_ENV=production
ENV PORT=3005
HEALTHCHECK /health
EXPOSE 3005
CMD ["bun", "run", "dev"]

Result: Optimized Bun container with OAuth2 backend

Frontend Container (Dockerfile.frontend)

FROM node:18-alpine as builder
  ↓ Build production bundle
COPY frontend/
RUN npm ci
RUN npm run build

FROM node:18-alpine (Runtime stage)
  ↓ Lightweight static server
COPY --from=builder /app/dist ./dist
RUN npm install -g serve
HEALTHCHECK /
EXPOSE 5173
CMD ["serve", "-s", "dist", "-l", "5173"]

Result: Production-optimized frontend container (42.70 kB gzip!)

---

🔧 CONFIGURATION

Backend Environment Variables

NODE_ENV=production
PORT=3005
LOG_LEVEL=info
OAUTH_CLIENT_ID=<from env or .env file>
OAUTH_CLIENT_SECRET=<from env or .env file>
OAUTH_REDIRECT_URI=http://localhost:5173/#/callback
CORS_ORIGIN=http://localhost:5173

Frontend Environment Variables

NODE_ENV=production

Docker Network

Type: bridge
Name: job-info-network
Purpose: Secure communication between backend and frontend

---

🚀 STARTUP SEQUENCE

When you run docker-compose up -d:

1. Build Stage (First time only)
   ├─ Build backend image from Dockerfile.backend
   │  └─ Multi-stage build (builder → runtime)
   │     └─ Result: Optimized Bun container
   ├─ Build frontend image from Dockerfile.frontend
   │  └─ Multi-stage build (builder → runtime)
   │     └─ Result: Optimized Node container with production build
   └─ Create network: job-info-network

2. Container Launch
   ├─ Start backend service (job-info-backend)
   │  ├─ Listen on port 3005
   │  ├─ Wait for health check (/health)
   │  └─ Status: healthy (ready for requests)
   │
   └─ Start frontend service (job-info-frontend)
      ├─ depends_on: backend healthy ✓
      ├─ Listen on port 5173
      ├─ Serve production build
      └─ Status: healthy (ready to browse)

3. Ready for Use
   → http://localhost:5173 ✓ READY
   → http://localhost:3005 ✓ READY

---

📊 CONTAINER SPECIFICATIONS

Backend Container

Property	Value
Image	oven/bun:latest
Container Name	job-info-backend
Port	3005
Restart Policy	unless-stopped
Health Check	Every 30s, /health endpoint
Health Timeout	10s, 3 retries
Volumes	./Mode3Test/backend (read-only)
CPU	Unlimited (no limit set)
Memory	Unlimited (no limit set)

Frontend Container

Property	Value
Image	node:18-alpine
Container Name	job-info-frontend
Port	5173
Restart Policy	unless-stopped
Health Check	Every 30s, HTTP GET /
Health Timeout	10s, 3 retries
Depends On	backend (service_healthy)
CPU	Unlimited (no limit set)
Memory	Unlimited (no limit set)

---

🌐 WHAT YOU CAN DO AFTER STARTING

Access the Application

# Open in browser
http://localhost:5173

# You'll see:
✓ Job Info logo
✓ "Sign In with Microsoft" button
✓ Responsive design (works on mobile too!)

Sign In Flow

1. Click "Sign In with Microsoft"
2. Redirected to Microsoft OAuth
3. Grant permissions
4. Redirected back to: http://localhost:5173/#/callback
5. Token exchanged securely
6. Redirected to Home page
7. Jobs list loads automatically

View Application Features

✓ User profile in header
✓ Jobs displayed as cards
✓ Search bar to filter jobs
✓ Loading spinners during API calls
✓ Error messages (user-friendly)
✓ Sign out button

Monitor Containers

# See running containers
docker-compose ps

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# View specific container logs
docker-compose logs -f job-info-backend
docker-compose logs -f job-info-frontend

# Inspect backend health
curl http://localhost:3005/health

# Check frontend
curl http://localhost:5173

---

🔍 TECHNICAL DETAILS - WHAT'S RUNNING

Backend (Port 3005)

Running: Hono web server on Bun runtime
Available Endpoints:

GET  /health                          - Health check
POST /api/auth/authorize              - OAuth authorize
POST /api/auth/refresh                - Token refresh
POST /api/auth/logout                 - Sign out

Features:

• OAuth2 PKCE flow with Microsoft
• Token signing and verification
• CORS configured for frontend
• Structured logging
• Error handling
• Health checks

Frontend (Port 5173)

Running: Vite static file server with production build
Serving: 52 optimized modules (42.70 kB gzip)

Features:

• OAuth2 sign-in flow
• Token management
• Service Worker (background refresh)
• IndexedDB caching
• Responsive UI
• Error boundaries
• Structured logging

Pages:

• / - Home (job dashboard)
• /#/signin - Sign in page
• /#/callback - OAuth callback handler

---

📊 BUILD ARTIFACTS

Frontend Build Output

dist/
├── index.html                  (0.32 kB)
├── assets/
│   ├── index-XXXXX.js         (42.70 kB gzip)
│   └── index-XXXXX.css        (4.08 kB gzip)
└── service-worker.js          (included)

Total: ~47 kB gzip (Production ready!)

Backend Dependencies

Installed via bun:
├── hono@4.x                    - Web framework
├── typescript@5.9.3            - Type safety
└── [Other dependencies]

---

✅ HEALTH CHECKS

Backend Health Check

# Every 30 seconds, Docker runs:
curl -f http://localhost:3005/health

# Expected response: 200 OK
# If fails 3 times: Container marked unhealthy

Frontend Health Check

# Every 30 seconds, Docker runs:
wget --quiet --tries=1 --spider http://localhost:5173

# Expected: HTTP 200
# If fails 3 times: Container marked unhealthy

---

🔒 SECURITY FEATURES

Network Isolation

job-info-network (bridge)
├─ Backend (only accessible via network)
└─ Frontend (accessible from network)

→ No external access without port mapping
→ Containers communicate securely
→ Network policies can be enforced

Environment Variables

✓ OAuth credentials via env vars (not in code)
✓ Production mode enforced
✓ Log level configurable
✓ Secrets not exposed in image

Container Restart

Policy: unless-stopped
→ Automatically restart if container crashes
→ Preserves data across restarts
→ Supports graceful shutdown

---

📝 LOGS YOU'LL SEE

Backend Startup

[Bun startup logs]
listening on 0.0.0.0:3005
OAuth2 configured
CORS enabled for http://localhost:5173
Health check endpoint ready

Frontend Startup

[Node startup logs]
Vite dev server running
Listening on http://localhost:5173
Production build served
Service Worker registered

During OAuth Flow

[Backend logs]
POST /api/auth/authorize
Code received
Token signed
Refresh token issued

[Frontend logs]
OAuth flow initiated
Callback received
Token stored in sessionStorage
User profile fetched
Redirected to home

---

🛑 STOPPING & CLEANUP

Stop Services (Data Preserved)

docker-compose stop
# Containers stop but persist
# Can restart with: docker-compose start

Stop & Remove (Clean)

docker-compose down
# Removes containers and network
# Images remain for reuse

Full Cleanup (Everything)

docker-compose down -v
# Removes containers, network, and volumes
# Full reset for fresh start

---

🎯 WHAT TO EXPECT

First Run

Time: ~2-3 minutes (builds images)
Output: 
  ✓ Building backend image
  ✓ Building frontend image
  ✓ Starting containers
  ✓ Waiting for health checks
  ✓ Both services ready

Subsequent Runs

Time: ~30 seconds
Output:
  ✓ Containers start immediately
  ✓ Health checks pass
  ✓ Services ready

Application Ready

✓ Backend: http://localhost:3005 (healthy)
✓ Frontend: http://localhost:5173 (healthy)
✓ Sign in button visible
✓ Can proceed with OAuth flow

---

🔧 COMMON COMMANDS

# Build and start
docker-compose up -d

# View status
docker-compose ps

# View logs
docker-compose logs -f

# Stop
docker-compose stop

# Restart
docker-compose restart

# Full cleanup
docker-compose down -v

# Rebuild images
docker-compose build --no-cache

# Scale services (for testing)
docker-compose up -d --scale backend=2 --scale frontend=2

---

📚 WHAT'S INCLUDED

• ✅ Multi-stage Docker builds (optimized images)
• ✅ Health checks (automated monitoring)
• ✅ Dependency management (backend waits for healthy)
• ✅ Network isolation (secure communication)
• ✅ Environment variables (configurable)
• ✅ Volume mounts (source code binding)
• ✅ Restart policies (automatic recovery)
• ✅ Port mapping (accessible from host)

---

🎉 BOTTOM LINE

When you run docker-compose up -d:

1. Two optimized containers start (backend + frontend)
2. Network connects them securely (job-info-network)
3. Health checks monitor both (auto-restart if needed)
4. Frontend waits for backend (depends_on)
5. Everything is ready in 2-3 minutes (first run)

Then you can:

• Open http://localhost:5173 in browser
• Click "Sign In with Microsoft"
• See the full production application
• Experience all features (caching, offline, etc.)

All infrastructure & dependencies are fully automated!

---

Generated: 2026-01-19
Status: ✅ READY TO LAUNCH
Command: docker-compose up -d