# Deployment Guide

This document describes the deployment setup for KLZ Cables website.

## Automatic Deployment (Gitea Actions)

The project uses Gitea Actions for CI/CD. On every push to the `main` branch:

1. **Build**: Docker image is built with platform `linux/arm64`
2. **Push**: Image is pushed to `registry.infra.mintel.me/mintel/klz-cables.com:latest`
3. **Deploy**: SSH connection to production server pulls and restarts containers

### Workflow File

Location: `.gitea/workflows/deploy.yml`

### Required Secrets

Configure these in your Gitea repository settings:

- `REGISTRY_USER` - Docker registry username
- `REGISTRY_PASS` - Docker registry password
- `ALPHA_SSH_KEY` - SSH private key for deployment user
- `NEXT_PUBLIC_UMAMI_WEBSITE_ID` - Umami analytics website ID
- `NEXT_PUBLIC_UMAMI_SCRIPT_URL` - Umami analytics script URL
- `SENTRY_DSN` - Sentry/GlitchTip DSN for error tracking

## Manual Deployment

If you need to deploy manually:

### On the Production Server

```bash
# SSH into the server
ssh deploy@alpha.mintel.me

# Navigate to the project directory
cd /home/deploy/sites/klz-cables.com

# Pull the latest image
docker compose pull

# Restart containers
docker compose up -d --force-recreate --remove-orphans

# Clean up old images
docker image prune -f
```

## Troubleshooting

### Workflow Not Triggering

1. Check Gitea Actions is enabled in repository settings
2. Verify the workflow file syntax
3. Check runner availability with label `docker`

### Build Failures

1. Check build logs in Gitea Actions tab
2. Verify all secrets are configured correctly
3. Ensure Dockerfile is valid

### Deployment Failures

1. Verify SSH key has correct permissions (600)
2. Check deploy user has Docker permissions
3. Verify registry credentials are correct
4. Check server disk space: `df -h`

### Container Issues

```bash
# Check container status
docker compose ps

# View logs
docker compose logs -f app
docker compose logs -f varnish

# Check health
docker compose exec app wget -O- http://localhost:3000/health
```

## Architecture

```
Client
  ↓
Traefik (TLS termination, routing)
  ↓
Varnish (HTTP caching)
  ↓
Next.js App (port 3000)
```

### Services

- **app**: Next.js application
- **varnish**: HTTP cache layer
- **traefik**: Reverse proxy (external network)

### Domains

- `klz-cables.com` - Production
- `www.klz-cables.com` - Production (www)
- `staging.klz-cables.com` - Staging

## Environment Variables

### Build-time (in Dockerfile/Workflow)

- `NEXT_PUBLIC_UMAMI_WEBSITE_ID`
- `NEXT_PUBLIC_UMAMI_SCRIPT_URL`
- `NEXT_PUBLIC_SENTRY_DSN`

### Runtime (in docker-compose.yml)

- `SENTRY_DSN`
- `REDIS_URL`
- `REDIS_KEY_PREFIX`

## Monitoring

### Health Checks

- App: `https://klz-cables.com/health`
- Varnish: Configured in docker-compose.yml

### Logs

```bash
# Application logs
docker compose logs -f app

# Varnish logs
docker compose logs -f varnish

# All logs
docker compose logs -f
```

### Analytics

- Umami: Configured via environment variables
- Sentry/GlitchTip: Error tracking

## Rollback

To rollback to a previous version:

```bash
# On the server
cd /home/deploy/sites/klz-cables.com

# Pull a specific version (if tagged)
docker pull registry.infra.mintel.me/mintel/klz-cables.com:TAG

# Or rebuild from a specific commit
# (requires access to the repository on the server)

# Restart with the older image
docker compose up -d --force-recreate
```

## Performance

### Cache Invalidation

Varnish caches static assets. To clear cache:

```bash
docker compose exec varnish varnishadm "ban req.url ~ ."
```

### Cache Configuration

Edit `varnish/default.vcl` and restart:

```bash
docker compose restart varnish
```

## Security

- All secrets are stored in Gitea repository settings
- SSH key is injected at deployment time
- Registry credentials are not stored in the repository
- Deploy webhook requires secret token

## Support

For issues or questions:
1. Check logs first
2. Review this documentation
3. Contact the development team