portfolio/DEPLOYMENT.md

Portfolio Deployment Guide

Overview

This document covers all aspects of deploying the Portfolio application, including local development, CI/CD, and production deployment.

Prerequisites

• Docker and Docker Compose installed
• Node.js 20+ for local development
• Access to Gitea repository with Actions enabled

Environment Setup

Required Secrets in Gitea

Configure these secrets in your Gitea repository (Settings → Secrets):

Secret Name	Description	Example
NEXT_PUBLIC_BASE_URL	Public URL of your website	https://dk0.dev
MY_EMAIL	Main email for contact form	contact@dk0.dev
MY_INFO_EMAIL	Info email address	info@dk0.dev
MY_PASSWORD	Password for main email	your_email_password
MY_INFO_PASSWORD	Password for info email	your_info_email_password
ADMIN_BASIC_AUTH	Admin basic auth for protected areas	admin:your_secure_password

Local Environment

1. Copy environment template:

   cp env.example .env
   

2. Update .env with your values:

   NEXT_PUBLIC_BASE_URL=https://dk0.dev
   MY_EMAIL=contact@dk0.dev
   MY_INFO_EMAIL=info@dk0.dev
   MY_PASSWORD=your_email_password
   MY_INFO_PASSWORD=your_info_email_password
   ADMIN_BASIC_AUTH=admin:your_secure_password
   

Deployment Methods

1. Local Development

# Start all services
docker compose up -d

# View logs
docker compose logs -f portfolio

# Stop services
docker compose down

2. CI/CD Pipeline (Automatic)

The CI/CD pipeline runs automatically on:

• Push to main: Runs tests, linting, build, and security checks
• Push to production: Full deployment including Docker build and deployment

Pipeline Steps:

1. Install dependencies (npm ci)
2. Run linting (npm run lint)
3. Run tests (npm run test)
4. Build application (npm run build)
5. Security scan (npm audit)
6. Build Docker image (production only)
7. Deploy with Docker Compose (production only)

3. Manual Deployment

# Build and start services
docker compose up -d --build

# Check service status
docker compose ps

# View logs
docker compose logs -f

Service Configuration

Portfolio App

• Port: 3000 (configurable via PORT environment variable)
• Health Check: http://localhost:3000/api/health
• Environment: Production
• Resources: 512M memory limit, 0.5 CPU limit

PostgreSQL Database

• Port: 5432 (internal)
• Database: portfolio_db
• User: portfolio_user
• Password: portfolio_pass
• Health Check: pg_isready

Redis Cache

• Port: 6379 (internal)
• Health Check: redis-cli ping

Troubleshooting

Common Issues

1. Secrets not loading:

   • Run the debug workflow: Actions → Debug Secrets
   • Verify all secrets are set in Gitea
   • Check secret names match exactly

2. Container won't start:

   # Check logs
   docker compose logs portfolio
   
   # Check service status
   docker compose ps
   
   # Restart services
   docker compose restart
   

3. Database connection issues:

   # Check PostgreSQL status
   docker compose exec postgres pg_isready -U portfolio_user -d portfolio_db
   
   # Check database logs
   docker compose logs postgres
   

4. Redis connection issues:

   # Test Redis connection
   docker compose exec redis redis-cli ping
   
   # Check Redis logs
   docker compose logs redis
   

Debug Commands

# Check environment variables in container
docker exec portfolio-app env | grep -E "(DATABASE_URL|REDIS_URL|NEXT_PUBLIC_BASE_URL)"

# Test health endpoints
curl -f http://localhost:3000/api/health

# View all service logs
docker compose logs --tail=50

# Check resource usage
docker stats

Monitoring

Health Checks

• Portfolio App: http://localhost:3000/api/health
• PostgreSQL: pg_isready command
• Redis: redis-cli ping command

Logs

# Follow all logs
docker compose logs -f

# Follow specific service logs
docker compose logs -f portfolio
docker compose logs -f postgres
docker compose logs -f redis

Security

Security Scans

• NPM Audit: Runs automatically in CI/CD
• Dependency Check: Checks for known vulnerabilities
• Secret Detection: Prevents accidental secret commits

Best Practices

• Never commit secrets to repository
• Use environment variables for sensitive data
• Regularly update dependencies
• Monitor security advisories

Backup and Recovery

Database Backup

# Create backup
docker compose exec postgres pg_dump -U portfolio_user portfolio_db > backup.sql

# Restore backup
docker compose exec -T postgres psql -U portfolio_user portfolio_db < backup.sql

Volume Backup

# Backup volumes
docker run --rm -v portfolio_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz /data
docker run --rm -v portfolio_redis_data:/data -v $(pwd):/backup alpine tar czf /backup/redis_backup.tar.gz /data

Performance Optimization

Resource Limits

• Portfolio App: 512M memory, 0.5 CPU
• PostgreSQL: 256M memory, 0.25 CPU
• Redis: Default limits

Caching

• Next.js: Built-in caching
• Redis: Session and analytics caching
• Static Assets: Served from CDN

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review CI/CD pipeline logs
3. Run the debug workflow
4. Check service health endpoints