Coolify CI/CD testing
This commit is contained in:
Ducky SSH User
365
DOCKER.md
Normal file
365
DOCKER.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Docker & Coolify Deployment Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Nerd Monitor is optimized for containerized deployment using Docker and Coolify CI/CD. This guide covers setup with Coolify, local development with Docker Compose, and deployment options.
|
||||
|
||||
## Quick Start with Coolify
|
||||
|
||||
### Prerequisites
|
||||
- Gitea repository configured
|
||||
- Coolify instance running
|
||||
- Docker/container runtime available
|
||||
|
||||
### Setup Steps
|
||||
|
||||
1. **Connect Repository to Coolify**
|
||||
- In Coolify, add new application
|
||||
- Select "Git Repository"
|
||||
- Choose your Gitea instance
|
||||
- Select `nerd-monitor` repository
|
||||
|
||||
2. **Configure Build Settings**
|
||||
- **Build Pack**: Dockerfile
|
||||
- **Dockerfile Path**: `./Dockerfile`
|
||||
- **Build Context**: `.` (root)
|
||||
- **Docker Image**: `nerd-monitor-server:latest`
|
||||
|
||||
3. **Set Environment Variables**
|
||||
In Coolify environment configuration:
|
||||
```
|
||||
ADDR=0.0.0.0
|
||||
PORT=8080
|
||||
USERNAME=admin
|
||||
PASSWORD=secure_password_here
|
||||
```
|
||||
|
||||
4. **Enable Auto-Deploy**
|
||||
- Set **Watch** to: `master`
|
||||
- Enable **Auto-deploy on push**
|
||||
- Coolify will automatically build and deploy on every push to master
|
||||
|
||||
5. **Configure Ports**
|
||||
- **Container Port**: 8080
|
||||
- **Public Port**: 8080 (or as needed)
|
||||
- **Protocol**: HTTP/HTTPS
|
||||
|
||||
6. **Set Resource Limits** (optional)
|
||||
- CPU: 500m - 1000m
|
||||
- Memory: 256MB - 512MB
|
||||
|
||||
## Docker Files Included
|
||||
|
||||
### Dockerfile
|
||||
- **Purpose**: Multi-stage build for the server
|
||||
- **Base Image**: Alpine (lightweight)
|
||||
- **Final Size**: ~40MB
|
||||
- **User**: Non-root (nerdmonitor)
|
||||
- **Health Check**: Enabled
|
||||
|
||||
### Dockerfile.agent
|
||||
- **Purpose**: Container for agent deployment
|
||||
- **Use Case**: Running agents in containerized environments
|
||||
- **Base Image**: Alpine
|
||||
- **Size**: ~15MB
|
||||
|
||||
### docker-compose.yml
|
||||
- **Purpose**: Local development and testing
|
||||
- **Services**: Server + Demo Agent
|
||||
- **Network**: Bridged (isolated)
|
||||
- **Volume**: Logs persistence
|
||||
|
||||
### .dockerignore
|
||||
- **Purpose**: Optimize build context
|
||||
- **Excludes**: Git files, IDE configs, documentation
|
||||
- **Benefit**: Faster builds, smaller context
|
||||
|
||||
## Local Development
|
||||
|
||||
### Using Docker Compose
|
||||
|
||||
Start the full stack locally:
|
||||
|
||||
```bash
|
||||
# Build and start all services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f server
|
||||
|
||||
# Stop all services
|
||||
docker-compose down
|
||||
|
||||
# Remove volumes (clean slate)
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
Access dashboard:
|
||||
- URL: http://localhost:8080
|
||||
- Username: admin
|
||||
- Password: admin
|
||||
|
||||
### Manual Docker Commands
|
||||
|
||||
Build server image:
|
||||
```bash
|
||||
docker build -t nerd-monitor-server:latest -f Dockerfile .
|
||||
```
|
||||
|
||||
Run server container:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name nerd-monitor-server \
|
||||
-p 8080:8080 \
|
||||
-e USERNAME=admin \
|
||||
-e PASSWORD=admin \
|
||||
nerd-monitor-server:latest
|
||||
```
|
||||
|
||||
Build agent image:
|
||||
```bash
|
||||
docker build -t nerd-monitor-agent:latest -f Dockerfile.agent .
|
||||
```
|
||||
|
||||
Run agent container:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name nerd-monitor-agent \
|
||||
-e SERVER=server-ip:8080 \
|
||||
nerd-monitor-agent:latest
|
||||
```
|
||||
|
||||
## Coolify Deployment Flow
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Push to master │
|
||||
│ (Git commit) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Gitea Webhook │
|
||||
│ notifies Coolify │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Coolify receives │
|
||||
│ build trigger │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Coolify clones │
|
||||
│ repository │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Docker build │
|
||||
│ executes Dockerfile│
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Multi-stage build: │
|
||||
│ 1. Build binaries │
|
||||
│ 2. Create runtime │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Image pushed to │
|
||||
│ registry (local) │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Coolify stops old │
|
||||
│ container │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Coolify starts new │
|
||||
│ container │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Health check │
|
||||
│ verifies service │
|
||||
└────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ ✅ Deployment │
|
||||
│ Complete │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
## Image Specifications
|
||||
|
||||
### Server Image
|
||||
- **Name**: nerd-monitor-server
|
||||
- **Tag**: latest (or version-based)
|
||||
- **Size**: ~40MB
|
||||
- **Base**: alpine:latest
|
||||
- **User**: nerdmonitor (uid: 1000)
|
||||
- **Port**: 8080
|
||||
- **Health Check**: Yes (30s interval)
|
||||
|
||||
### Agent Image
|
||||
- **Name**: nerd-monitor-agent
|
||||
- **Tag**: latest
|
||||
- **Size**: ~15MB
|
||||
- **Base**: alpine:latest
|
||||
- **User**: nerdmonitor (uid: 1000)
|
||||
- **Stateless**: Yes (no persistent storage)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Server
|
||||
```
|
||||
ADDR=0.0.0.0 # Server bind address
|
||||
PORT=8080 # Server port
|
||||
USERNAME=admin # Admin username
|
||||
PASSWORD=admin # Admin password (change!)
|
||||
```
|
||||
|
||||
### Agent
|
||||
```
|
||||
SERVER=localhost:8080 # Server address:port
|
||||
INTERVAL=15s # Reporting interval
|
||||
```
|
||||
|
||||
## Build Optimization
|
||||
|
||||
The Dockerfile uses several optimization techniques:
|
||||
|
||||
1. **Multi-stage Build**
|
||||
- Builder stage: Includes compiler toolchain
|
||||
- Runtime stage: Only includes runtime dependencies
|
||||
- Result: Minimal final image size
|
||||
|
||||
2. **Alpine Linux**
|
||||
- Lightweight base image (5-10MB)
|
||||
- Includes essentials only
|
||||
- Fast pull and startup
|
||||
|
||||
3. **Binary Optimization**
|
||||
- `-w -s` flags strip debug symbols
|
||||
- Reduces binary size by ~30%
|
||||
- No runtime impact
|
||||
|
||||
4. **Non-root User**
|
||||
- Improved security
|
||||
- Prevents privilege escalation
|
||||
- Best practice for containers
|
||||
|
||||
5. **Health Checks**
|
||||
- Automatic service monitoring
|
||||
- Coolify/Kubernetes aware
|
||||
- Allows orchestration decisions
|
||||
|
||||
## Production Checklist
|
||||
|
||||
- [ ] Change USERNAME and PASSWORD in Coolify
|
||||
- [ ] Enable HTTPS/SSL certificate
|
||||
- [ ] Configure resource limits (CPU/Memory)
|
||||
- [ ] Set up logging aggregation
|
||||
- [ ] Configure backup strategy (if needed)
|
||||
- [ ] Enable monitoring/alerts
|
||||
- [ ] Test rollback procedure
|
||||
- [ ] Document deployment process
|
||||
- [ ] Set up redundancy if needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails
|
||||
- Check Dockerfile syntax
|
||||
- Verify build context includes all files
|
||||
- Review build logs in Coolify
|
||||
- Ensure .dockerignore isn't excluding source files
|
||||
|
||||
### Container Won't Start
|
||||
- Check environment variables are set
|
||||
- Verify port isn't already in use
|
||||
- Check Docker logs: `docker logs container-name`
|
||||
- Verify health check endpoint is accessible
|
||||
|
||||
### Deployment Shows Unhealthy
|
||||
- Check network connectivity
|
||||
- Verify PORT environment variable matches exposed port
|
||||
- Review health check command
|
||||
- Check application logs
|
||||
|
||||
### Image Size Too Large
|
||||
- Remove unnecessary files from .dockerignore
|
||||
- Use `docker image inspect` to analyze layers
|
||||
- Consider multi-stage build optimization
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Caching**
|
||||
- Copy go.mod/go.sum first (cached layer)
|
||||
- Copy source code second
|
||||
- Docker reuses layers if unchanged
|
||||
|
||||
2. **Build Speed**
|
||||
- Use `docker buildx` for faster builds
|
||||
- Enable BuildKit: `DOCKER_BUILDKIT=1`
|
||||
- Parallelize stages if possible
|
||||
|
||||
3. **Runtime Performance**
|
||||
- Alpine is lightweight but bare-bones
|
||||
- Add tools only as needed
|
||||
- Monitor resource usage
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Private Container Registry
|
||||
If using private Docker registry:
|
||||
|
||||
```bash
|
||||
# In Coolify, set registry credentials
|
||||
docker login private-registry.example.com
|
||||
|
||||
# In docker-compose, use:
|
||||
image: private-registry.example.com/nerd-monitor-server:latest
|
||||
```
|
||||
|
||||
### Multi-architecture Builds
|
||||
Build for multiple architectures:
|
||||
|
||||
```bash
|
||||
docker buildx build \
|
||||
--platform linux/amd64,linux/arm64 \
|
||||
-t nerd-monitor-server:latest \
|
||||
-f Dockerfile .
|
||||
```
|
||||
|
||||
### Custom Base Images
|
||||
Modify Dockerfile FROM directive:
|
||||
|
||||
```dockerfile
|
||||
# Use different base image if needed
|
||||
FROM golang:1.23-bookworm # Debian-based
|
||||
FROM golang:1.23-bullseye # Another option
|
||||
```
|
||||
|
||||
## Support & Documentation
|
||||
|
||||
- Review Dockerfile comments for details
|
||||
- Check Coolify documentation for advanced features
|
||||
- See README.md for general project info
|
||||
- Review AGENTS.md for development guidelines
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Commit Docker files: `git add Dockerfile*`
|
||||
2. Push to master: `git push origin master`
|
||||
3. Coolify will automatically detect and build
|
||||
4. Monitor build progress in Coolify UI
|
||||
5. Access deployed application once ready
|
||||
Reference in New Issue
Block a user