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:
   ```bash
   cp env.example .env
   ```

2. Update `.env` with your values:
   ```bash
   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

```bash
# 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

```bash
# 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**:
   ```bash
   # Check logs
   docker compose logs portfolio
   
   # Check service status
   docker compose ps
   
   # Restart services
   docker compose restart
   ```

3. **Database connection issues**:
   ```bash
   # 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**:
   ```bash
   # Test Redis connection
   docker compose exec redis redis-cli ping
   
   # Check Redis logs
   docker compose logs redis
   ```

### Debug Commands

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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