hosting-frontend/docs/DEPLOYMENT.md

Deployment Guide

Complete guide for deploying Portfolio Host to production.

Table of Contents

1. Prerequisites
2. Local Development Setup
3. Docker Build & Run
4. CI/CD Pipeline
5. Production Deployment
6. Health Checks & Monitoring
7. Troubleshooting

---

Prerequisites

• Node.js: 20.x or later
• Docker: 20.10 or later
• Docker Compose: 2.0 or later (optional)
• Git: For version control
• kubectl: For Kubernetes deployments (if using k3s)

Environment Setup

1. Clone the repository:

git clone https://github.com/your-org/hosting-frontend.git
cd hosting-frontend

2. Install dependencies:

npm install

3. Create environment files:

cp .env.local.example .env.local
cp .env.production.example .env.production

4. Configure environment variables:

# .env.production
NEXT_PUBLIC_API_URL=https://api.portfoliohost.com/api
NODE_ENV=production
NEXT_PUBLIC_ENABLE_ANALYTICS=true

---

Local Development Setup

Development Server

Start the development server:

npm run dev

Server runs at http://localhost:3000

Testing Locally

Run the full test suite:

# Run all tests
npm test

# Run tests in CI mode (one pass)
npm run test:ci

# Generate coverage report
npm run test:coverage

# Run specific test file
npm test -- --testPathPattern=navbar

Building Locally

Build for production:

npm run build

This generates the .next/ directory with optimized production artifacts.

Production Preview

Preview the production build locally:

npm run build
npm start

Server runs at http://localhost:3000

---

Docker Build & Run

Building the Docker Image

# Build image
docker build -t hosting-frontend:latest .

# Build with specific tag
docker build -t hosting-frontend:v1.0.0 .

# Build with build arguments
docker build \
  --build-arg NODE_ENV=production \
  -t hosting-frontend:prod \
  .

Running the Container

# Run in foreground
docker run -p 3000:3000 hosting-frontend:latest

# Run in background
docker run -d \
  --name hosting-frontend \
  -p 3000:3000 \
  hosting-frontend:latest

# Run with environment variables
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=https://api.example.com \
  hosting-frontend:latest

# Run with volume mounting (for logs)
docker run -d \
  -p 3000:3000 \
  -v /var/log/app:/app/logs \
  hosting-frontend:latest

Checking Container Health

# Check container status
docker ps -a | grep hosting-frontend

# View container logs
docker logs hosting-frontend

# View real-time logs
docker logs -f hosting-frontend

# Test health endpoint
curl http://localhost:3000/

# Execute command in container
docker exec hosting-frontend curl http://localhost:3000/health

Docker Compose (Optional)

Create docker-compose.yml:

version: '3.8'

services:
  hosting-frontend:
    build:
      context: .
      args:
        NODE_ENV: production
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_URL: https://api.portfoliohost.com
      NODE_ENV: production
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s
    restart: unless-stopped

Run with Docker Compose:

docker-compose up -d
docker-compose logs -f
docker-compose down

---

CI/CD Pipeline

Gitea CI/CD Workflows

The project includes two CI/CD workflows:

1. Test & Validate Workflow

• Trigger: Push to main or develop branches
• File: .gitea/workflows/test-and-validate.yml
• Steps:
  1. Checkout code
  2. Setup Node.js 20
  3. Install dependencies
  4. Run linter
  5. Run tests with coverage
  6. Validate coverage threshold (90%)
  7. Build Next.js application
  8. Validate bundle size (<250MB)
  9. Build and test Docker image
  10. Run Docker health checks

2. Production Deployment Workflow

• Trigger: Push tags starting with PROD
• File: .gitea/workflows/deploy-prod.yml
• Steps:
  1. Build Next.js application
  2. Build Docker image
  3. Push to container registry
  4. Configure kubectl
  5. Deploy to Kubernetes (k3s)
  6. Wait for rollout completion

Running CI/CD Locally

Test the workflow locally using act:

# Install act
brew install act  # macOS
# or download from https://github.com/nektos/act

# Run the test workflow
act push -j test-and-validate

# Run specific workflow
act -l  # List available workflows

Environment Secrets

Configure these secrets in Gitea:

PROD_API_URL              = https://api.portfoliohost.com/api
REGISTRY_URL              = registry.example.com
REGISTRY_USER             = your-username
REGISTRY_PASSWORD         = your-password
KUBE_CONFIG               = your-kubeconfig-content

---

Production Deployment

Prerequisites for Production

1. Kubernetes Cluster (k3s recommended)
2. Container Registry (Docker Hub, Private Registry, etc.)
3. DNS Configuration (for custom domain)
4. SSL/TLS Certificate (Let's Encrypt or custom)

Deployment Process

Step 1: Prepare Release

# Create and push release tag
git tag PROD-v1.0.0
git push origin PROD-v1.0.0

This triggers the CI/CD pipeline automatically.

Step 2: Monitor Deployment

# Watch deployment status
kubectl rollout status deployment/hosting-frontend -n hosting

# Check pod status
kubectl get pods -n hosting

# View logs
kubectl logs -f deployment/hosting-frontend -n hosting

# Describe deployment
kubectl describe deployment hosting-frontend -n hosting

Step 3: Verify Deployment

# Check service endpoint
kubectl get service hosting-frontend -n hosting

# Test health endpoint
curl https://portfoliohost.com/

# Test API connectivity
curl https://portfoliohost.com/api/health

Kubernetes Manifests

Kubernetes manifests are located in deploy/k3s/prod/:

deploy/
├── k3s/
│   ├── prod/
│   │   ├── kustomization.yaml
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── ingress.yaml
│   └── staging/
│       └── ...

Manual Deployment (without CI/CD)

# Apply manifests
kubectl apply -k deploy/k3s/prod

# Update image
kubectl set image deployment/hosting-frontend \
  hosting-frontend=hosting-frontend:v1.0.0 \
  -n hosting

# Verify rollout
kubectl rollout status deployment/hosting-frontend -n hosting

---

Health Checks & Monitoring

Health Check Endpoint

The application includes a built-in health check in the Dockerfile:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"

Test manually:

curl -f http://localhost:3000/
echo $?  # 0 = healthy, 1 = unhealthy

Kubernetes Liveness & Readiness Probes

Configured in deployment manifests:

livenessProbe:
  httpGet:
    path: /
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

Monitoring

Logs

# View application logs
docker logs hosting-frontend

# View Kubernetes logs
kubectl logs -f deployment/hosting-frontend -n hosting

# Search logs
kubectl logs deployment/hosting-frontend -n hosting | grep "error"

Metrics

Check application performance:

# CPU and memory usage
kubectl top pods -n hosting

# Pod events
kubectl describe pod <pod-name> -n hosting

# Recent events
kubectl get events -n hosting --sort-by='.lastTimestamp'

---

Troubleshooting

Build Issues

Docker Build Fails

# Check Docker logs
docker logs <container-id>

# Rebuild with verbose output
docker build --progress=plain -t hosting-frontend:latest .

# Check disk space
docker system df
docker system prune  # Clean up unused images

Test Coverage Too Low

# Generate detailed coverage report
npm run test:coverage

# Check specific file coverage
npm test -- --coverage --collectCoverageFrom="components/launch-ui/*.tsx"

Runtime Issues

Container Won't Start

# Check logs
docker logs hosting-frontend

# Check if port is in use
lsof -i :3000

# Run container in interactive mode
docker run -it hosting-frontend:latest /bin/sh

Kubernetes Pod CrashLoopBackOff

# Check pod status
kubectl describe pod <pod-name> -n hosting

# View logs
kubectl logs <pod-name> -n hosting

# Check for resource issues
kubectl top nodes
kubectl top pods -n hosting

API Connection Errors

# Verify API URL
echo $NEXT_PUBLIC_API_URL

# Test API connectivity
curl https://api.portfoliohost.com/api/health

# Check environment variables in pod
kubectl exec <pod-name> -n hosting -- env | grep API

Performance Issues

Slow Application

# Check container resource limits
kubectl describe deployment hosting-frontend -n hosting

# Increase resources if needed
kubectl set resources deployment hosting-frontend \
  --requests=cpu=500m,memory=512Mi \
  --limits=cpu=1000m,memory=1Gi \
  -n hosting

# Monitor performance
kubectl top pods -n hosting --containers

High Memory Usage

# Check for memory leaks
docker stats hosting-frontend

# Restart container
docker restart hosting-frontend

# Or restart Kubernetes pod
kubectl delete pod <pod-name> -n hosting

---

Rollback Procedure

If deployment goes wrong, rollback to previous version:

# Check rollout history
kubectl rollout history deployment/hosting-frontend -n hosting

# Rollback to previous version
kubectl rollout undo deployment/hosting-frontend -n hosting

# Rollback to specific revision
kubectl rollout undo deployment/hosting-frontend -n hosting --to-revision=2

# Verify rollback
kubectl rollout status deployment/hosting-frontend -n hosting

---

Performance Optimization

Next.js Optimization

The application includes optimizations:

• ✅ Static site generation (SSG)
• ✅ Incremental Static Regeneration (ISR)
• ✅ Image optimization with Next.js Image component
• ✅ Code splitting and lazy loading
• ✅ Automatic compression

Docker Optimization

• ✅ Multi-stage build (reduces image size)
• ✅ Alpine Linux base (small footprint)
• ✅ Non-root user (security)
• ✅ Health checks (auto-restart)

Kubernetes Optimization

• ✅ Resource limits and requests
• ✅ Horizontal Pod Autoscaling (HPA)
• ✅ Pod disruption budgets
• ✅ Regular liveness/readiness probes

---

Support

For issues or questions:

1. Check logs: docker logs or kubectl logs
2. Review this guide for troubleshooting steps
3. Contact support: support@portfoliohost.com
4. Report bugs: https://github.com/your-org/hosting-frontend/issues

---

Last Updated: 2025-10-17 Version: 1.0.0