klz-cables.com/docs/DEPLOYMENT.md

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

# 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

# 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)

These variables are baked into the Docker image during the build process.

• NEXT_PUBLIC_BASE_URL (Required)
• NEXT_PUBLIC_UMAMI_WEBSITE_ID
• NEXT_PUBLIC_UMAMI_SCRIPT_URL
• SENTRY_DSN

Runtime (in docker-compose.yml)

These variables are passed to the container at runtime.

• NODE_ENV (Defaults to production)
• NEXT_PUBLIC_BASE_URL (Must be passed again at runtime for server-side use)
• SENTRY_DSN
• MAIL_HOST
• MAIL_PORT
• MAIL_USERNAME
• MAIL_PASSWORD
• MAIL_FROM
• MAIL_RECIPIENTS
• REDIS_URL
• REDIS_KEY_PREFIX

Local Development

For local development, use a .env file. The docker-compose.override.yml file automatically loads this file for the app service.

Monitoring

Health Checks

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

Logs

# 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:

# 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:

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

Cache Configuration

Edit varnish/default.vcl and restart:

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