Round 4 improvements: automated config, relative paths, simplified deployment
- Automate Traefik email substitution in deploy script - Auto-generate Authelia admin password (saved to ADMIN_PASSWORD.txt) - Standardize all volume paths to use relative paths (./service/config) - Switch Traefik to HTTP challenge by default (DNS challenge optional) - Update documentation with improved setup instructions - Enhance troubleshooting guide - Update AGENT_INSTRUCTIONS with new conventions - Simplify .env.example with clearer guidance These changes reduce manual configuration steps and improve deployment reliability.
This commit is contained in:
@@ -3,6 +3,41 @@
|
||||
## Primary Directive
|
||||
You are an AI agent specialized in managing Docker-based homelab infrastructure using Dockge. Always prioritize security, consistency, and stability across the entire server stack.
|
||||
|
||||
## Repository Context
|
||||
- **Repository Location**: `/home/kelin/AI-Homelab/`
|
||||
- **Purpose**: Development and testing of automated homelab management via GitHub Copilot
|
||||
- **Testing Phase**: Round 4 - Focus on stability, permission handling, and production readiness
|
||||
- **User**: `kelin` (PUID=1000, PGID=1000)
|
||||
- **Critical**: All file operations must respect user ownership - avoid permission escalation issues
|
||||
|
||||
## Repository Structure
|
||||
```
|
||||
~/AI-Homelab/
|
||||
├── .github/
|
||||
│ └── copilot-instructions.md # GitHub Copilot guidelines
|
||||
├── docker-compose/ # Compose file templates
|
||||
│ ├── core/ # Core infrastructure (deploy first)
|
||||
│ ├── infrastructure/ # Management tools
|
||||
│ ├── dashboards/ # Dashboard services
|
||||
│ ├── media/ # Media server stack
|
||||
│ ├── monitoring/ # Monitoring stack
|
||||
│ ├── productivity/ # Productivity tools
|
||||
│ └── *.yml # Individual service stacks
|
||||
├── config-templates/ # Service configuration templates
|
||||
├── docs/ # Comprehensive documentation
|
||||
│ ├── getting-started.md
|
||||
│ ├── services-reference.md
|
||||
│ ├── docker-guidelines.md
|
||||
│ ├── proxying-external-hosts.md
|
||||
│ └── troubleshooting/
|
||||
├── scripts/ # Automation scripts
|
||||
│ ├── setup-homelab.sh # First-run setup
|
||||
│ └── deploy-homelab.sh # Automated deployment
|
||||
├── .env.example # Environment template
|
||||
├── AGENT_INSTRUCTIONS.md # This file
|
||||
└── README.md # Project overview
|
||||
```
|
||||
|
||||
## Core Operating Principles
|
||||
|
||||
### 1. Docker Compose First
|
||||
@@ -28,7 +63,7 @@ You are an AI agent specialized in managing Docker-based homelab infrastructure
|
||||
```
|
||||
|
||||
### 4. Storage Strategy
|
||||
- **Config files**: `/opt/stacks/stack-name/config/`
|
||||
- **Config files**: Use relative paths `./service/config:/config` in compose files
|
||||
- **Large data**: Separate drives (`/mnt/media`, `/mnt/downloads`)
|
||||
- **Small data**: Docker named volumes
|
||||
- **Secrets**: `.env` files (never commit)
|
||||
@@ -46,7 +81,7 @@ services:
|
||||
ports:
|
||||
- "host:container" # Only if not using Traefik
|
||||
volumes:
|
||||
- /opt/stacks/stack-name/config:/config
|
||||
- ./service-name/config:/config # Relative to stack directory
|
||||
- service-data:/data
|
||||
# Large data on separate drives:
|
||||
# - /mnt/media:/media
|
||||
@@ -75,6 +110,11 @@ networks:
|
||||
external: true
|
||||
```
|
||||
|
||||
**Important Volume Path Convention:**
|
||||
- Use **relative paths** (`./<service>/config`) for service configs within the stack directory
|
||||
- Use **absolute paths** (`/mnt/media`) only for large shared data on separate drives
|
||||
- This allows stacks to be portable and work correctly in Dockge's `/opt/stacks/` structure
|
||||
|
||||
## Critical Deployment Order
|
||||
|
||||
1. **Core Stack First**: Deploy `/opt/stacks/core/docker-compose.yml`
|
||||
@@ -118,6 +158,13 @@ labels:
|
||||
|
||||
## Agent Actions Checklist
|
||||
|
||||
### Permission Safety (CRITICAL for Round 4)
|
||||
- [ ] **NEVER** use sudo for file operations in user directories
|
||||
- [ ] Always check file ownership before modifying: `ls -la`
|
||||
- [ ] Respect existing ownership - files should be owned by `kelin:kelin`
|
||||
- [ ] If permission denied, diagnose first - don't escalate privileges blindly
|
||||
- [ ] Docker operations may need sudo, but file edits in `/home/kelin/` should not
|
||||
|
||||
### Before Any Change
|
||||
- [ ] Read existing compose files for context
|
||||
- [ ] Check port availability
|
||||
@@ -142,12 +189,30 @@ labels:
|
||||
|
||||
### File Management
|
||||
- [ ] Store configs in `/opt/stacks/stack-name/`
|
||||
- [ ] Use relative paths for configs: `./service/config`
|
||||
- [ ] Use `/mnt/` for large data (>50GB)
|
||||
- [ ] Create `.env.example` templates
|
||||
- [ ] Document non-obvious configurations
|
||||
|
||||
## Common Agent Tasks
|
||||
|
||||
### Development Workflow (Round 4 Focus)
|
||||
1. **Repository Testing**
|
||||
- Test deployment scripts: `./scripts/setup-homelab.sh`, `./scripts/deploy-homelab.sh`
|
||||
- Verify compose file syntax across all stacks
|
||||
- Validate `.env.example` completeness
|
||||
- Check documentation accuracy
|
||||
|
||||
2. **Configuration Updates**
|
||||
- Modify compose files in `docker-compose/` directory
|
||||
- Update config templates in `config-templates/`
|
||||
- Ensure changes maintain backward compatibility
|
||||
|
||||
3. **Documentation Maintenance**
|
||||
- Keep `docs/` synchronized with compose changes
|
||||
- Update service lists when adding new services
|
||||
- Document new features or configuration patterns
|
||||
|
||||
### Deploy New Service
|
||||
1. Create stack directory: `/opt/stacks/stack-name/`
|
||||
2. Write docker-compose.yml with template
|
||||
@@ -213,6 +278,29 @@ labels:
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### Permission-Related Crashes (Recent Issue)
|
||||
1. **Diagnose**: Check recent file operations
|
||||
- Review which files were modified
|
||||
- Check ownership: `ls -la /path/to/files`
|
||||
- Identify what triggered permission errors
|
||||
|
||||
2. **Fix Ownership Issues**
|
||||
```bash
|
||||
# For /opt/ directory (if modified during testing)
|
||||
sudo chown -R kelin:kelin /opt/stacks
|
||||
|
||||
# For repository files
|
||||
chown -R kelin:kelin ~/AI-Homelab # No sudo needed in home dir
|
||||
|
||||
# For Docker-managed directories, leave as root
|
||||
# (e.g., /opt/stacks/*/data/ created by containers)
|
||||
```
|
||||
|
||||
3. **Prevent Future Issues**
|
||||
- Edit files in `~/AI-Homelab/` without sudo
|
||||
- Only use sudo for Docker commands
|
||||
- Don't change ownership of Docker-created volumes
|
||||
|
||||
### Service Won't Start
|
||||
1. Check logs: `docker compose logs service-name`
|
||||
2. Verify YAML syntax
|
||||
@@ -251,6 +339,9 @@ labels:
|
||||
- Use `:latest` tags in production
|
||||
- Bypass security without explicit request
|
||||
- Modify core stack without understanding dependencies
|
||||
- **Use sudo for operations in `/home/kelin/` directory**
|
||||
- **Change file ownership without explicit permission**
|
||||
- **Blindly escalate privileges when encountering errors**
|
||||
|
||||
### Always Do
|
||||
- Read existing configurations first
|
||||
@@ -259,6 +350,59 @@ labels:
|
||||
- Follow established naming patterns
|
||||
- Prioritize security over convenience
|
||||
- Maintain consistency across the stack
|
||||
- **Check file permissions before operations**
|
||||
- **Respect user ownership boundaries**
|
||||
- **Ask before modifying system directories**
|
||||
|
||||
## Testing and Development Guidelines (Round 4)
|
||||
|
||||
### Repository Development
|
||||
- Work within `~/AI-Homelab/` for all development
|
||||
- Test scripts in isolated environment before production
|
||||
- Validate all YAML files before committing
|
||||
- Ensure `.env.example` stays updated with new variables
|
||||
- Document breaking changes in commit messages
|
||||
|
||||
### Permission Best Practices
|
||||
- Repository files: Owned by `kelin:kelin`
|
||||
- Docker socket: Requires docker group membership
|
||||
- `/opt/stacks/`: Owned by user, some subdirs by containers
|
||||
- Never use sudo for editing files in home directory
|
||||
|
||||
### Pre-deployment Validation
|
||||
```bash
|
||||
# Validate compose files
|
||||
docker compose -f docker-compose/core.yml config
|
||||
|
||||
# Check environment variables
|
||||
grep -v '^#' .env | grep -v '^$'
|
||||
|
||||
# Test script syntax
|
||||
bash -n scripts/deploy-homelab.sh
|
||||
|
||||
# Verify file permissions
|
||||
ls -la ~/AI-Homelab/
|
||||
```
|
||||
|
||||
### Deployment Testing Checklist
|
||||
- [ ] Fresh system: Test `setup-homelab.sh`
|
||||
- [ ] Core stack: Deploy and verify DuckDNS, Traefik, Authelia, Gluetun
|
||||
- [ ] Infrastructure: Deploy Dockge and verify web UI access
|
||||
- [ ] Additional stacks: Test individual stack deployment
|
||||
- [ ] SSO: Verify authentication works
|
||||
- [ ] SSL: Check certificate generation
|
||||
- [ ] VPN: Test Gluetun routing
|
||||
- [ ] Documentation: Validate all steps in docs/
|
||||
|
||||
### Round 4 Success Criteria
|
||||
- [ ] No permission-related crashes
|
||||
- [ ] All deployment scripts work on fresh Debian install
|
||||
- [ ] Documentation matches actual implementation
|
||||
- [ ] All 60+ services deploy successfully
|
||||
- [ ] Traefik routes all services correctly
|
||||
- [ ] Authelia protects appropriate services
|
||||
- [ ] Gluetun routes download clients through VPN
|
||||
- [ ] No sudo required for repository file editing
|
||||
|
||||
## Communication Guidelines
|
||||
|
||||
|
||||
Reference in New Issue
Block a user