Wiki v1.0
Added a wiki
This commit is contained in:
kelinfoxy
@@ -0,0 +1,428 @@
|
||||
====== Code Server ======
|
||||
|
||||
Code Server is a web-based version of Visual Studio Code that runs in your browser, providing a full development environment accessible from anywhere. It includes all VS Code features, extensions, and integrates with your homelab development workflow.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Browser-based code editor
|
||||
**URL:** https://code.yourdomain.duckdns.org
|
||||
**Authentication:** Authelia SSO protected
|
||||
**Deployment:** Infrastructure stack
|
||||
**Interface:** Full VS Code web interface
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**VS Code Features:**
|
||||
* **Full IDE**: Complete Visual Studio Code experience
|
||||
* **Extensions**: Access to VS Code marketplace
|
||||
* **Themes**: All VS Code themes and customization
|
||||
* **Git Integration**: Built-in Git version control
|
||||
|
||||
**Web Access:**
|
||||
* **Browser-based**: Access from any device
|
||||
* **Responsive Design**: Works on desktop and mobile
|
||||
* **Persistent Sessions**: Maintain work sessions
|
||||
* **File Synchronization**: Sync across devices
|
||||
|
||||
**Development Tools:**
|
||||
* **Terminal Integration**: Built-in terminal access
|
||||
* **Debugging**: Full debugging capabilities
|
||||
* **Extensions**: Python, Docker, GitHub Copilot
|
||||
* **Language Support**: 50+ programming languages
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
code-server:
|
||||
image: lscr.io/linuxserver/code-server:latest
|
||||
container_name: code-server
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- TZ=${TZ}
|
||||
- PASSWORD=${CODE_SERVER_PASSWORD}
|
||||
- SUDO_PASSWORD=${CODE_SERVER_PASSWORD}
|
||||
- PROXY_DOMAIN=${DOMAIN}
|
||||
- DEFAULT_WORKSPACE=/config/workspace
|
||||
volumes:
|
||||
- ./code-server/config:/config
|
||||
- /opt/stacks:/opt/stacks:ro
|
||||
- /home/kelin/AI-Homelab:/workspace
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
memory: 1G
|
||||
reservations:
|
||||
cpus: '0.2'
|
||||
memory: 256M
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.code-server.rule=Host(`code.${DOMAIN}`)"
|
||||
- "traefik.http.routers.code-server.entrypoints=websecure"
|
||||
- "traefik.http.routers.code-server.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.code-server.middlewares=authelia@docker"
|
||||
- "traefik.http.services.code-server.loadbalancer.server.port=8443"
|
||||
- "x-dockge.url=https://code.${DOMAIN}"
|
||||
```
|
||||
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
# User permissions
|
||||
PUID=1000
|
||||
PGID=1000
|
||||
|
||||
# Authentication
|
||||
PASSWORD=your-secure-password
|
||||
SUDO_PASSWORD=your-secure-password
|
||||
|
||||
# Domain configuration
|
||||
PROXY_DOMAIN=yourdomain.duckdns.org
|
||||
|
||||
# Default workspace
|
||||
DEFAULT_WORKSPACE=/config/workspace
|
||||
```
|
||||
|
||||
===== Getting Started =====
|
||||
|
||||
**Initial Access:**
|
||||
1. **Access URL**: Visit https://code.yourdomain.duckdns.org
|
||||
2. **Authelia Login**: Authenticate with SSO
|
||||
3. **Password Setup**: Enter container password
|
||||
4. **Workspace Setup**: Configure your workspace
|
||||
|
||||
**Interface Overview:**
|
||||
* **Explorer**: File and folder navigation
|
||||
* **Editor**: Code editing with syntax highlighting
|
||||
* **Terminal**: Integrated command line access
|
||||
* **Extensions**: VS Code extension marketplace
|
||||
* **Settings**: Full VS Code configuration
|
||||
|
||||
===== Workspace Configuration =====
|
||||
|
||||
**Directory Mounting:**
|
||||
```yaml
|
||||
volumes:
|
||||
# AI-Homelab repository
|
||||
- /home/kelin/AI-Homelab:/workspace
|
||||
|
||||
# Stack configurations
|
||||
- /opt/stacks:/opt/stacks:ro
|
||||
|
||||
# User configuration
|
||||
- ./code-server/config:/config
|
||||
```
|
||||
|
||||
**Workspace Settings:**
|
||||
```json
|
||||
// .vscode/settings.json in workspace
|
||||
{
|
||||
"python.defaultInterpreterPath": "/usr/bin/python3",
|
||||
"git.enableSmartCommit": true,
|
||||
"editor.formatOnSave": true,
|
||||
"terminal.integrated.shell.linux": "/bin/bash"
|
||||
}
|
||||
```
|
||||
|
||||
**Recommended Extensions:**
|
||||
* **GitHub Copilot**: AI-powered code completion
|
||||
* **Python**: Python language support
|
||||
* **Docker**: Container management
|
||||
* **GitLens**: Enhanced Git capabilities
|
||||
* **Remote SSH**: Remote development
|
||||
|
||||
===== Development Workflow =====
|
||||
|
||||
**Homelab Development:**
|
||||
* **Stack Editing**: Edit docker-compose.yml files
|
||||
* **Configuration Management**: Modify service configurations
|
||||
* **Script Development**: Create automation scripts
|
||||
* **Documentation**: Edit wiki and documentation
|
||||
|
||||
**AI Integration:**
|
||||
* **GitHub Copilot**: AI-powered code suggestions
|
||||
* **AI Toolkit**: Access to AI development tools
|
||||
* **Model Testing**: Test AI models and integrations
|
||||
* **Workflow Development**: Create AI agent workflows
|
||||
|
||||
**Version Control:**
|
||||
* **Git Integration**: Full Git repository management
|
||||
* **Branch Management**: Create and manage branches
|
||||
* **Commit Management**: Stage, commit, and push changes
|
||||
* **Conflict Resolution**: Handle merge conflicts
|
||||
|
||||
===== Extensions & Customization =====
|
||||
|
||||
**Essential Extensions:**
|
||||
```json
|
||||
{
|
||||
"recommendations": [
|
||||
"ms-python.python",
|
||||
"ms-vscode.vscode-json",
|
||||
"ms-vscode-remote.remote-ssh",
|
||||
"GitHub.copilot",
|
||||
"ms-vscode.vscode-docker",
|
||||
"eamodio.gitlens",
|
||||
"ms-vscode.vscode-yaml",
|
||||
"redhat.vscode-yaml"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Theme Configuration:**
|
||||
```json
|
||||
// Dark theme with high contrast
|
||||
{
|
||||
"workbench.colorTheme": "Default Dark Modern",
|
||||
"editor.fontSize": 14,
|
||||
"editor.lineHeight": 1.6,
|
||||
"terminal.integrated.fontSize": 13
|
||||
}
|
||||
```
|
||||
|
||||
**Keybindings:**
|
||||
```json
|
||||
// Custom keybindings
|
||||
[
|
||||
{
|
||||
"key": "ctrl+shift+t",
|
||||
"command": "workbench.action.terminal.new"
|
||||
},
|
||||
{
|
||||
"key": "ctrl+shift+g",
|
||||
"command": "gitlens.showCommitSearch"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
===== Terminal Integration =====
|
||||
|
||||
**Terminal Configuration:**
|
||||
```json
|
||||
{
|
||||
"terminal.integrated.shell.linux": "/bin/bash",
|
||||
"terminal.integrated.cwd": "/workspace",
|
||||
"terminal.integrated.env.linux": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Docker Commands:**
|
||||
```bash
|
||||
# Access from terminal
|
||||
docker ps
|
||||
docker logs container-name
|
||||
docker exec -it container-name /bin/bash
|
||||
```
|
||||
|
||||
**Development Commands:**
|
||||
```bash
|
||||
# Python development
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Git operations
|
||||
git status
|
||||
git add .
|
||||
git commit -m "Update"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
===== Security Considerations =====
|
||||
|
||||
**Access Control:**
|
||||
* **Authelia Protection**: SSO authentication required
|
||||
* **Password Protection**: Additional container password
|
||||
* **Network Isolation**: Container network restrictions
|
||||
* **File Permissions**: Proper user permission mapping
|
||||
|
||||
**Data Protection:**
|
||||
* **Workspace Security**: Secure workspace access
|
||||
* **Git Credentials**: Secure Git authentication
|
||||
* **Extension Security**: Verify extension sources
|
||||
* **Session Security**: Secure web sessions
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**Resource Management:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
memory: 1G
|
||||
reservations:
|
||||
cpus: '0.2'
|
||||
memory: 256M
|
||||
```
|
||||
|
||||
**Performance Tuning:**
|
||||
* **Extension Management**: Limit active extensions
|
||||
* **File Watching**: Configure file watcher limits
|
||||
* **Memory Usage**: Monitor memory consumption
|
||||
* **Caching**: Enable appropriate caching
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**Connection Issues:**
|
||||
```bash
|
||||
# Check service status
|
||||
docker ps | grep code-server
|
||||
|
||||
# View logs
|
||||
docker logs code-server
|
||||
|
||||
# Test web access
|
||||
curl -k https://code.yourdomain.duckdns.org
|
||||
```
|
||||
|
||||
**Extension Problems:**
|
||||
* **Installation Failures**: Check network connectivity
|
||||
* **Compatibility Issues**: Verify VS Code version compatibility
|
||||
* **Permission Errors**: Check file permissions
|
||||
* **Cache Issues**: Clear extension cache
|
||||
|
||||
**Workspace Issues:**
|
||||
* **File Access**: Verify volume mount permissions
|
||||
* **Git Problems**: Check Git configuration
|
||||
* **Python Issues**: Verify Python interpreter path
|
||||
* **Extension Sync**: Check settings synchronization
|
||||
|
||||
**Performance Issues:**
|
||||
* **High CPU Usage**: Reduce active extensions
|
||||
* **Memory Problems**: Increase memory limits
|
||||
* **Slow Loading**: Clear browser cache
|
||||
* **Network Latency**: Check network performance
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs code-server`
|
||||
2. **Verify configuration**: Check environment variables
|
||||
3. **Test connectivity**: Access web interface
|
||||
4. **Clear cache**: Clear browser and extension cache
|
||||
5. **Restart service**: `docker restart code-server`
|
||||
|
||||
===== Integration with Homelab =====
|
||||
|
||||
**Stack Management:**
|
||||
* **Compose Editing**: Edit docker-compose.yml files
|
||||
* **Configuration Management**: Modify service settings
|
||||
* **Script Development**: Create deployment scripts
|
||||
* **Documentation**: Update wiki and docs
|
||||
|
||||
**AI Development:**
|
||||
* **Model Testing**: Test AI models in isolated environment
|
||||
* **Workflow Development**: Create AI agent workflows
|
||||
* **API Integration**: Develop API integrations
|
||||
* **Tool Development**: Build custom tools and extensions
|
||||
|
||||
**Monitoring & Debugging:**
|
||||
* **Log Analysis**: Analyze service logs
|
||||
* **Performance Monitoring**: Monitor system performance
|
||||
* **Network Debugging**: Debug network connectivity
|
||||
* **Container Debugging**: Debug containerized applications
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**Workspace Organization:**
|
||||
* **Project Structure**: Maintain clean project structure
|
||||
* **Version Control**: Use Git for all projects
|
||||
* **Documentation**: Document code and configurations
|
||||
* **Backup**: Regular workspace backups
|
||||
|
||||
**Development Workflow:**
|
||||
* **Branch Strategy**: Use feature branches
|
||||
* **Code Reviews**: Review code changes
|
||||
* **Testing**: Test changes before deployment
|
||||
* **Documentation**: Update documentation
|
||||
|
||||
**Security:**
|
||||
* **Access Control**: Limit workspace access
|
||||
* **Credential Management**: Secure sensitive credentials
|
||||
* **Extension Verification**: Only trusted extensions
|
||||
* **Session Management**: Proper session handling
|
||||
|
||||
**Performance:**
|
||||
* **Resource Limits**: Appropriate resource allocation
|
||||
* **Extension Management**: Keep extensions updated
|
||||
* **Cache Management**: Regular cache cleanup
|
||||
* **Optimization**: Optimize for your use case
|
||||
|
||||
===== Use Cases =====
|
||||
|
||||
**Homelab Management:**
|
||||
* **Service Configuration**: Edit service configurations
|
||||
* **Script Development**: Create automation scripts
|
||||
* **Documentation**: Maintain project documentation
|
||||
* **Troubleshooting**: Debug homelab issues
|
||||
|
||||
**Development Work:**
|
||||
* **Code Development**: Full-stack development
|
||||
* **API Development**: Build and test APIs
|
||||
* **Testing**: Unit and integration testing
|
||||
* **Debugging**: Application debugging
|
||||
|
||||
**Remote Development:**
|
||||
* **Mobile Development**: Code on mobile devices
|
||||
* **Travel Access**: Access code while traveling
|
||||
* **Collaborative Work**: Share development environment
|
||||
* **Backup Access**: Access code from any location
|
||||
|
||||
**Education & Learning:**
|
||||
* **Tutorial Following**: Follow coding tutorials
|
||||
* **Experimentation**: Test new technologies
|
||||
* **Documentation**: Create learning materials
|
||||
* **Project Development**: Build personal projects
|
||||
|
||||
===== Advanced Configuration =====
|
||||
|
||||
**Custom Extensions:**
|
||||
```json
|
||||
// Install custom extensions
|
||||
{
|
||||
"extensions": {
|
||||
"recommendations": [
|
||||
"ms-python.python",
|
||||
"GitHub.copilot"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Remote Development:**
|
||||
```json
|
||||
// SSH configuration for remote development
|
||||
{
|
||||
"remote.SSH.configFile": "~/.ssh/config",
|
||||
"remote.SSH.remotePlatform": {
|
||||
"homelab-server": "linux"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Task Automation:**
|
||||
```json
|
||||
// tasks.json for automation
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "Deploy Stack",
|
||||
"type": "shell",
|
||||
"command": "docker-compose",
|
||||
"args": ["up", "-d"],
|
||||
"group": "build"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Code Server provides a full-featured development environment in your browser, perfectly integrated with your homelab workflow and AI development tools.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:docker-proxy|Docker Proxy]] or explore [[getting_started:access|Access Guide]].
|
||||
@@ -0,0 +1,384 @@
|
||||
====== Docker Proxy ======
|
||||
|
||||
Docker Proxy provides secure remote access to the Docker daemon socket, enabling safe Docker API access from external tools and services. It acts as a secure proxy between Docker clients and the Docker daemon.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Secure Docker socket proxy
|
||||
**Deployment:** Infrastructure stack
|
||||
**Access Method:** TCP socket (no web UI)
|
||||
**Security:** TLS encryption and authentication
|
||||
**Integration:** External Docker tool access
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**Secure Access:**
|
||||
* **TLS Encryption**: Encrypted Docker API communication
|
||||
* **Authentication**: Client certificate authentication
|
||||
* **Access Control**: Granular permission control
|
||||
* **Audit Logging**: Comprehensive access logging
|
||||
|
||||
**Proxy Features:**
|
||||
* **Socket Proxy**: TCP proxy for Docker socket
|
||||
* **API Compatibility**: Full Docker API support
|
||||
* **Connection Pooling**: Efficient connection management
|
||||
* **Load Balancing**: Distribute requests across instances
|
||||
|
||||
**Monitoring:**
|
||||
* **Request Logging**: Log all Docker API requests
|
||||
* **Performance Metrics**: Monitor proxy performance
|
||||
* **Health Checks**: Proxy health monitoring
|
||||
* **Error Tracking**: Track and report errors
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
docker-proxy:
|
||||
image: tecnativa/docker-socket-proxy:latest
|
||||
container_name: docker-proxy
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- CONTAINERS=1
|
||||
- SERVICES=1
|
||||
- TASKS=1
|
||||
- NODES=0
|
||||
- SWARM=0
|
||||
- NETWORKS=0
|
||||
- VOLUMES=0
|
||||
- IMAGES=0
|
||||
- EXEC=0
|
||||
- INFO=1
|
||||
- VERSION=1
|
||||
- PING=1
|
||||
- BUILD=0
|
||||
- COMMIT=0
|
||||
- CONFIGS=0
|
||||
- DISTRIBUTION=0
|
||||
- EVENTS=1
|
||||
- GRPC=0
|
||||
- LOGS=1
|
||||
- PLUGINS=0
|
||||
- POST=0
|
||||
- SECRETS=0
|
||||
- SESSION=0
|
||||
- SYSTEM=0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
ports:
|
||||
- 2376:2376
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.2'
|
||||
memory: 64M
|
||||
reservations:
|
||||
cpus: '0.01'
|
||||
memory: 16M
|
||||
```
|
||||
|
||||
**Permission Levels:**
|
||||
```bash
|
||||
# Read-only access (recommended)
|
||||
CONTAINERS=1 # List containers
|
||||
SERVICES=1 # List services
|
||||
TASKS=1 # List tasks
|
||||
INFO=1 # System info
|
||||
VERSION=1 # Version info
|
||||
PING=1 # Health checks
|
||||
EVENTS=1 # Docker events
|
||||
LOGS=1 # Container logs
|
||||
|
||||
# Write access (use carefully)
|
||||
IMAGES=1 # Pull/push images
|
||||
NETWORKS=1 # Network management
|
||||
VOLUMES=1 # Volume management
|
||||
EXEC=1 # Execute commands
|
||||
BUILD=1 # Build images
|
||||
POST=1 # Create resources
|
||||
```
|
||||
|
||||
===== Security Configuration =====
|
||||
|
||||
**TLS Setup:**
|
||||
```yaml
|
||||
# Generate certificates
|
||||
openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
|
||||
-subj "/C=US/ST=State/L=City/O=Organization/CN=docker-proxy" \
|
||||
-keyout docker-proxy.key -out docker-proxy.crt
|
||||
|
||||
# Mount certificates
|
||||
volumes:
|
||||
- ./certs/docker-proxy.crt:/certs/server.crt:ro
|
||||
- ./certs/docker-proxy.key:/certs/server.key:ro
|
||||
```
|
||||
|
||||
**Client Authentication:**
|
||||
```bash
|
||||
# Client certificate authentication
|
||||
environment:
|
||||
- AUTH=1
|
||||
- CERTS_PATH=/certs
|
||||
|
||||
volumes:
|
||||
- ./certs:/certs:ro
|
||||
```
|
||||
|
||||
**Access Control:**
|
||||
* **IP Whitelisting**: Restrict access by IP address
|
||||
* **Certificate Validation**: Require valid client certificates
|
||||
* **Permission Levels**: Granular API permission control
|
||||
* **Rate Limiting**: Prevent abuse and DoS attacks
|
||||
|
||||
===== Usage Examples =====
|
||||
|
||||
**Docker Client Connection:**
|
||||
```bash
|
||||
# Connect using TCP
|
||||
export DOCKER_HOST=tcp://localhost:2376
|
||||
docker ps
|
||||
|
||||
# With TLS
|
||||
export DOCKER_HOST=tcp://localhost:2376
|
||||
export DOCKER_TLS_VERIFY=1
|
||||
export DOCKER_CERT_PATH=/path/to/certs
|
||||
docker ps
|
||||
```
|
||||
|
||||
**External Tool Integration:**
|
||||
```python
|
||||
# Python Docker client
|
||||
import docker
|
||||
|
||||
client = docker.DockerClient(base_url='tcp://localhost:2376')
|
||||
containers = client.containers.list()
|
||||
```
|
||||
|
||||
**CI/CD Integration:**
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Connect to Docker
|
||||
run: |
|
||||
echo "DOCKER_HOST=tcp://docker-proxy:2376" >> $GITHUB_ENV
|
||||
docker ps
|
||||
```
|
||||
|
||||
**Monitoring Integration:**
|
||||
```bash
|
||||
# Prometheus metrics
|
||||
curl http://localhost:2376/metrics
|
||||
|
||||
# Health check
|
||||
curl http://localhost:2376/_ping
|
||||
```
|
||||
|
||||
===== Monitoring & Troubleshooting =====
|
||||
|
||||
**Proxy Logs:**
|
||||
```bash
|
||||
# View proxy logs
|
||||
docker logs docker-proxy
|
||||
|
||||
# Follow logs in real-time
|
||||
docker logs -f docker-proxy
|
||||
```
|
||||
|
||||
**Connection Testing:**
|
||||
```bash
|
||||
# Test basic connectivity
|
||||
telnet localhost 2376
|
||||
|
||||
# Test Docker API
|
||||
curl http://localhost:2376/_ping
|
||||
|
||||
# Test with Docker client
|
||||
DOCKER_HOST=tcp://localhost:2376 docker version
|
||||
```
|
||||
|
||||
**Permission Issues:**
|
||||
* **Access Denied**: Check permission environment variables
|
||||
* **Certificate Errors**: Verify TLS certificate configuration
|
||||
* **Network Issues**: Check firewall and network connectivity
|
||||
* **Socket Access**: Verify Docker socket permissions
|
||||
|
||||
**Performance Issues:**
|
||||
* **High Latency**: Check network configuration
|
||||
* **Connection Limits**: Monitor concurrent connections
|
||||
* **Resource Usage**: Check CPU/memory usage
|
||||
* **Rate Limiting**: Adjust rate limiting settings
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs docker-proxy`
|
||||
2. **Test connectivity**: Verify TCP connection
|
||||
3. **Validate permissions**: Check environment variables
|
||||
4. **Test Docker client**: Verify Docker API access
|
||||
5. **Restart service**: `docker restart docker-proxy`
|
||||
|
||||
===== Advanced Configuration =====
|
||||
|
||||
**High Availability:**
|
||||
```yaml
|
||||
# Multiple proxy instances
|
||||
services:
|
||||
docker-proxy-1:
|
||||
# Configuration for instance 1
|
||||
|
||||
docker-proxy-2:
|
||||
# Configuration for instance 2
|
||||
|
||||
load-balancer:
|
||||
# Load balancer configuration
|
||||
```
|
||||
|
||||
**Custom TLS Configuration:**
|
||||
```yaml
|
||||
environment:
|
||||
- TLS_CERT=/certs/custom.crt
|
||||
- TLS_KEY=/certs/custom.key
|
||||
- TLS_CA=/certs/ca.crt
|
||||
```
|
||||
|
||||
**Rate Limiting:**
|
||||
```yaml
|
||||
environment:
|
||||
- RATE_LIMIT=100 # Requests per minute
|
||||
- BURST_LIMIT=20 # Burst allowance
|
||||
```
|
||||
|
||||
**Audit Logging:**
|
||||
```yaml
|
||||
environment:
|
||||
- LOG_LEVEL=debug
|
||||
- AUDIT_LOG=/logs/audit.log
|
||||
|
||||
volumes:
|
||||
- ./logs:/logs
|
||||
```
|
||||
|
||||
===== Security Best Practices =====
|
||||
|
||||
**Access Control:**
|
||||
* **Principle of Least Privilege**: Grant minimal required permissions
|
||||
* **Network Segmentation**: Isolate proxy network access
|
||||
* **Certificate Management**: Regular certificate rotation
|
||||
* **Monitoring**: Continuous access monitoring
|
||||
|
||||
**TLS Security:**
|
||||
* **Strong Ciphers**: Use modern TLS cipher suites
|
||||
* **Certificate Validation**: Enable client certificate validation
|
||||
* **Perfect Forward Secrecy**: Enable PFS cipher suites
|
||||
* **Regular Updates**: Keep TLS libraries updated
|
||||
|
||||
**Operational Security:**
|
||||
* **Log Analysis**: Regular security log review
|
||||
* **Intrusion Detection**: Monitor for suspicious activity
|
||||
* **Backup Security**: Secure configuration backups
|
||||
* **Incident Response**: Have security incident procedures
|
||||
|
||||
===== Integration Patterns =====
|
||||
|
||||
**CI/CD Pipelines:**
|
||||
```yaml
|
||||
# Jenkins pipeline
|
||||
pipeline {
|
||||
agent any
|
||||
stages {
|
||||
stage('Build') {
|
||||
steps {
|
||||
script {
|
||||
docker.withServer('tcp://docker-proxy:2376') {
|
||||
docker.build('my-app')
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Monitoring Integration:**
|
||||
```yaml
|
||||
# Prometheus configuration
|
||||
scrape_configs:
|
||||
- job_name: 'docker-proxy'
|
||||
static_configs:
|
||||
- targets: ['docker-proxy:2376']
|
||||
metrics_path: '/metrics'
|
||||
```
|
||||
|
||||
**Backup Integration:**
|
||||
```bash
|
||||
# Backup Docker configurations
|
||||
DOCKER_HOST=tcp://localhost:2376 docker system info > system-info.json
|
||||
DOCKER_HOST=tcp://localhost:2376 docker config ls > configs.json
|
||||
```
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**Resource Management:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.2'
|
||||
memory: 64M
|
||||
reservations:
|
||||
cpus: '0.01'
|
||||
memory: 16M
|
||||
```
|
||||
|
||||
**Connection Optimization:**
|
||||
* **Connection Pooling**: Reuse connections efficiently
|
||||
* **Timeout Configuration**: Appropriate request timeouts
|
||||
* **Concurrent Limits**: Control simultaneous connections
|
||||
* **Caching**: Cache frequently accessed data
|
||||
|
||||
===== Use Cases =====
|
||||
|
||||
**Development Environments:**
|
||||
* **Remote Docker Access**: Access Docker from development machines
|
||||
* **CI/CD Integration**: Integrate with build pipelines
|
||||
* **Testing Environments**: Isolated testing environments
|
||||
* **Container Management**: Manage containers from external tools
|
||||
|
||||
**Production Management:**
|
||||
* **Monitoring Tools**: Connect monitoring tools to Docker API
|
||||
* **Management Platforms**: Integrate with Docker management platforms
|
||||
* **Backup Solutions**: Connect backup tools to Docker
|
||||
* **Security Scanning**: Integrate security scanning tools
|
||||
|
||||
**Homelab Management:**
|
||||
* **Portainer Integration**: Connect Portainer to Docker API
|
||||
* **External Tools**: Use Docker CLI from external machines
|
||||
* **Automation Scripts**: Run Docker automation scripts
|
||||
* **Monitoring Integration**: Connect monitoring stacks
|
||||
|
||||
**Enterprise Integration:**
|
||||
* **Centralized Management**: Connect to enterprise Docker platforms
|
||||
* **Compliance Monitoring**: Meet compliance requirements
|
||||
* **Audit Trails**: Maintain Docker operation audit logs
|
||||
* **Security Integration**: Integrate with security platforms
|
||||
|
||||
===== Backup & Recovery =====
|
||||
|
||||
**Configuration Backup:**
|
||||
```bash
|
||||
# Backup proxy configuration
|
||||
docker run --rm \
|
||||
-v docker-proxy-config:/config \
|
||||
-v $(pwd)/backup:/backup \
|
||||
busybox tar czf /backup/docker-proxy-config.tar.gz /config
|
||||
```
|
||||
|
||||
**Certificate Management:**
|
||||
* **Certificate Backup**: Regular certificate backups
|
||||
* **Key Rotation**: Periodic key rotation procedures
|
||||
* **Certificate Monitoring**: Monitor certificate expiration
|
||||
* **Renewal Process**: Automated certificate renewal
|
||||
|
||||
Docker Proxy provides secure, controlled access to the Docker daemon, enabling safe integration with external tools and services while maintaining security and audit capabilities.
|
||||
|
||||
**Next:** Explore [[services:media:start|Media Services]] or return to [[services:start|Services Overview]].
|
||||
@@ -0,0 +1,313 @@
|
||||
====== Dockge ======
|
||||
|
||||
Dockge is the primary web-based interface for managing Docker stacks in your homelab. It provides a clean, intuitive way to deploy, monitor, and manage all your services through a web UI, making it the central hub for homelab management.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Docker stack management interface
|
||||
**URL:** https://dockge.yourdomain.duckdns.org
|
||||
**Authentication:** Authelia SSO protected
|
||||
**Deployment:** Infrastructure stack
|
||||
**Interface:** Modern web UI with drag-and-drop
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**Stack Management:**
|
||||
* **Visual Interface**: Web-based stack management
|
||||
* **Compose File Editing**: Direct YAML editing
|
||||
* **One-Click Deploy**: Deploy stacks with single click
|
||||
* **Real-time Monitoring**: Live container status
|
||||
|
||||
**Container Operations:**
|
||||
* **Start/Stop/Restart**: Individual container control
|
||||
* **Log Viewing**: Integrated log viewer
|
||||
* **Resource Monitoring**: CPU/memory usage
|
||||
* **Network Inspection**: Container networking info
|
||||
|
||||
**File Management:**
|
||||
* **Directory Browser**: Navigate stack directories
|
||||
* **File Editor**: Edit configuration files
|
||||
* **Upload/Download**: File transfer capabilities
|
||||
* **Backup Integration**: Stack backup/restore
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
dockge:
|
||||
image: louislam/dockge:1
|
||||
container_name: dockge
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- DOCKGE_STACKS_DIR=/opt/stacks
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- /opt/stacks:/opt/stacks
|
||||
- ./dockge/data:/app/data
|
||||
ports:
|
||||
- 5001:5001
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
reservations:
|
||||
cpus: '0.1'
|
||||
memory: 64M
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.dockge.rule=Host(`dockge.${DOMAIN}`)"
|
||||
- "traefik.http.routers.dockge.entrypoints=websecure"
|
||||
- "traefik.http.routers.dockge.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.dockge.middlewares=authelia@docker"
|
||||
- "traefik.http.services.dockge.loadbalancer.server.port=5001"
|
||||
- "x-dockge.url=https://dockge.${DOMAIN}"
|
||||
```
|
||||
|
||||
**Directory Structure:**
|
||||
```
|
||||
/opt/stacks/
|
||||
├── core/ # Core infrastructure
|
||||
├── infrastructure/ # Management tools
|
||||
├── media/ # Media services
|
||||
├── media-management/ # Download automation
|
||||
├── dashboards/ # Dashboard services
|
||||
├── homeassistant/ # Home automation
|
||||
├── productivity/ # Office tools
|
||||
├── monitoring/ # Observability
|
||||
├── utilities/ # Backup/utilities
|
||||
└── development/ # Dev tools
|
||||
```
|
||||
|
||||
===== Getting Started =====
|
||||
|
||||
**Initial Access:**
|
||||
1. **Deploy Infrastructure Stack**: Run deploy script or manual deployment
|
||||
2. **Access URL**: Visit https://dockge.yourdomain.duckdns.org
|
||||
3. **Authelia Login**: Authenticate with your credentials
|
||||
4. **First Stack**: Create your first stack
|
||||
|
||||
**Interface Overview:**
|
||||
* **Left Sidebar**: Stack categories and navigation
|
||||
* **Main Panel**: Stack list with status indicators
|
||||
* **Top Bar**: Search, settings, and actions
|
||||
* **Stack Cards**: Individual stack management
|
||||
|
||||
===== Stack Operations =====
|
||||
|
||||
**Creating a New Stack:**
|
||||
1. **Click "Compose"**: Open compose file editor
|
||||
2. **Enter Stack Name**: Choose directory name
|
||||
3. **Paste YAML**: Copy docker-compose.yml content
|
||||
4. **Deploy**: Click deploy button
|
||||
5. **Monitor**: Watch deployment progress
|
||||
|
||||
**Managing Existing Stacks:**
|
||||
* **Start/Stop**: Control stack lifecycle
|
||||
* **Update**: Pull new images and restart
|
||||
* **Edit**: Modify compose files
|
||||
* **Logs**: View container logs
|
||||
* **Terminal**: Access container shells
|
||||
|
||||
**Stack Status Indicators:**
|
||||
* **🟢 Running**: All containers healthy
|
||||
* **🟡 Partial**: Some containers issues
|
||||
* **🔴 Stopped**: Stack not running
|
||||
* **🔵 Updating**: Stack being updated
|
||||
|
||||
===== File Management =====
|
||||
|
||||
**Directory Navigation:**
|
||||
* **Browse Stacks**: Navigate /opt/stacks directory
|
||||
* **File Editor**: Edit YAML, config files
|
||||
* **Upload Files**: Drag-and-drop file uploads
|
||||
* **Download**: Download files from containers
|
||||
|
||||
**Configuration Editing:**
|
||||
* **Syntax Highlighting**: YAML, JSON, text files
|
||||
* **Save Changes**: Auto-save or manual save
|
||||
* **Version Control**: Track file changes
|
||||
* **Backup**: Automatic file backups
|
||||
|
||||
===== Container Management =====
|
||||
|
||||
**Individual Container Control:**
|
||||
* **Start/Stop/Restart**: Container lifecycle
|
||||
* **Logs**: Real-time log streaming
|
||||
* **Exec**: Run commands in containers
|
||||
* **Inspect**: View container details
|
||||
|
||||
**Resource Monitoring:**
|
||||
* **CPU Usage**: Real-time CPU monitoring
|
||||
* **Memory Usage**: RAM consumption tracking
|
||||
* **Network I/O**: Traffic monitoring
|
||||
* **Disk Usage**: Storage utilization
|
||||
|
||||
===== Advanced Features =====
|
||||
|
||||
**Environment Variables:**
|
||||
```yaml
|
||||
# Global environment file
|
||||
# /opt/stacks/.env
|
||||
DOMAIN=yourdomain.duckdns.org
|
||||
PUID=1000
|
||||
PGID=1000
|
||||
TZ=America/New_York
|
||||
```
|
||||
|
||||
**Stack Dependencies:**
|
||||
* **Service Dependencies**: depends_on configuration
|
||||
* **Network Dependencies**: Shared networks
|
||||
* **Volume Dependencies**: Shared storage
|
||||
* **Health Checks**: Service readiness
|
||||
|
||||
**Backup & Restore:**
|
||||
* **Stack Export**: Download compose files
|
||||
* **Configuration Backup**: Environment files
|
||||
* **Volume Backup**: Data persistence
|
||||
* **Full Restore**: Complete stack recovery
|
||||
|
||||
===== Integration with AI Assistant =====
|
||||
|
||||
**AI-Powered Management:**
|
||||
* **Service Creation**: AI generates compose files
|
||||
* **Configuration Help**: AI assists with setup
|
||||
* **Troubleshooting**: AI analyzes logs and issues
|
||||
* **Documentation**: AI maintains service docs
|
||||
|
||||
**Workflow Integration:**
|
||||
* **VS Code**: Direct file editing
|
||||
* **GitHub Copilot**: AI assistance for configurations
|
||||
* **Automated Deployments**: Script-based stack management
|
||||
* **Monitoring Integration**: Health check automation
|
||||
|
||||
===== Security Considerations =====
|
||||
|
||||
**Access Control:**
|
||||
* **Authelia Protection**: SSO authentication required
|
||||
* **User Permissions**: Container user mapping (PUID/PGID)
|
||||
* **Docker Socket**: Read-only access to Docker API
|
||||
* **Network Isolation**: Container network segmentation
|
||||
|
||||
**Data Protection:**
|
||||
* **Encrypted Connections**: HTTPS via Traefik
|
||||
* **Secure Storage**: Sensitive data in environment files
|
||||
* **Backup Security**: Encrypted backup storage
|
||||
* **Access Logging**: User action auditing
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**Resource Management:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
reservations:
|
||||
cpus: '0.1'
|
||||
memory: 64M
|
||||
```
|
||||
|
||||
**Container Optimization:**
|
||||
* **Image Updates**: Regular security updates
|
||||
* **Log Rotation**: Prevent disk space issues
|
||||
* **Cache Management**: Docker layer caching
|
||||
* **Network Efficiency**: Optimized container networking
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**Common Issues:**
|
||||
|
||||
**Cannot Connect to Docker:**
|
||||
```bash
|
||||
# Check Docker socket permissions
|
||||
ls -la /var/run/docker.sock
|
||||
|
||||
# Verify Docker is running
|
||||
docker ps
|
||||
|
||||
# Check container logs
|
||||
docker logs dockge
|
||||
```
|
||||
|
||||
**Stack Deployment Fails:**
|
||||
* **YAML Syntax**: Validate compose file syntax
|
||||
* **Port Conflicts**: Check for port usage conflicts
|
||||
* **Network Issues**: Verify network connectivity
|
||||
* **Permission Errors**: Check file/directory permissions
|
||||
|
||||
**Web Interface Issues:**
|
||||
* **Traefik Routing**: Verify Traefik configuration
|
||||
* **Authelia Access**: Check SSO authentication
|
||||
* **SSL Certificates**: Validate certificate status
|
||||
* **Browser Cache**: Clear browser cache
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs dockge`
|
||||
2. **Validate configuration**: Test compose file syntax
|
||||
3. **Network connectivity**: Verify Docker network access
|
||||
4. **Restart service**: `docker restart dockge`
|
||||
5. **Check dependencies**: Ensure required services running
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**Stack Organization:**
|
||||
* **Logical Grouping**: Group related services
|
||||
* **Naming Convention**: Consistent naming patterns
|
||||
* **Documentation**: Comment complex configurations
|
||||
* **Version Control**: Track configuration changes
|
||||
|
||||
**Maintenance:**
|
||||
* **Regular Updates**: Keep images updated
|
||||
* **Backup Routine**: Regular configuration backups
|
||||
* **Log Monitoring**: Review logs for issues
|
||||
* **Performance Tuning**: Optimize resource usage
|
||||
|
||||
**Security:**
|
||||
* **Access Control**: Limit user permissions
|
||||
* **Network Security**: Use secure networks
|
||||
* **Data Encryption**: Encrypt sensitive data
|
||||
* **Audit Logging**: Monitor access and changes
|
||||
|
||||
**Workflow:**
|
||||
* **Testing**: Test changes in development first
|
||||
* **Documentation**: Document custom configurations
|
||||
* **Automation**: Use scripts for repetitive tasks
|
||||
* **Monitoring**: Monitor stack health continuously
|
||||
|
||||
===== Integration Examples =====
|
||||
|
||||
**Adding a New Service:**
|
||||
```yaml
|
||||
# 1. Create new stack directory
|
||||
# 2. Add docker-compose.yml
|
||||
# 3. Configure environment variables
|
||||
# 4. Deploy via Dockge UI
|
||||
# 5. Test service functionality
|
||||
```
|
||||
|
||||
**Service Updates:**
|
||||
```yaml
|
||||
# 1. Edit compose file in Dockge
|
||||
# 2. Update image version
|
||||
# 3. Deploy changes
|
||||
# 4. Monitor startup logs
|
||||
# 5. Verify functionality
|
||||
```
|
||||
|
||||
**Backup Strategy:**
|
||||
```yaml
|
||||
# 1. Export stack configurations
|
||||
# 2. Backup environment files
|
||||
# 3. Backup persistent volumes
|
||||
# 4. Store backups securely
|
||||
# 5. Test restore procedures
|
||||
```
|
||||
|
||||
Dockge serves as the central nervous system of your homelab, providing intuitive management of all your Docker services through a modern web interface.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:pihole|Pi-hole]] or explore [[getting_started:deployment|Deployment Guide]].
|
||||
@@ -0,0 +1,343 @@
|
||||
====== Dozzle ======
|
||||
|
||||
Dozzle is a real-time log viewer for Docker containers, providing a web-based interface to monitor and search through container logs. It offers live log streaming, filtering capabilities, and multi-container log management.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Real-time Docker log viewer
|
||||
**URL:** https://dozzle.yourdomain.duckdns.org
|
||||
**Authentication:** Authelia SSO protected
|
||||
**Deployment:** Infrastructure stack
|
||||
**Interface:** Modern web UI with live updates
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**Log Viewing:**
|
||||
* **Real-time Streaming**: Live log updates
|
||||
* **Multi-container**: View multiple containers simultaneously
|
||||
* **Search & Filter**: Advanced log filtering
|
||||
* **Color Coding**: Syntax highlighting for different log levels
|
||||
|
||||
**Container Management:**
|
||||
* **Container List**: All running containers
|
||||
* **Status Indicators**: Container health status
|
||||
* **Quick Actions**: Start/stop/restart containers
|
||||
* **Resource Monitoring**: Basic CPU/memory stats
|
||||
|
||||
**Search & Filtering:**
|
||||
* **Text Search**: Search within logs
|
||||
* **Regex Support**: Regular expression filtering
|
||||
* **Date Filtering**: Time-based log filtering
|
||||
* **Container Filtering**: Filter by specific containers
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
dozzle:
|
||||
image: amir20/dozzle:latest
|
||||
container_name: dozzle
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- DOZZLE_USERNAME=${DOZZLE_USERNAME:-admin}
|
||||
- DOZZLE_PASSWORD=${DOZZLE_PASSWORD}
|
||||
- DOZZLE_LEVEL=info
|
||||
- DOZZLE_TAILSIZE=100
|
||||
- DOZZLE_FILTER_CONTAINERS=${DOZZLE_FILTER_CONTAINERS}
|
||||
- DOZZLE_NO_ANALYTICS=true
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.3'
|
||||
memory: 128M
|
||||
reservations:
|
||||
cpus: '0.05'
|
||||
memory: 32M
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.dozzle.rule=Host(`dozzle.${DOMAIN}`)"
|
||||
- "traefik.http.routers.dozzle.entrypoints=websecure"
|
||||
- "traefik.http.routers.dozzle.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.dozzle.middlewares=authelia@docker"
|
||||
- "traefik.http.services.dozzle.loadbalancer.server.port=8080"
|
||||
- "x-dockge.url=https://dozzle.${DOMAIN}"
|
||||
```
|
||||
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
# Authentication (optional, Authelia handles SSO)
|
||||
DOZZLE_USERNAME=admin
|
||||
DOZZLE_PASSWORD=your-secure-password
|
||||
|
||||
# Logging configuration
|
||||
DOZZLE_LEVEL=info # debug, info, warn, error
|
||||
DOZZLE_TAILSIZE=100 # Lines to show initially
|
||||
|
||||
# Container filtering (optional)
|
||||
DOZZLE_FILTER_CONTAINERS=container1,container2
|
||||
|
||||
# Privacy
|
||||
DOZZLE_NO_ANALYTICS=true
|
||||
```
|
||||
|
||||
===== Interface Overview =====
|
||||
|
||||
**Main Dashboard:**
|
||||
* **Container List**: Left sidebar with all containers
|
||||
* **Log Viewer**: Main panel showing selected logs
|
||||
* **Search Bar**: Top search and filter controls
|
||||
* **Status Bar**: Connection and filter status
|
||||
|
||||
**Container Selection:**
|
||||
* **Single Container**: Click to view individual logs
|
||||
* **Multiple Containers**: Hold Ctrl/Cmd to select multiple
|
||||
* **All Containers**: View logs from all containers
|
||||
* **Container Groups**: Filter by stack or service type
|
||||
|
||||
**Log Display:**
|
||||
* **Live Updates**: Real-time log streaming
|
||||
* **Color Coding**: Different colors for log levels
|
||||
* **Timestamps**: Show log timestamps
|
||||
* **Line Numbers**: Reference specific log lines
|
||||
|
||||
===== Search & Filtering =====
|
||||
|
||||
**Text Search:**
|
||||
```bash
|
||||
# Basic search
|
||||
error warning
|
||||
|
||||
# Case-sensitive search
|
||||
/Error|Warning/
|
||||
|
||||
# Complex patterns
|
||||
"connection refused" OR "timeout"
|
||||
```
|
||||
|
||||
**Advanced Filtering:**
|
||||
* **Container Name**: Filter by specific containers
|
||||
* **Log Level**: Filter by severity (ERROR, WARN, INFO, DEBUG)
|
||||
* **Time Range**: Show logs from specific time periods
|
||||
* **Regex Patterns**: Use regular expressions for complex matching
|
||||
|
||||
**Saved Filters:**
|
||||
* **Custom Filters**: Save frequently used search patterns
|
||||
* **Filter Presets**: Pre-configured filter combinations
|
||||
* **Quick Filters**: One-click common filters (errors only, etc.)
|
||||
|
||||
===== Container Management =====
|
||||
|
||||
**Quick Actions:**
|
||||
* **Start/Stop**: Control container lifecycle
|
||||
* **Restart**: Restart individual containers
|
||||
* **Logs**: Jump to detailed logs
|
||||
* **Exec**: Open terminal in container
|
||||
|
||||
**Container Information:**
|
||||
* **Status**: Running, stopped, paused
|
||||
* **Uptime**: How long container has been running
|
||||
* **Image**: Container image and version
|
||||
* **Ports**: Exposed ports and mappings
|
||||
|
||||
**Resource Monitoring:**
|
||||
* **CPU Usage**: Real-time CPU percentage
|
||||
* **Memory Usage**: RAM consumption
|
||||
* **Network I/O**: Data transfer rates
|
||||
* **Disk I/O**: Storage read/write operations
|
||||
|
||||
===== Advanced Features =====
|
||||
|
||||
**Log Analysis:**
|
||||
* **Pattern Recognition**: Identify common error patterns
|
||||
* **Anomaly Detection**: Flag unusual log patterns
|
||||
* **Trend Analysis**: Track log volume over time
|
||||
* **Alert Integration**: Send alerts for specific log patterns
|
||||
|
||||
**Export & Sharing:**
|
||||
* **Log Export**: Download logs as text files
|
||||
* **Share Links**: Generate shareable log links
|
||||
* **API Access**: Programmatic log access
|
||||
* **Integration**: Connect with other monitoring tools
|
||||
|
||||
**Customization:**
|
||||
* **Themes**: Light/dark mode switching
|
||||
* **Layout**: Customizable interface layout
|
||||
* **Shortcuts**: Keyboard shortcuts for common actions
|
||||
* **Notifications**: Browser notifications for events
|
||||
|
||||
===== Security Considerations =====
|
||||
|
||||
**Access Control:**
|
||||
* **Authelia Protection**: SSO authentication required
|
||||
* **User Permissions**: Container access restrictions
|
||||
* **Log Privacy**: Sensitive data in logs
|
||||
* **Network Security**: Secure Docker socket access
|
||||
|
||||
**Data Protection:**
|
||||
* **Log Encryption**: Secure log transmission
|
||||
* **Access Logging**: Audit log access
|
||||
* **Data Retention**: Log retention policies
|
||||
* **Privacy Controls**: Filter sensitive information
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**Resource Management:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.3'
|
||||
memory: 128M
|
||||
reservations:
|
||||
cpus: '0.05'
|
||||
memory: 32M
|
||||
```
|
||||
|
||||
**Log Optimization:**
|
||||
* **Tail Size**: Limit initial log display
|
||||
* **Buffer Management**: Efficient log buffering
|
||||
* **Compression**: Log compression for storage
|
||||
* **Cleanup**: Automatic old log cleanup
|
||||
|
||||
**Container Filtering:**
|
||||
```yaml
|
||||
# Limit visible containers
|
||||
environment:
|
||||
- DOZZLE_FILTER_CONTAINERS=traefik,authelia,dockge
|
||||
```
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**Connection Issues:**
|
||||
```bash
|
||||
# Check Docker socket access
|
||||
ls -la /var/run/docker.sock
|
||||
|
||||
# Verify Docker is running
|
||||
docker ps
|
||||
|
||||
# Check container logs
|
||||
docker logs dozzle
|
||||
```
|
||||
|
||||
**Log Display Problems:**
|
||||
* **No Logs Showing**: Check container permissions
|
||||
* **Logs Not Updating**: Verify real-time connection
|
||||
* **Search Not Working**: Check search syntax
|
||||
* **Performance Issues**: Reduce number of containers
|
||||
|
||||
**Authentication Issues:**
|
||||
* **Login Problems**: Verify credentials
|
||||
* **Authelia Integration**: Check SSO configuration
|
||||
* **Session Timeout**: Adjust session settings
|
||||
* **Permission Denied**: Check user permissions
|
||||
|
||||
**Web Interface Issues:**
|
||||
* **Page Not Loading**: Check Traefik routing
|
||||
* **SSL Errors**: Verify certificate status
|
||||
* **JavaScript Errors**: Clear browser cache
|
||||
* **Mobile Issues**: Check responsive design
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs dozzle`
|
||||
2. **Test connectivity**: Verify Docker socket access
|
||||
3. **Validate configuration**: Check environment variables
|
||||
4. **Browser testing**: Test in different browsers
|
||||
5. **Restart service**: `docker restart dozzle`
|
||||
|
||||
===== Integration with Monitoring =====
|
||||
|
||||
**Prometheus Integration:**
|
||||
```yaml
|
||||
# Expose metrics for monitoring
|
||||
environment:
|
||||
- DOZZLE_ENABLE_METRICS=true
|
||||
- DOZZLE_METRICS_PORT=8081
|
||||
```
|
||||
|
||||
**Grafana Dashboards:**
|
||||
* **Log Volume**: Track log generation rates
|
||||
* **Error Rates**: Monitor error log frequency
|
||||
* **Container Health**: Track container status
|
||||
* **Performance Metrics**: CPU/memory usage trends
|
||||
|
||||
**Alert Integration:**
|
||||
* **Error Alerts**: Alert on specific error patterns
|
||||
* **Container Alerts**: Notify on container failures
|
||||
* **Performance Alerts**: Alert on resource issues
|
||||
* **Log Volume Alerts**: Alert on unusual log activity
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**Log Management:**
|
||||
* **Regular Monitoring**: Daily log review routine
|
||||
* **Search Optimization**: Use efficient search patterns
|
||||
* **Filter Usage**: Create useful filter presets
|
||||
* **Export Strategy**: Regular log exports for analysis
|
||||
|
||||
**Container Organization:**
|
||||
* **Naming Convention**: Consistent container naming
|
||||
* **Grouping**: Logical container grouping
|
||||
* **Tagging**: Use labels for better organization
|
||||
* **Documentation**: Document container purposes
|
||||
|
||||
**Security:**
|
||||
* **Access Control**: Limit log access to authorized users
|
||||
* **Data Protection**: Be aware of sensitive data in logs
|
||||
* **Network Security**: Secure Docker socket access
|
||||
* **Audit Logging**: Track log access and searches
|
||||
|
||||
**Performance:**
|
||||
* **Resource Limits**: Appropriate CPU/memory limits
|
||||
* **Container Filtering**: Limit visible containers
|
||||
* **Log Tail Size**: Optimize initial log display
|
||||
* **Caching**: Use browser caching for better performance
|
||||
|
||||
===== Use Cases =====
|
||||
|
||||
**Development & Debugging:**
|
||||
* **Application Logs**: Monitor application behavior
|
||||
* **Error Tracking**: Quickly identify and fix errors
|
||||
* **Performance Monitoring**: Track application performance
|
||||
* **Integration Testing**: Verify service interactions
|
||||
|
||||
**Production Monitoring:**
|
||||
* **Service Health**: Monitor service availability
|
||||
* **Error Detection**: Catch errors before they escalate
|
||||
* **User Issue Investigation**: Debug user-reported problems
|
||||
* **Security Monitoring**: Watch for suspicious activity
|
||||
|
||||
**Maintenance & Troubleshooting:**
|
||||
* **Update Monitoring**: Watch for issues during updates
|
||||
* **Configuration Changes**: Monitor impact of changes
|
||||
* **Network Issues**: Debug connectivity problems
|
||||
* **Resource Problems**: Identify resource bottlenecks
|
||||
|
||||
===== Keyboard Shortcuts =====
|
||||
|
||||
**Navigation:**
|
||||
* **Ctrl/Cmd + K**: Focus search bar
|
||||
* **Arrow Keys**: Navigate container list
|
||||
* **Enter**: Select container
|
||||
* **Esc**: Clear selection
|
||||
|
||||
**Search:**
|
||||
* **Ctrl/Cmd + F**: Start search
|
||||
* **F3**: Find next occurrence
|
||||
* **Shift + F3**: Find previous occurrence
|
||||
* **Ctrl/Cmd + G**: Go to line
|
||||
|
||||
**Actions:**
|
||||
* **Ctrl/Cmd + R**: Refresh logs
|
||||
* **Ctrl/Cmd + S**: Save current filter
|
||||
* **Ctrl/Cmd + E**: Export logs
|
||||
* **Ctrl/Cmd + T**: Open terminal
|
||||
|
||||
Dozzle provides essential log monitoring capabilities with an intuitive interface, making it easy to track and troubleshoot your containerized services in real-time.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:glances|Glances]] or explore [[architecture:monitoring|Monitoring Architecture]].
|
||||
@@ -0,0 +1,394 @@
|
||||
====== Glances ======
|
||||
|
||||
Glances is a cross-platform system monitoring tool that provides real-time information about your system's performance, resources, and running processes. It offers a web-based interface for monitoring system health and performance metrics.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** System and container monitoring
|
||||
**URL:** https://glances.yourdomain.duckdns.org
|
||||
**Authentication:** Authelia SSO protected
|
||||
**Deployment:** Infrastructure stack
|
||||
**Interface:** Web-based monitoring dashboard
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**System Monitoring:**
|
||||
* **CPU Usage**: Real-time CPU utilization
|
||||
* **Memory Usage**: RAM and swap monitoring
|
||||
* **Disk I/O**: Storage read/write operations
|
||||
* **Network I/O**: Network traffic monitoring
|
||||
|
||||
**Container Monitoring:**
|
||||
* **Docker Stats**: Container resource usage
|
||||
* **Container Health**: Status and health checks
|
||||
* **Process Monitoring**: Running processes
|
||||
* **Service Status**: Application service monitoring
|
||||
|
||||
**Performance Metrics:**
|
||||
* **Load Average**: System load over time
|
||||
* **Temperature**: CPU and system temperatures
|
||||
* **Fan Speed**: Cooling system monitoring
|
||||
* **Power Usage**: System power consumption
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
glances:
|
||||
image: nicolargo/glances:latest
|
||||
container_name: glances
|
||||
restart: unless-stopped
|
||||
pid: host
|
||||
environment:
|
||||
- GLANCES_OPT=-w
|
||||
- GLANCES_OPT_WEBserver=true
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- /etc/os-release:/etc/os-release:ro
|
||||
- /proc:/host/proc:ro
|
||||
- /sys:/host/sys:ro
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.3'
|
||||
memory: 128M
|
||||
reservations:
|
||||
cpus: '0.05'
|
||||
memory: 32M
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.glances.rule=Host(`glances.${DOMAIN}`)"
|
||||
- "traefik.http.routers.glances.entrypoints=websecure"
|
||||
- "traefik.http.routers.glances.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.glances.middlewares=authelia@docker"
|
||||
- "traefik.http.services.glances.loadbalancer.server.port=61208"
|
||||
- "x-dockge.url=https://glances.${DOMAIN}"
|
||||
```
|
||||
|
||||
**Command Line Options:**
|
||||
```bash
|
||||
# Web server mode
|
||||
GLANCES_OPT=-w
|
||||
|
||||
# Additional options
|
||||
GLANCES_OPT=-w --disable-webui-password --enable-process-extended
|
||||
|
||||
# Custom refresh interval
|
||||
GLANCES_OPT=-w --time 5
|
||||
|
||||
# Disable specific plugins
|
||||
GLANCES_OPT=-w --disable cpu --disable mem
|
||||
```
|
||||
|
||||
===== Interface Overview =====
|
||||
|
||||
**Main Dashboard:**
|
||||
* **System Overview**: CPU, memory, disk, network
|
||||
* **Container List**: Docker container statistics
|
||||
* **Process List**: Top running processes
|
||||
* **Alerts Panel**: System alerts and warnings
|
||||
|
||||
**Navigation Tabs:**
|
||||
* **System**: Core system metrics
|
||||
* **Docker**: Container monitoring
|
||||
* **Processes**: Process management
|
||||
* **Alerts**: System alerts and thresholds
|
||||
* **Filesystem**: Disk usage and I/O
|
||||
|
||||
**Real-time Updates:**
|
||||
* **Auto-refresh**: Configurable update intervals
|
||||
* **Live Charts**: Real-time performance graphs
|
||||
* **Color Coding**: Status-based color indicators
|
||||
* **Threshold Alerts**: Configurable warning levels
|
||||
|
||||
===== System Monitoring =====
|
||||
|
||||
**CPU Monitoring:**
|
||||
* **Usage Percentage**: Overall CPU utilization
|
||||
* **Per-Core Usage**: Individual core monitoring
|
||||
* **Load Average**: 1, 5, 15-minute averages
|
||||
* **CPU Frequency**: Current clock speeds
|
||||
|
||||
**Memory Monitoring:**
|
||||
* **RAM Usage**: Physical memory utilization
|
||||
* **Swap Usage**: Swap file/page file usage
|
||||
* **Memory Pressure**: System memory pressure
|
||||
* **Cache Statistics**: Buffer and cache usage
|
||||
|
||||
**Disk Monitoring:**
|
||||
* **Usage Percentage**: Filesystem utilization
|
||||
* **I/O Operations**: Read/write operations per second
|
||||
* **Transfer Rates**: Data transfer speeds
|
||||
* **Disk Health**: S.M.A.R.T. status (if available)
|
||||
|
||||
**Network Monitoring:**
|
||||
* **Interface Statistics**: Per-interface traffic
|
||||
* **Connection Count**: Active network connections
|
||||
* **Bandwidth Usage**: Upload/download rates
|
||||
* **Network Errors**: Packet loss and errors
|
||||
|
||||
===== Container Monitoring =====
|
||||
|
||||
**Docker Integration:**
|
||||
* **Container List**: All running containers
|
||||
* **Resource Usage**: CPU, memory per container
|
||||
* **Network Stats**: Container network traffic
|
||||
* **Health Status**: Container health checks
|
||||
|
||||
**Container Details:**
|
||||
* **Image Information**: Base image and version
|
||||
* **Port Mappings**: Exposed ports
|
||||
* **Volume Mounts**: Attached volumes
|
||||
* **Environment Variables**: Container configuration
|
||||
|
||||
**Performance Metrics:**
|
||||
* **CPU Shares**: CPU allocation and usage
|
||||
* **Memory Limits**: Memory constraints and usage
|
||||
* **Network I/O**: Container network traffic
|
||||
* **Disk I/O**: Container storage operations
|
||||
|
||||
===== Process Monitoring =====
|
||||
|
||||
**Process List:**
|
||||
* **Top Processes**: Most resource-intensive processes
|
||||
* **Process Tree**: Parent-child process relationships
|
||||
* **User Processes**: Per-user process listing
|
||||
* **System Processes**: Kernel and system processes
|
||||
|
||||
**Process Details:**
|
||||
* **CPU Usage**: Per-process CPU consumption
|
||||
* **Memory Usage**: RAM and virtual memory
|
||||
* **I/O Operations**: Disk read/write activity
|
||||
* **Network Activity**: Network connections
|
||||
|
||||
**Process Management:**
|
||||
* **Kill Process**: Terminate problematic processes
|
||||
* **Change Priority**: Adjust process nice levels
|
||||
* **Resource Limits**: Set process resource limits
|
||||
* **Process Groups**: Group related processes
|
||||
|
||||
===== Alert System =====
|
||||
|
||||
**Threshold Configuration:**
|
||||
```yaml
|
||||
# Alert thresholds (environment variables)
|
||||
GLANCES_OPT=-w --alert cpu>80,mem>90,disk>85
|
||||
```
|
||||
|
||||
**Alert Types:**
|
||||
* **CPU Alerts**: High CPU usage warnings
|
||||
* **Memory Alerts**: Memory pressure alerts
|
||||
* **Disk Alerts**: Storage space warnings
|
||||
* **Network Alerts**: Bandwidth threshold alerts
|
||||
|
||||
**Alert Actions:**
|
||||
* **Visual Indicators**: Color-coded alerts
|
||||
* **Sound Alerts**: Audio notifications
|
||||
* **Email Notifications**: SMTP alerts
|
||||
* **Webhook Integration**: External alert systems
|
||||
|
||||
===== Advanced Configuration =====
|
||||
|
||||
**Custom Plugins:**
|
||||
```yaml
|
||||
# Enable additional plugins
|
||||
GLANCES_OPT=-w --enable-plugin sensors --enable-plugin gpu
|
||||
```
|
||||
|
||||
**Export Options:**
|
||||
```yaml
|
||||
# Export to various formats
|
||||
GLANCES_OPT=-w --export csv --export-csv-file /data/stats.csv
|
||||
GLANCES_OPT=-w --export influxdb --export-influxdb-host localhost
|
||||
```
|
||||
|
||||
**Remote Monitoring:**
|
||||
```yaml
|
||||
# Monitor remote systems
|
||||
GLANCES_OPT=-w --client localhost:61209
|
||||
```
|
||||
|
||||
**Configuration File:**
|
||||
```yaml
|
||||
# glances.conf
|
||||
[main]
|
||||
refresh=2
|
||||
history_size=1200
|
||||
|
||||
[cpu]
|
||||
user_careful=50
|
||||
user_warning=70
|
||||
user_critical=90
|
||||
```
|
||||
|
||||
===== Security Considerations =====
|
||||
|
||||
**Access Control:**
|
||||
* **Authelia Protection**: SSO authentication required
|
||||
* **Network Isolation**: Container network restrictions
|
||||
* **Read-only Access**: Limited system access
|
||||
* **Audit Logging**: Monitor access patterns
|
||||
|
||||
**Data Protection:**
|
||||
* **Sensitive Data**: Avoid exposing sensitive information
|
||||
* **Encryption**: Secure data transmission
|
||||
* **Access Logging**: Track monitoring access
|
||||
* **Privacy Controls**: Limit exposed system information
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**Resource Management:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.3'
|
||||
memory: 128M
|
||||
reservations:
|
||||
cpus: '0.05'
|
||||
memory: 32M
|
||||
```
|
||||
|
||||
**Monitoring Optimization:**
|
||||
* **Refresh Rate**: Balance between real-time and performance
|
||||
* **Data Retention**: Configure historical data limits
|
||||
* **Plugin Selection**: Enable only needed monitoring plugins
|
||||
* **Caching**: Use efficient data caching
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**Connection Issues:**
|
||||
```bash
|
||||
# Check web interface
|
||||
curl -k https://glances.yourdomain.duckdns.org
|
||||
|
||||
# Verify port accessibility
|
||||
netstat -tlnp | grep 61208
|
||||
|
||||
# Check container logs
|
||||
docker logs glances
|
||||
```
|
||||
|
||||
**Monitoring Problems:**
|
||||
* **No Data Showing**: Check system permissions
|
||||
* **High Resource Usage**: Adjust refresh rates
|
||||
* **Missing Metrics**: Enable required plugins
|
||||
* **Inaccurate Data**: Verify system compatibility
|
||||
|
||||
**Docker Integration Issues:**
|
||||
* **Socket Access**: Verify Docker socket permissions
|
||||
* **Container Detection**: Check Docker API access
|
||||
* **Permission Errors**: Adjust container privileges
|
||||
* **Network Issues**: Check container networking
|
||||
|
||||
**Performance Issues:**
|
||||
* **High CPU Usage**: Reduce refresh frequency
|
||||
* **Memory Leaks**: Monitor memory consumption
|
||||
* **Disk I/O**: Optimize data storage
|
||||
* **Network Latency**: Check network performance
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs glances`
|
||||
2. **Verify configuration**: Test command line options
|
||||
3. **Test connectivity**: Check web interface access
|
||||
4. **Monitor resources**: Track system resource usage
|
||||
5. **Restart service**: `docker restart glances`
|
||||
|
||||
===== Integration with Monitoring Stack =====
|
||||
|
||||
**Prometheus Integration:**
|
||||
```yaml
|
||||
# Export metrics to Prometheus
|
||||
GLANCES_OPT=-w --export prometheus --export-prometheus-port 9091
|
||||
```
|
||||
|
||||
**Grafana Dashboards:**
|
||||
* **System Overview**: CPU, memory, disk, network
|
||||
* **Container Metrics**: Docker container statistics
|
||||
* **Process Monitoring**: Top processes and resource usage
|
||||
* **Historical Trends**: Performance over time
|
||||
|
||||
**Alert Manager Integration:**
|
||||
* **Threshold Alerts**: Configurable alert rules
|
||||
* **Notification Channels**: Email, Slack, webhook alerts
|
||||
* **Escalation Policies**: Multi-level alert handling
|
||||
* **Silence Management**: Alert suppression rules
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**Monitoring Strategy:**
|
||||
* **Key Metrics**: Focus on critical system metrics
|
||||
* **Alert Thresholds**: Set appropriate warning levels
|
||||
* **Baseline Establishment**: Understand normal system behavior
|
||||
* **Trend Analysis**: Monitor performance trends
|
||||
|
||||
**Alert Configuration:**
|
||||
* **Avoid Alert Fatigue**: Set meaningful thresholds
|
||||
* **Escalation Paths**: Define alert escalation procedures
|
||||
* **Maintenance Windows**: Suppress alerts during maintenance
|
||||
* **Testing**: Regularly test alert functionality
|
||||
|
||||
**Performance:**
|
||||
* **Resource Limits**: Appropriate CPU/memory allocation
|
||||
* **Refresh Rates**: Balance real-time vs performance
|
||||
* **Data Retention**: Configure appropriate history
|
||||
* **Optimization**: Enable only needed features
|
||||
|
||||
**Security:**
|
||||
* **Access Control**: Limit monitoring access
|
||||
* **Data Protection**: Secure monitoring data
|
||||
* **Network Security**: Secure monitoring traffic
|
||||
* **Compliance**: Meet monitoring compliance requirements
|
||||
|
||||
===== Use Cases =====
|
||||
|
||||
**System Administration:**
|
||||
* **Performance Monitoring**: Track system health
|
||||
* **Capacity Planning**: Plan for resource upgrades
|
||||
* **Troubleshooting**: Diagnose system issues
|
||||
* **Maintenance Planning**: Schedule maintenance windows
|
||||
|
||||
**Container Orchestration:**
|
||||
* **Resource Allocation**: Monitor container resources
|
||||
* **Health Checks**: Track container health
|
||||
* **Scaling Decisions**: Inform scaling decisions
|
||||
* **Optimization**: Optimize container performance
|
||||
|
||||
**Development & Testing:**
|
||||
* **Application Monitoring**: Monitor application performance
|
||||
* **Resource Usage**: Track development environment usage
|
||||
* **Debugging**: Identify performance bottlenecks
|
||||
* **Testing**: Validate system performance
|
||||
|
||||
**Production Monitoring:**
|
||||
* **SLA Monitoring**: Ensure service level agreements
|
||||
* **Incident Response**: Quick issue identification
|
||||
* **Root Cause Analysis**: Analyze system incidents
|
||||
* **Reporting**: Generate performance reports
|
||||
|
||||
===== Keyboard Shortcuts =====
|
||||
|
||||
**Navigation:**
|
||||
* **Tab**: Switch between sections
|
||||
* **Arrow Keys**: Navigate lists and menus
|
||||
* **Enter**: Select item or open details
|
||||
* **Esc**: Close dialogs or return to main view
|
||||
|
||||
**Actions:**
|
||||
* **R**: Refresh data
|
||||
* **S**: Sort current list
|
||||
* **F**: Filter/search
|
||||
* **H**: Show help
|
||||
|
||||
**Views:**
|
||||
* **1-9**: Switch to specific tabs
|
||||
* **C**: Container view
|
||||
* **P**: Process view
|
||||
* **A**: Alerts view
|
||||
|
||||
Glances provides comprehensive system and container monitoring with an intuitive web interface, essential for maintaining your homelab's health and performance.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:watchtower|Watchtower]] or explore [[architecture:monitoring|Monitoring Architecture]].
|
||||
@@ -0,0 +1,376 @@
|
||||
====== Pi-hole ======
|
||||
|
||||
Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking advertisements and tracking domains at the network level. It provides DNS-based ad blocking, DHCP server capabilities, and comprehensive network statistics.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Network-wide ad blocking and DNS
|
||||
**URL:** http://pihole.yourdomain.duckdns.org (HTTP only)
|
||||
**Authentication:** Authelia SSO protected
|
||||
**Deployment:** Infrastructure stack
|
||||
**Protocol:** DNS (port 53), DHCP (optional)
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**Ad Blocking:**
|
||||
* **DNS Sinkhole**: Blocks ad/tracking domains
|
||||
* **Network Wide**: Protects all devices on network
|
||||
* **Custom Lists**: Support for custom blocklists
|
||||
* **Whitelist/Blacklist**: Fine-grained control
|
||||
|
||||
**DNS Services:**
|
||||
* **Recursive DNS**: Full DNS resolution
|
||||
* **DNSSEC**: DNS security extensions
|
||||
* **Conditional Forwarding**: Local hostname resolution
|
||||
* **Rate Limiting**: Query rate limiting
|
||||
|
||||
**DHCP Server:**
|
||||
* **IP Address Assignment**: Dynamic IP allocation
|
||||
* **Static Leases**: Reserved IP addresses
|
||||
* **Network Configuration**: Gateway and DNS settings
|
||||
* **Client Management**: Device tracking
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
pihole:
|
||||
image: pihole/pihole:latest
|
||||
container_name: pihole
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- TZ=${TZ}
|
||||
- WEBPASSWORD=${PIHOLE_PASSWORD}
|
||||
- PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4
|
||||
- DHCP_ACTIVE=false # Set to true to enable DHCP
|
||||
- DHCP_START=192.168.1.100
|
||||
- DHCP_END=192.168.1.200
|
||||
- DHCP_ROUTER=192.168.1.1
|
||||
- DHCP_LEASETIME=24
|
||||
volumes:
|
||||
- ./pihole/etc-pihole:/etc/pihole
|
||||
- ./pihole/etc-dnsmasq.d:/etc/dnsmasq.d
|
||||
ports:
|
||||
- 53:53/tcp
|
||||
- 53:53/udp
|
||||
- 8082:80/tcp # Web interface
|
||||
networks:
|
||||
- traefik-network
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
reservations:
|
||||
cpus: '0.1'
|
||||
memory: 64M
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.pihole.rule=Host(`pihole.${DOMAIN}`)"
|
||||
- "traefik.http.routers.pihole.entrypoints=websecure"
|
||||
- "traefik.http.routers.pihole.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.pihole.middlewares=authelia@docker"
|
||||
- "traefik.http.services.pihole.loadbalancer.server.port=80"
|
||||
- "x-dockge.url=http://pihole.${DOMAIN}"
|
||||
dns:
|
||||
- 127.0.0.1
|
||||
- 1.1.1.1
|
||||
```
|
||||
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
# Required
|
||||
PIHOLE_PASSWORD=your-secure-password
|
||||
|
||||
# Optional DNS servers (comma-separated)
|
||||
PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4
|
||||
|
||||
# DHCP Configuration (if enabled)
|
||||
DHCP_ACTIVE=true
|
||||
DHCP_START=192.168.1.100
|
||||
DHCP_END=192.168.1.200
|
||||
DHCP_ROUTER=192.168.1.1
|
||||
DHCP_LEASETIME=24
|
||||
```
|
||||
|
||||
===== DNS Configuration =====
|
||||
|
||||
**Upstream DNS Servers:**
|
||||
* **Cloudflare**: 1.1.1.1, 1.0.0.1 (default)
|
||||
* **Google**: 8.8.8.8, 8.8.4.4
|
||||
* **Quad9**: 9.9.9.9, 149.112.112.112
|
||||
* **OpenDNS**: 208.67.222.222, 208.67.220.220
|
||||
|
||||
**DNS Settings:**
|
||||
```bash
|
||||
# In Pi-hole admin interface
|
||||
# Settings > DNS
|
||||
# Enable DNSSEC for enhanced security
|
||||
# Configure conditional forwarding for local network
|
||||
```
|
||||
|
||||
**Client Configuration:**
|
||||
* **Router DNS**: Set router to use Pi-hole IP
|
||||
* **Device DNS**: Configure individual devices
|
||||
* **DHCP**: Enable DHCP server in Pi-hole
|
||||
* **IPv6**: Configure IPv6 DNS if needed
|
||||
|
||||
===== Ad Blocking Setup =====
|
||||
|
||||
**Blocklists:**
|
||||
* **Default Lists**: Pre-configured ad/tracking lists
|
||||
* **Custom Lists**: Add your own blocklists
|
||||
* **Gravity Update**: Regular list updates
|
||||
* **Regex Filtering**: Advanced pattern matching
|
||||
|
||||
**Whitelist/Blacklist:**
|
||||
* **Whitelist**: Allow specific domains
|
||||
* **Blacklist**: Block additional domains
|
||||
* **Regex**: Pattern-based filtering
|
||||
* **Client Groups**: Per-device rules
|
||||
|
||||
**Group Management:**
|
||||
```bash
|
||||
# Create client groups for different policies
|
||||
# Assign devices to groups
|
||||
# Apply different filtering rules per group
|
||||
```
|
||||
|
||||
===== DHCP Server Configuration =====
|
||||
|
||||
**DHCP Setup:**
|
||||
```yaml
|
||||
environment:
|
||||
- DHCP_ACTIVE=true
|
||||
- DHCP_START=192.168.1.100
|
||||
- DHCP_END=192.168.1.200
|
||||
- DHCP_ROUTER=192.168.1.1
|
||||
- DHCP_LEASETIME=24
|
||||
```
|
||||
|
||||
**Static Leases:**
|
||||
* **MAC Address**: Device hardware address
|
||||
* **IP Address**: Reserved static IP
|
||||
* **Hostname**: Device name
|
||||
* **Description**: Device description
|
||||
|
||||
**DHCP Options:**
|
||||
* **Domain Name**: Local domain suffix
|
||||
* **NTP Servers**: Time synchronization
|
||||
* **PXE Boot**: Network boot options
|
||||
* **Vendor Options**: Device-specific options
|
||||
|
||||
===== Monitoring & Statistics =====
|
||||
|
||||
**Dashboard Overview:**
|
||||
* **Total Queries**: DNS query volume
|
||||
* **Blocked Domains**: Ad blocking statistics
|
||||
* **Top Clients**: Most active devices
|
||||
* **Top Domains**: Frequently queried domains
|
||||
|
||||
**Query Log:**
|
||||
* **Real-time Monitoring**: Live query feed
|
||||
* **Filtering**: Search and filter queries
|
||||
* **Blocking Status**: See what's blocked/allowed
|
||||
* **Client Tracking**: Per-device statistics
|
||||
|
||||
**Long-term Statistics:**
|
||||
* **Historical Data**: Query trends over time
|
||||
* **Blocking Efficiency**: Ad blocking performance
|
||||
* **Client Usage**: Device activity patterns
|
||||
* **Domain Analysis**: Popular domain tracking
|
||||
|
||||
===== Security Features =====
|
||||
|
||||
**Access Control:**
|
||||
* **Web Interface**: Password protected
|
||||
* **Authelia Integration**: SSO authentication
|
||||
* **IP Restrictions**: Limit admin access
|
||||
* **Session Management**: Secure login sessions
|
||||
|
||||
**DNS Security:**
|
||||
* **DNSSEC**: Domain signature validation
|
||||
* **Query Logging**: Audit trail of requests
|
||||
* **Rate Limiting**: Prevent DNS amplification
|
||||
* **Cache Poisoning**: Protection against attacks
|
||||
|
||||
**Network Security:**
|
||||
* **Firewall Integration**: UFW/iptables rules
|
||||
* **Port Protection**: Restrict unnecessary ports
|
||||
* **Traffic Monitoring**: Network traffic analysis
|
||||
* **Intrusion Detection**: Suspicious activity alerts
|
||||
|
||||
===== Performance Optimization =====
|
||||
|
||||
**DNS Performance:**
|
||||
```yaml
|
||||
# Optimize DNS settings
|
||||
# Settings > DNS > Interface Settings
|
||||
# Enable cache optimization
|
||||
# Configure upstream server timeout
|
||||
```
|
||||
|
||||
**Resource Limits:**
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 256M
|
||||
reservations:
|
||||
cpus: '0.1'
|
||||
memory: 64M
|
||||
```
|
||||
|
||||
**Caching:**
|
||||
* **DNS Cache**: Local query caching
|
||||
* **Blocklist Cache**: Efficient blocklist lookups
|
||||
* **Negative Cache**: Failed query caching
|
||||
* **TTL Management**: Cache expiration handling
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**DNS Resolution Issues:**
|
||||
```bash
|
||||
# Check DNS resolution
|
||||
nslookup google.com 127.0.0.1
|
||||
|
||||
# Test Pi-hole DNS
|
||||
dig @127.0.0.1 google.com
|
||||
|
||||
# Check upstream connectivity
|
||||
dig @8.8.8.8 google.com
|
||||
```
|
||||
|
||||
**Ad Blocking Problems:**
|
||||
* **Test Blocking**: Visit ad-heavy sites
|
||||
* **Check Lists**: Verify blocklists are updating
|
||||
* **Whitelist Issues**: Check whitelist configuration
|
||||
* **Client Bypass**: Some apps bypass DNS
|
||||
|
||||
**DHCP Issues:**
|
||||
* **IP Conflicts**: Check for IP address conflicts
|
||||
* **Lease Problems**: Clear DHCP leases
|
||||
* **Router Settings**: Verify router DHCP disabled
|
||||
* **Network Issues**: Check network connectivity
|
||||
|
||||
**Web Interface Problems:**
|
||||
* **Login Issues**: Reset admin password
|
||||
* **SSL Problems**: Check certificate validity
|
||||
* **Authelia**: Verify SSO configuration
|
||||
* **Browser Cache**: Clear browser cache
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs pihole`
|
||||
2. **Test DNS**: Verify DNS resolution works
|
||||
3. **Check configuration**: Validate environment variables
|
||||
4. **Network connectivity**: Test upstream DNS
|
||||
5. **Restart service**: `docker restart pihole`
|
||||
|
||||
===== Advanced Configuration =====
|
||||
|
||||
**Custom DNS Records:**
|
||||
```bash
|
||||
# Add local DNS records
|
||||
# Settings > Local DNS > DNS Records
|
||||
# Add A, AAAA, CNAME, PTR records
|
||||
```
|
||||
|
||||
**Conditional Forwarding:**
|
||||
```bash
|
||||
# Forward local queries to router
|
||||
# Settings > DNS > Advanced Settings
|
||||
# Enable conditional forwarding
|
||||
# Set router IP and local domain
|
||||
```
|
||||
|
||||
**Regex Blocking:**
|
||||
```bash
|
||||
# Advanced blocking patterns
|
||||
# Settings > DNS > Group Management
|
||||
# Create regex filters for complex patterns
|
||||
```
|
||||
|
||||
**API Access:**
|
||||
```bash
|
||||
# Enable API for external tools
|
||||
# Settings > API > Show API token
|
||||
# Use token for programmatic access
|
||||
```
|
||||
|
||||
===== Integration with Other Services =====
|
||||
|
||||
**Router Integration:**
|
||||
* **DNS Settings**: Configure router to use Pi-hole
|
||||
* **DHCP Disable**: Disable router DHCP if using Pi-hole
|
||||
* **Port Forwarding**: Forward port 53 to Pi-hole
|
||||
* **Static IP**: Give Pi-hole static IP address
|
||||
|
||||
**Monitoring Integration:**
|
||||
* **Prometheus**: Export metrics for monitoring
|
||||
* **Grafana**: Create dashboards for Pi-hole stats
|
||||
* **Uptime Kuma**: Monitor Pi-hole availability
|
||||
* **Alerting**: Set up alerts for service issues
|
||||
|
||||
**Backup Integration:**
|
||||
* **Configuration Backup**: Backup Pi-hole settings
|
||||
* **Blocklist Backup**: Save custom lists
|
||||
* **DHCP Backup**: Backup DHCP leases
|
||||
* **Automated Backups**: Schedule regular backups
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**DNS Configuration:**
|
||||
* **Multiple Upstream**: Use multiple DNS servers
|
||||
* **DNSSEC**: Enable DNS security
|
||||
* **Conditional Forwarding**: Enable for local network
|
||||
* **Rate Limiting**: Prevent abuse
|
||||
|
||||
**Ad Blocking:**
|
||||
* **Regular Updates**: Keep blocklists current
|
||||
* **Custom Lists**: Add domain-specific blocks
|
||||
* **Whitelist Carefully**: Only whitelist necessary sites
|
||||
* **Test Blocking**: Verify blocking effectiveness
|
||||
|
||||
**DHCP Management:**
|
||||
* **IP Planning**: Plan IP address ranges
|
||||
* **Static Leases**: Reserve IPs for servers
|
||||
* **Lease Time**: Appropriate lease durations
|
||||
* **Monitoring**: Track DHCP usage
|
||||
|
||||
**Security:**
|
||||
* **Strong Password**: Secure admin password
|
||||
* **Access Control**: Limit admin access
|
||||
* **Updates**: Keep Pi-hole updated
|
||||
* **Monitoring**: Monitor for security issues
|
||||
|
||||
**Maintenance:**
|
||||
* **Log Rotation**: Manage log file sizes
|
||||
* **Database Optimization**: Regular database maintenance
|
||||
* **Backup Routine**: Regular configuration backups
|
||||
* **Performance Monitoring**: Track resource usage
|
||||
|
||||
===== Common Use Cases =====
|
||||
|
||||
**Home Network:**
|
||||
* **Ad Blocking**: Block ads on all devices
|
||||
* **Parental Controls**: Block inappropriate content
|
||||
* **Device Management**: Track and manage devices
|
||||
* **Network Monitoring**: Monitor network activity
|
||||
|
||||
**Small Office:**
|
||||
* **Content Filtering**: Block productivity-draining sites
|
||||
* **Guest Network**: Separate guest DNS
|
||||
* **Device Control**: Manage corporate devices
|
||||
* **Reporting**: Generate usage reports
|
||||
|
||||
**Development:**
|
||||
* **Local DNS**: Resolve development domains
|
||||
* **Testing**: Test ad blocking effectiveness
|
||||
* **Network Simulation**: Simulate network conditions
|
||||
* **Debugging**: Debug DNS-related issues
|
||||
|
||||
Pi-hole provides essential network services with powerful ad blocking capabilities, serving as the DNS backbone of your homelab network.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:dozzle|Dozzle]] or explore [[architecture:networking|Network Architecture]].
|
||||
@@ -0,0 +1,404 @@
|
||||
====== Watchtower ======
|
||||
|
||||
Watchtower is an automated container update service that monitors running Docker containers and automatically updates them when new images are available. It ensures your homelab services stay up-to-date with the latest security patches and features.
|
||||
|
||||
===== Overview =====
|
||||
|
||||
**Purpose:** Automated container updates
|
||||
**Deployment:** Infrastructure stack (currently disabled)
|
||||
**Monitoring:** Passive background service
|
||||
**Update Strategy:** Rolling updates with health checks
|
||||
|
||||
===== Key Features =====
|
||||
|
||||
**Automated Updates:**
|
||||
* **Image Monitoring**: Checks for new image versions
|
||||
* **Scheduled Updates**: Configurable update intervals
|
||||
* **Rolling Updates**: Updates containers one by one
|
||||
* **Health Checks**: Waits for container health before proceeding
|
||||
|
||||
**Update Control:**
|
||||
* **Include/Exclude**: Control which containers to update
|
||||
* **Update Notifications**: Email/Slack notifications
|
||||
* **Rollback Support**: Revert to previous versions
|
||||
* **Dry Run Mode**: Test updates without applying
|
||||
|
||||
**Safety Features:**
|
||||
* **Health Monitoring**: Ensures containers start successfully
|
||||
* **Timeout Control**: Prevents hanging updates
|
||||
* **Resource Limits**: Controls update resource usage
|
||||
* **Backup Integration**: Coordinates with backup services
|
||||
|
||||
===== Configuration =====
|
||||
|
||||
**Container Configuration:**
|
||||
```yaml
|
||||
services:
|
||||
watchtower:
|
||||
image: containrrr/watchtower:latest
|
||||
container_name: watchtower
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- WATCHTOWER_CLEANUP=true
|
||||
- WATCHTOWER_POLL_INTERVAL=3600
|
||||
- WATCHTOWER_TIMEOUT=30s
|
||||
- WATCHTOWER_NOTIFICATIONS=shoutrrr
|
||||
- WATCHTOWER_NOTIFICATION_URL=discord://token@webhook
|
||||
- WATCHTOWER_INCLUDE_STOPPED=false
|
||||
- WATCHTOWER_REVIVE_STOPPED=false
|
||||
- WATCHTOWER_REMOVE_VOLUMES=false
|
||||
- WATCHTOWER_LABEL_ENABLE=true
|
||||
- WATCHTOWER_MONITOR_ONLY=false
|
||||
- WATCHTOWER_RUN_ONCE=false
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
command: --interval 3600 --cleanup --label-enable
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.2'
|
||||
memory: 64M
|
||||
reservations:
|
||||
cpus: '0.01'
|
||||
memory: 16M
|
||||
```
|
||||
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
# Update interval (seconds)
|
||||
WATCHTOWER_POLL_INTERVAL=3600
|
||||
|
||||
# Update timeout
|
||||
WATCHTOWER_TIMEOUT=30s
|
||||
|
||||
# Cleanup old images
|
||||
WATCHTOWER_CLEANUP=true
|
||||
|
||||
# Notification settings
|
||||
WATCHTOWER_NOTIFICATIONS=shoutrrr
|
||||
WATCHTOWER_NOTIFICATION_URL=discord://token@webhook
|
||||
|
||||
# Container control
|
||||
WATCHTOWER_INCLUDE_STOPPED=false
|
||||
WATCHTOWER_REVIVE_STOPPED=false
|
||||
WATCHTOWER_REMOVE_VOLUMES=false
|
||||
|
||||
# Label-based control
|
||||
WATCHTOWER_LABEL_ENABLE=true
|
||||
|
||||
# Monitoring mode
|
||||
WATCHTOWER_MONITOR_ONLY=false
|
||||
|
||||
# One-time run
|
||||
WATCHTOWER_RUN_ONCE=false
|
||||
```
|
||||
|
||||
===== Update Process =====
|
||||
|
||||
**Monitoring Phase:**
|
||||
1. **Image Check**: Queries Docker registry for new versions
|
||||
2. **Version Comparison**: Compares current vs latest versions
|
||||
3. **Update Decision**: Determines if update is needed
|
||||
4. **Schedule Planning**: Plans update timing
|
||||
|
||||
**Update Execution:**
|
||||
1. **Container Stop**: Gracefully stops current container
|
||||
2. **Image Pull**: Downloads new image version
|
||||
3. **Container Start**: Starts container with new image
|
||||
4. **Health Check**: Verifies container health
|
||||
5. **Cleanup**: Removes old images (if enabled)
|
||||
|
||||
**Post-Update:**
|
||||
* **Notification**: Sends update notifications
|
||||
* **Logging**: Records update details
|
||||
* **Monitoring**: Continues monitoring for next updates
|
||||
* **Error Handling**: Handles update failures
|
||||
|
||||
===== Container Selection =====
|
||||
|
||||
**Label-Based Control:**
|
||||
```yaml
|
||||
# Enable updates for specific containers
|
||||
labels:
|
||||
- "com.centurylinklabs.watchtower.enable=true"
|
||||
|
||||
# Disable updates for specific containers
|
||||
labels:
|
||||
- "com.centurylinklabs.watchtower.enable=false"
|
||||
```
|
||||
|
||||
**Include/Exclude Patterns:**
|
||||
```bash
|
||||
# Include only specific containers
|
||||
command: --include=traefik,authelia,dockge
|
||||
|
||||
# Exclude specific containers
|
||||
command: --exclude=plex,jellyfin
|
||||
|
||||
# Use regex patterns
|
||||
command: --include="^media-.*"
|
||||
```
|
||||
|
||||
**Scope Control:**
|
||||
* **All Containers**: Update all running containers
|
||||
* **Specific Services**: Update only selected services
|
||||
* **Stack-Based**: Update containers in specific stacks
|
||||
* **Label-Based**: Use Docker labels for control
|
||||
|
||||
===== Notification System =====
|
||||
|
||||
**Supported Notifications:**
|
||||
* **Email**: SMTP email notifications
|
||||
* **Slack**: Slack channel notifications
|
||||
* **Discord**: Discord webhook notifications
|
||||
* **Gotify**: Gotify push notifications
|
||||
* **Telegram**: Telegram bot notifications
|
||||
|
||||
**Notification Configuration:**
|
||||
```yaml
|
||||
environment:
|
||||
- WATCHTOWER_NOTIFICATIONS=shoutrrr
|
||||
- WATCHTOWER_NOTIFICATION_URL=slack://token@channel
|
||||
# Or for Discord
|
||||
- WATCHTOWER_NOTIFICATION_URL=discord://token@webhook
|
||||
# Or for email
|
||||
- WATCHTOWER_NOTIFICATION_URL=smtp://user:pass@host:port
|
||||
```
|
||||
|
||||
**Notification Content:**
|
||||
* **Update Started**: Container update beginning
|
||||
* **Update Completed**: Successful update confirmation
|
||||
* **Update Failed**: Error details and troubleshooting
|
||||
* **Rollback Performed**: Automatic rollback notifications
|
||||
|
||||
===== Safety & Reliability =====
|
||||
|
||||
**Health Checks:**
|
||||
```yaml
|
||||
# Wait for health checks
|
||||
command: --interval 3600 --cleanup --label-enable --enable-healthchecks
|
||||
```
|
||||
|
||||
**Timeout Management:**
|
||||
```yaml
|
||||
# Set update timeouts
|
||||
environment:
|
||||
- WATCHTOWER_TIMEOUT=60s
|
||||
```
|
||||
|
||||
**Rollback Capability:**
|
||||
```yaml
|
||||
# Enable automatic rollback on failure
|
||||
command: --rollback-on-failure
|
||||
```
|
||||
|
||||
**Resource Protection:**
|
||||
* **CPU Limits**: Prevent update resource exhaustion
|
||||
* **Memory Limits**: Control memory usage during updates
|
||||
* **Network Limits**: Manage download bandwidth
|
||||
* **Concurrent Updates**: Limit simultaneous updates
|
||||
|
||||
===== Scheduling =====
|
||||
|
||||
**Update Intervals:**
|
||||
```bash
|
||||
# Check every hour
|
||||
command: --interval 3600
|
||||
|
||||
# Check every 24 hours
|
||||
command: --interval 86400
|
||||
|
||||
# Check at specific times
|
||||
command: --schedule "0 0 4 * * *" # Daily at 4 AM
|
||||
```
|
||||
|
||||
**Maintenance Windows:**
|
||||
* **Off-hours Updates**: Schedule updates during low-usage times
|
||||
* **Weekend Updates**: Perform updates on weekends
|
||||
* **Manual Control**: Trigger updates manually when needed
|
||||
* **Holiday Scheduling**: Avoid updates during holidays
|
||||
|
||||
===== Troubleshooting =====
|
||||
|
||||
**Update Failures:**
|
||||
```bash
|
||||
# Check Watchtower logs
|
||||
docker logs watchtower
|
||||
|
||||
# Manual update test
|
||||
docker pull image:latest
|
||||
docker stop container
|
||||
docker rm container
|
||||
docker run -d --name container image:latest
|
||||
```
|
||||
|
||||
**Permission Issues:**
|
||||
* **Docker Socket**: Verify socket access permissions
|
||||
* **Registry Access**: Check Docker registry authentication
|
||||
* **Network Issues**: Verify internet connectivity
|
||||
* **Disk Space**: Ensure sufficient space for image downloads
|
||||
|
||||
**Notification Problems:**
|
||||
* **Webhook URLs**: Verify notification endpoint URLs
|
||||
* **Authentication**: Check API tokens and credentials
|
||||
* **Network Access**: Ensure outbound connectivity
|
||||
* **Rate Limits**: Check service rate limiting
|
||||
|
||||
**Performance Issues:**
|
||||
* **Resource Usage**: Monitor CPU/memory during updates
|
||||
* **Update Frequency**: Adjust polling intervals
|
||||
* **Concurrent Updates**: Limit simultaneous container updates
|
||||
* **Network Bandwidth**: Control download speeds
|
||||
|
||||
**Troubleshooting Steps:**
|
||||
1. **Check logs**: `docker logs watchtower`
|
||||
2. **Test manually**: Perform manual container updates
|
||||
3. **Verify configuration**: Check environment variables
|
||||
4. **Test notifications**: Send test notifications
|
||||
5. **Restart service**: `docker restart watchtower`
|
||||
|
||||
===== Advanced Configuration =====
|
||||
|
||||
**Custom Update Logic:**
|
||||
```bash
|
||||
# Use custom update script
|
||||
command: --script /path/to/update-script.sh
|
||||
```
|
||||
|
||||
**Lifecycle Hooks:**
|
||||
```yaml
|
||||
# Pre/post update hooks
|
||||
command: --pre-check /path/to/pre-check.sh --post-check /path/to/post-check.sh
|
||||
```
|
||||
|
||||
**Advanced Filtering:**
|
||||
```bash
|
||||
# Complex filtering rules
|
||||
command: --filter-by-label=com.example.version=latest --filter-by-label=com.example.tier=frontend
|
||||
```
|
||||
|
||||
**Monitoring Integration:**
|
||||
```yaml
|
||||
# Export metrics
|
||||
command: --metrics
|
||||
environment:
|
||||
- WATCHTOWER_METRICS_PORT=8080
|
||||
```
|
||||
|
||||
===== Security Considerations =====
|
||||
|
||||
**Access Control:**
|
||||
* **Docker Socket Security**: Read-only socket access
|
||||
* **Registry Authentication**: Secure registry credentials
|
||||
* **Network Security**: Secure update traffic
|
||||
* **Audit Logging**: Track all update activities
|
||||
|
||||
**Update Security:**
|
||||
* **Image Verification**: Verify image authenticity
|
||||
* **Vulnerability Scanning**: Check for security issues
|
||||
* **Trusted Sources**: Only update from trusted registries
|
||||
* **Rollback Security**: Secure rollback procedures
|
||||
|
||||
===== Integration with Backup =====
|
||||
|
||||
**Backup Coordination:**
|
||||
```yaml
|
||||
# Coordinate with backup services
|
||||
command: --pre-check /scripts/backup-check.sh --post-check /scripts/backup-verify.sh
|
||||
```
|
||||
|
||||
**Backup Scripts:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Pre-update backup
|
||||
docker exec backup-service backup-now
|
||||
|
||||
# Post-update verification
|
||||
docker exec backup-service verify-backup
|
||||
```
|
||||
|
||||
**Automated Backup:**
|
||||
* **Pre-update Backup**: Backup before each update
|
||||
* **Post-update Verification**: Verify backup integrity
|
||||
* **Rollback Backup**: Maintain rollback capability
|
||||
* **Retention Policy**: Manage backup retention
|
||||
|
||||
===== Best Practices =====
|
||||
|
||||
**Update Strategy:**
|
||||
* **Staged Updates**: Update non-critical services first
|
||||
* **Monitoring**: Monitor updates closely initially
|
||||
* **Testing**: Test updates in development first
|
||||
* **Documentation**: Document update procedures
|
||||
|
||||
**Safety Measures:**
|
||||
* **Health Checks**: Always enable health checks
|
||||
* **Timeouts**: Set appropriate update timeouts
|
||||
* **Notifications**: Enable comprehensive notifications
|
||||
* **Rollback**: Have rollback procedures ready
|
||||
|
||||
**Performance:**
|
||||
* **Resource Limits**: Appropriate CPU/memory limits
|
||||
* **Update Windows**: Schedule during low-usage times
|
||||
* **Concurrent Limits**: Limit simultaneous updates
|
||||
* **Network Management**: Control bandwidth usage
|
||||
|
||||
**Monitoring:**
|
||||
* **Update Tracking**: Monitor update success/failure
|
||||
* **Performance Impact**: Track update performance impact
|
||||
* **Error Analysis**: Analyze update failure patterns
|
||||
* **Success Metrics**: Track update success rates
|
||||
|
||||
===== Use Cases =====
|
||||
|
||||
**Production Environments:**
|
||||
* **Security Updates**: Automatic security patch deployment
|
||||
* **Feature Updates**: Deploy new features automatically
|
||||
* **Compliance**: Maintain compliance with update policies
|
||||
* **Stability**: Ensure service stability through updates
|
||||
|
||||
**Development Environments:**
|
||||
* **Testing Updates**: Test update procedures safely
|
||||
* **CI/CD Integration**: Integrate with development pipelines
|
||||
* **Version Control**: Manage container versions
|
||||
* **Rollback Testing**: Test rollback capabilities
|
||||
|
||||
**Homelab Management:**
|
||||
* **Convenience**: Hands-off update management
|
||||
* **Security**: Maintain security through updates
|
||||
* **Stability**: Prevent version drift issues
|
||||
* **Monitoring**: Track update status and health
|
||||
|
||||
**Enterprise Deployments:**
|
||||
* **Policy Compliance**: Enforce update policies
|
||||
* **Change Management**: Manage change through updates
|
||||
* **Audit Trails**: Maintain update audit logs
|
||||
* **Reporting**: Generate update compliance reports
|
||||
|
||||
===== Manual Update Process =====
|
||||
|
||||
**When Watchtower is Disabled:**
|
||||
```bash
|
||||
# Manual update procedure
|
||||
# 1. Identify containers to update
|
||||
docker ps --format "table {{.Names}}\t{{.Image}}"
|
||||
|
||||
# 2. Check for updates
|
||||
docker pull image:latest
|
||||
|
||||
# 3. Backup current state
|
||||
docker tag current-image backup-image
|
||||
|
||||
# 4. Stop and update container
|
||||
docker stop container
|
||||
docker rm container
|
||||
docker run -d --name container image:latest
|
||||
|
||||
# 5. Verify update
|
||||
docker logs container
|
||||
docker ps | grep container
|
||||
```
|
||||
|
||||
Watchtower provides automated container updates with safety features and monitoring, ensuring your homelab services remain current and secure.
|
||||
|
||||
**Next:** Learn about [[services:infrastructure:code-server|Code Server]] or explore [[architecture:backup|Backup Architecture]].
|
||||
Reference in New Issue
Block a user