deploy

docs/DEPLOYMENT.md

@@ -0,0 +1,197 @@
+# 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