Marc Mintel
8242687b07
All checks were successful
Build & Deploy KLZ Cables / build-and-deploy (push) Successful in 3m46s
215 lines
4.5 KiB
Markdown
215 lines
4.5 KiB
Markdown
# 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)
|
|
|
|
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
|
|
|
|
```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
|