Documentation Reorganization
Major upgrade to the documentation.
This commit is contained in:
kelinfoxy
117
docs/Ondemand-Remote-Services.md
Normal file
117
docs/Ondemand-Remote-Services.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# On Demand Remote Services with Authelia, Sablier & Traefik
|
||||
|
||||
## 4 Step Process
|
||||
1. Add route & service in Traefik external hosts file
|
||||
2. Add middleware in Sablier config file (sablier.yml)
|
||||
3. Add labels to compose files on Remote Host
|
||||
4. Restart services
|
||||
|
||||
## Required Information
|
||||
```bash
|
||||
<server> - the hostname of the remote server
|
||||
|
||||
<service> - the application/container name
|
||||
|
||||
<full domain> - the base url for your proxy host (my-subdomain.duckdns.org)
|
||||
|
||||
<ip address> - the ip address of the remote server
|
||||
|
||||
<port> - the external port exposed by the service
|
||||
|
||||
<service display name> - how it will appear on the now loading page
|
||||
|
||||
<group name> - use <service name> for a single service, or something descriptive for the group of services that will start together.
|
||||
|
||||
```
|
||||
## Step 1: Add route & service in Traefik external hosts file
|
||||
|
||||
### In /opt/stacks/core/traefik/dynamic/external-host-server_name.yml
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
# Add a section under routers for each Route (Proxy Host)
|
||||
<service>-<server>:
|
||||
rule: "Host(`<service>.<full domain>`)"
|
||||
entryPoints:
|
||||
- websecure
|
||||
service: <service>-<server>
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
middlewares:
|
||||
- sablier-<server>-<service>@file
|
||||
- authelia@docker # comment this line to disable SSO login
|
||||
|
||||
# next route goes here
|
||||
|
||||
# All Routes go above this line
|
||||
# Services section defines each service used above
|
||||
services:
|
||||
<service>-<server>:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://<ip address>:<port>"
|
||||
passHostHeader: true
|
||||
|
||||
# next service goes here
|
||||
```
|
||||
## Step 2: Add middlware to sablier config file
|
||||
|
||||
### In /opt/stacks/core/traefik/dynamic/sablier.yml
|
||||
|
||||
```yaml
|
||||
http:
|
||||
middlwares:
|
||||
# Add a section under middlewares for each Route (Proxy Host)
|
||||
sablier-<server>-<service>:
|
||||
plugin:
|
||||
sablier:
|
||||
sablierUrl: http://sablier-service:10000
|
||||
group: <server>-<group name>
|
||||
sessionDuration: 2m # Increase this for convience
|
||||
ignoreUserAgent: curl # Don't wake the service for a curl command
|
||||
dynamic:
|
||||
displayName: <service display name>
|
||||
theme: ghost # This can be changed
|
||||
show-details-by-default: true # May want to disable for production
|
||||
|
||||
# Next middleware goes here
|
||||
```
|
||||
## Step 3: Add labels to compose files on Remote Host
|
||||
|
||||
## On the Remote Server
|
||||
|
||||
### Apply lables to the services in the compose files
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- sablier.enable=true
|
||||
- sablier.group=<server>-<group name>
|
||||
- sablier.start-on-demand=true
|
||||
|
||||
```
|
||||
|
||||
>**Note**:
|
||||
Traefik & Authelia labels are not used in the compose file for Remote Hosts
|
||||
|
||||
## Step 4: Restart services
|
||||
|
||||
### On host system
|
||||
|
||||
```bash
|
||||
docker restart traefik
|
||||
docker restart sablier-service
|
||||
```
|
||||
|
||||
### On the Remote Host
|
||||
|
||||
```bash
|
||||
cd /opt/stacks/<service>
|
||||
docker compose down && docker compose up -d
|
||||
docker stop <service>
|
||||
```
|
||||
|
||||
## Setup Complete
|
||||
|
||||
Access your service by the proxy url.
|
||||
|
||||
182
docs/README.md
Normal file
182
docs/README.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# AI-Homelab Documentation
|
||||
|
||||
Welcome to the AI-Homelab documentation! This is your comprehensive guide to deploying and managing a production-ready homelab infrastructure with 70+ pre-configured services.
|
||||
|
||||
## 📚 Documentation Structure
|
||||
|
||||
### 🚀 Getting Started
|
||||
- **[Quick Start Guide](getting-started.md)** - Step-by-step setup for new users
|
||||
- **[Prerequisites & Requirements](getting-started.md#prerequisites)** - What you need before starting
|
||||
- **[First Deployment](getting-started.md#simple-setup)** - Automated setup process
|
||||
|
||||
### 🏗️ Architecture & Design
|
||||
- **[System Architecture](README.md#key-features)** - High-level overview of components
|
||||
- **[Network Architecture](docker-guidelines.md#network-architecture)** - How services communicate
|
||||
- **[Security Model](docker-guidelines.md#security-best-practices)** - Authentication, SSL, and access control
|
||||
- **[Storage Strategy](docker-guidelines.md#volume-management)** - Data persistence and organization
|
||||
|
||||
### 💾 Backup & Recovery
|
||||
- **[Backup Strategy](Restic-BackRest-Backup-Guide.md)** - Comprehensive Restic + Backrest guide (default strategy)
|
||||
- **[Backrest Service](service-docs/backrest.md)** - Web UI for backup management
|
||||
|
||||
### 📦 Services & Stacks
|
||||
|
||||
#### Core Infrastructure (Deploy First)
|
||||
Essential services that everything else depends on:
|
||||
- **[DuckDNS](service-docs/duckdns.md)** - Dynamic DNS updates
|
||||
- **[Traefik](service-docs/traefik.md)** - Reverse proxy & SSL termination
|
||||
- **[Authelia](service-docs/authelia.md)** - Single Sign-On authentication
|
||||
- **[Gluetun](service-docs/gluetun.md)** - VPN client for secure downloads
|
||||
- **[Sablier](service-docs/sablier.md)** - Lazy loading service for on-demand containers
|
||||
|
||||
#### Management & Monitoring
|
||||
- **[Dockge](service-docs/dockge.md)** - Primary stack management UI
|
||||
- **[Homepage](service-docs/homepage.md)** - Service dashboard (AI-configurable)
|
||||
- **[Homarr](service-docs/homarr.md)** - Alternative modern dashboard
|
||||
- **[Dozzle](service-docs/dozzle.md)** - Real-time log viewer
|
||||
- **[Glances](service-docs/glances.md)** - System monitoring
|
||||
- **[Pi-hole](service-docs/pihole.md)** - DNS & ad blocking
|
||||
|
||||
#### Media Services
|
||||
- **[Jellyfin](service-docs/jellyfin.md)** - Open-source media streaming
|
||||
- **[Plex](service-docs/plex.md)** - Popular media server (alternative)
|
||||
- **[qBittorrent](service-docs/qbittorrent.md)** - Torrent client (VPN-routed)
|
||||
- **[Calibre-Web](service-docs/calibre-web.md)** - Ebook reader & server
|
||||
|
||||
#### Media Management (Arr Stack)
|
||||
- **[Sonarr](service-docs/sonarr.md)** - TV show automation
|
||||
- **[Radarr](service-docs/radarr.md)** - Movie automation
|
||||
- **[Prowlarr](service-docs/prowlarr.md)** - Indexer management
|
||||
- **[Readarr](service-docs/readarr.md)** - Ebook/audiobook automation
|
||||
- **[Lidarr](service-docs/lidarr.md)** - Music library management
|
||||
- **[Bazarr](service-docs/bazarr.md)** - Subtitle automation
|
||||
- **[Jellyseerr](service-docs/jellyseerr.md)** - Media request interface
|
||||
|
||||
#### Home Automation
|
||||
- **[Home Assistant](service-docs/home-assistant.md)** - Smart home platform
|
||||
- **[Node-RED](service-docs/node-red.md)** - Flow-based programming
|
||||
- **[Zigbee2MQTT](service-docs/zigbee2mqtt.md)** - Zigbee device integration
|
||||
- **[ESPHome](service-docs/esphome.md)** - ESP device firmware
|
||||
- **[TasmoAdmin](service-docs/tasmoadmin.md)** - Tasmota device management
|
||||
- **[MotionEye](service-docs/motioneye.md)** - Video surveillance
|
||||
|
||||
#### Productivity & Collaboration
|
||||
- **[Nextcloud](service-docs/nextcloud.md)** - Self-hosted cloud storage
|
||||
- **[Gitea](service-docs/gitea.md)** - Git service (GitHub alternative)
|
||||
- **[BookStack](service-docs/bookstack.md)** - Documentation/wiki platform
|
||||
- **[WordPress](service-docs/wordpress.md)** - Blog/CMS platform
|
||||
- **[MediaWiki](service-docs/mediawiki.md)** - Wiki platform
|
||||
- **[DokuWiki](service-docs/dokuwiki.md)** - Simple wiki
|
||||
- **[Excalidraw](service-docs/excalidraw.md)** - Collaborative drawing
|
||||
|
||||
#### Development Tools
|
||||
- **[Code Server](service-docs/code-server.md)** - VS Code in the browser
|
||||
- **[GitLab](service-docs/gitlab.md)** - Complete DevOps platform
|
||||
- **[Jupyter](service-docs/jupyter.md)** - Interactive computing
|
||||
- **[pgAdmin](service-docs/pgadmin.md)** - PostgreSQL administration
|
||||
|
||||
#### Monitoring & Observability
|
||||
- **[Grafana](service-docs/grafana.md)** - Metrics visualization
|
||||
- **[Prometheus](service-docs/prometheus.md)** - Metrics collection
|
||||
- **[Uptime Kuma](service-docs/uptime-kuma.md)** - Uptime monitoring
|
||||
- **[Loki](service-docs/loki.md)** - Log aggregation
|
||||
- **[Promtail](service-docs/promtail.md)** - Log shipping
|
||||
- **[Node Exporter](service-docs/node-exporter.md)** - System metrics
|
||||
- **[cAdvisor](service-docs/cadvisor.md)** - Container metrics
|
||||
|
||||
#### Utilities & Tools
|
||||
- **[Backrest](service-docs/backrest.md)** - Backup management (Restic-based, default)
|
||||
- **[Duplicati](service-docs/duplicati.md)** - Alternative backup solution
|
||||
- **[FreshRSS](service-docs/freshrss.md)** - RSS feed reader
|
||||
- **[Wallabag](service-docs/wallabag.md)** - Read-it-later service
|
||||
- **[Watchtower](service-docs/watchtower.md)** - Automatic updates
|
||||
- **[Vaultwarden](service-docs/vaultwarden.md)** - Password manager
|
||||
|
||||
#### Alternative Services
|
||||
Services that provide alternatives to the defaults:
|
||||
- **[Portainer](service-docs/portainer.md)** - Alternative container management
|
||||
- **[Authentik](service-docs/authentik.md)** - Alternative SSO with web UI
|
||||
|
||||
### 🛠️ Development & Operations
|
||||
|
||||
#### Docker & Container Management
|
||||
- **[Docker Guidelines](docker-guidelines.md)** - Complete service management guide
|
||||
- **[Service Creation](docker-guidelines.md#service-creation-guidelines)** - How to add new services
|
||||
- **[Service Modification](docker-guidelines.md#service-modification-guidelines)** - Updating existing services
|
||||
- **[Resource Limits](resource-limits-template.md)** - CPU/memory management
|
||||
- **[Troubleshooting](docker-guidelines.md#troubleshooting)** - Common issues & fixes
|
||||
|
||||
#### External Service Integration
|
||||
- **[Proxying External Hosts](proxying-external-hosts.md)** - Route non-Docker services through Traefik
|
||||
- **[External Host Examples](proxying-external-hosts.md#common-external-services-to-proxy)** - Raspberry Pi, NAS, etc.
|
||||
|
||||
#### AI & Automation
|
||||
- **[Copilot Instructions](.github/copilot-instructions.md)** - AI agent guidelines for this codebase
|
||||
- **[AI Management Capabilities](.github/copilot-instructions.md#ai-management-capabilities)** - What the AI can help with
|
||||
|
||||
### 📋 Quick References
|
||||
|
||||
#### Commands & Operations
|
||||
- **[Quick Reference](quick-reference.md)** - Essential commands and workflows
|
||||
- **[Stack Management](quick-reference.md#service-management)** - Start/stop/restart services
|
||||
- **[Deployment Scripts](quick-reference.md#deployment-scripts)** - Setup and deployment automation
|
||||
|
||||
#### Troubleshooting
|
||||
- **[Common Issues](quick-reference.md#troubleshooting)** - SSL, networking, permissions
|
||||
- **[Service Won't Start](quick-reference.md#service-wont-start)** - Debugging steps
|
||||
- **[Traefik Routing](quick-reference.md#traefik-not-routing)** - Route configuration issues
|
||||
- **[VPN Problems](quick-reference.md#vpn-not-working-gluetun)** - Gluetun troubleshooting
|
||||
|
||||
### 📖 Advanced Topics
|
||||
|
||||
#### SSL & Certificates
|
||||
- **[Wildcard SSL Setup](getting-started.md#notes-about-ssl-certificates-from-letsencrypt-with-duckdns)** - How SSL certificates work
|
||||
- **[Certificate Troubleshooting](getting-started.md#certificate-troubleshooting)** - SSL issues and fixes
|
||||
- **[DNS Challenge Process](getting-started.md#dns-challenge-process)** - How domain validation works
|
||||
|
||||
#### Security & Access Control
|
||||
- **[Authelia Configuration](service-docs/authelia.md)** - SSO setup and customization
|
||||
- **[Bypass Rules](docker-guidelines.md#when-to-use-authelia-sso)** - When to skip authentication
|
||||
- **[2FA Setup](getting-started.md#set-up-2fa-with-authelia)** - Two-factor authentication
|
||||
|
||||
#### Backup & Recovery
|
||||
- **[Backup Strategies](service-docs/duplicati.md)** - Data protection approaches
|
||||
- **[Service Backups](service-docs/backrest.md)** - Database backup solutions
|
||||
- **[Configuration Backup](quick-reference.md#backup-commands)** - Config file preservation
|
||||
|
||||
### 🔧 Development & Contributing
|
||||
|
||||
#### Repository Structure
|
||||
- **[File Organization](.github/copilot-instructions.md#file-structure-standards)** - How files are organized
|
||||
- **[Service Documentation](service-docs/)** - Individual service guides
|
||||
- **[Configuration Templates](config-templates/)** - Reusable configurations
|
||||
- **[Scripts](scripts/)** - Automation and deployment tools
|
||||
|
||||
#### Development Workflow
|
||||
- **[Adding Services](docker-guidelines.md#service-creation-guidelines)** - New service integration
|
||||
- **[Testing Changes](.github/copilot-instructions.md#testing-changes)** - Validation procedures
|
||||
- **[Resource Limits](resource-limits-template.md)** - Performance management
|
||||
|
||||
### 📚 Additional Resources
|
||||
|
||||
- **[GitHub Repository](https://github.com/kelinfoxy/AI-Homelab)** - Source code and issues
|
||||
- **[Docker Hub](https://hub.docker.com)** - Container images
|
||||
- **[Traefik Documentation](https://doc.traefik.io/traefik/)** - Official reverse proxy docs
|
||||
- **[Authelia Documentation](https://www.authelia.com/)** - SSO documentation
|
||||
- **[DuckDNS](https://www.duckdns.org/)** - Dynamic DNS service
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Navigation
|
||||
|
||||
**New to AI-Homelab?** → [Getting Started](getting-started.md)
|
||||
|
||||
**Need to add a service?** → [Service Creation Guide](docker-guidelines.md#service-creation-guidelines)
|
||||
|
||||
**Having issues?** → [Troubleshooting](quick-reference.md#troubleshooting)
|
||||
|
||||
**Want to contribute?** → [Development Workflow](docker-guidelines.md#service-creation-guidelines)
|
||||
|
||||
---
|
||||
|
||||
*This documentation is maintained by AI and community contributors. Last updated: January 20, 2026*
|
||||
196
docs/Restic-BackRest-Backup-Guide.md
Normal file
196
docs/Restic-BackRest-Backup-Guide.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# Comprehensive Backup Guide: Restic + Backrest
|
||||
|
||||
This guide covers your configured setup with **Restic** (the backup engine) and **Backrest** (the web UI for managing Restic). It includes current info (as of January 2026), configurations, examples, and best practices. Your setup backs up Docker volumes, service configs, and databases with automated stop/start hooks.
|
||||
|
||||
## Overview
|
||||
|
||||
### What is Restic?
|
||||
Restic (latest: v0.18.1) is a modern, open-source backup program written in Go. It provides:
|
||||
- **Deduplication**: Efficiently stores only changed data.
|
||||
- **Encryption**: All data is encrypted with AES-256.
|
||||
- **Snapshots**: Point-in-time backups with metadata.
|
||||
- **Cross-Platform**: Works on Linux, macOS, Windows.
|
||||
- **Backends**: Supports local, SFTP, S3, etc.
|
||||
- **Features**: Compression, locking, pruning, mounting snapshots.
|
||||
|
||||
Restic is command-line based; Backrest provides a web UI.
|
||||
|
||||
### What is Backrest?
|
||||
Backrest (latest: v1.10.1) is a web-based UI for Restic, built with Go and SvelteKit. It simplifies Restic management:
|
||||
- **Web Interface**: Create repos, plans, and monitor backups.
|
||||
- **Automation**: Scheduled backups, hooks (pre/post commands).
|
||||
- **Integration**: Runs Restic under the hood.
|
||||
- **Features**: Multi-repo support, retention policies, notifications.
|
||||
|
||||
Your Backrest instance is containerized, with access to Docker volumes and host paths.
|
||||
|
||||
## Your Current Setup
|
||||
|
||||
### Backrest Configuration
|
||||
- **Container**: `garethgeorge/backrest:latest` on port 9898.
|
||||
- **Mounts**:
|
||||
- `/var/lib/docker/volumes:/docker_volumes` (all Docker volumes).
|
||||
- `/opt/stacks:/opt/stacks` (service configs and data).
|
||||
- `/var/run/docker.sock` (for Docker commands in hooks).
|
||||
- **Environment**:
|
||||
- `BACKREST_DATA=/data` (internal data).
|
||||
- `BACKREST_CONFIG=/config/config.json` (plans/repos).
|
||||
- `BACKREST_UI_CONFIG={"baseURL": "https://backrest.kelin-casa.duckdns.org"}` (UI base URL).
|
||||
- **Repos**: `jarvis-restic-repo` (your main repo).
|
||||
- **Plans**:
|
||||
- **jarvis-database-backup**: Backs up `_mysql` volumes with DB stop/start hooks.
|
||||
- **Other Plans**: For volumes/configs (e.g., individual paths like `/docker_volumes/gitea_data/_data`).
|
||||
|
||||
### Key Features in Use
|
||||
- **Hooks**: Pre-backup stops DBs, post-backup starts them.
|
||||
- **Retention**: Keep last 30 snapshots.
|
||||
- **Schedule**: Daily backups.
|
||||
- **Paths**: Selective (e.g., DB volumes, service data).
|
||||
|
||||
## Step-by-Step Guide
|
||||
|
||||
### 1. Accessing Backrest
|
||||
- URL: `https://backrest.kelin-casa.duckdns.org`
|
||||
- Auth: Via Authelia (as configured in NPM).
|
||||
- UI Sections: Repos, Plans, Logs.
|
||||
|
||||
### 2. Managing Repos
|
||||
Repos store backups. Yours is `jarvis-restic-repo`.
|
||||
|
||||
#### Create a New Repo
|
||||
1. Go to **Repos** > **Add Repo**.
|
||||
2. **Name**: `my-new-repo`.
|
||||
3. **Storage**: Choose backend (e.g., Local: `/data/repos/my-new-repo`).
|
||||
4. **Password**: Set a strong password (Restic encrypts with this).
|
||||
5. **Initialize**: Backrest runs `restic init`.
|
||||
|
||||
#### Example Config (JSON)
|
||||
```json
|
||||
{
|
||||
"id": "jarvis-restic-repo",
|
||||
"uri": "/repos/jarvis-restic-repo",
|
||||
"password": "your-secure-password",
|
||||
"env": {},
|
||||
"flags": []
|
||||
}
|
||||
```
|
||||
|
||||
#### Best Practices
|
||||
- Use strong passwords.
|
||||
- For remote: Use SFTP/S3 for offsite backups.
|
||||
- Test access: `restic list snapshots --repo /repos/repo-name`.
|
||||
|
||||
### 3. Creating Backup Plans
|
||||
Plans define what/when/how to back up.
|
||||
|
||||
#### Your DB Plan Example
|
||||
```json
|
||||
{
|
||||
"id": "jarvis-database-backup",
|
||||
"repo": "jarvis-restic-repo",
|
||||
"paths": [
|
||||
"/docker_volumes/bookstack_mysql/_data",
|
||||
"/docker_volumes/gitea_mysql/_data",
|
||||
"/docker_volumes/mediawiki_mysql/_data",
|
||||
"/docker_volumes/nextcloud_mysql/_data",
|
||||
"/docker_volumes/formio_mysql/_data"
|
||||
],
|
||||
"excludes": [],
|
||||
"iexcludes": [],
|
||||
"schedule": {
|
||||
"clock": "CLOCK_LOCAL",
|
||||
"maxFrequencyDays": 1
|
||||
},
|
||||
"backup_flags": [],
|
||||
"hooks": [
|
||||
{
|
||||
"actionCommand": {
|
||||
"command": "for vol in $(docker volume ls -q | grep '_mysql$'); do docker ps -q --filter volume=$vol | xargs -r docker stop || true; done"
|
||||
},
|
||||
"conditions": ["CONDITION_SNAPSHOT_START"],
|
||||
"onError": "ON_ERROR_CANCEL"
|
||||
},
|
||||
{
|
||||
"actionCommand": {
|
||||
"command": "for vol in $(docker volume ls -q | grep '_mysql$'); do docker ps -a -q --filter volume=$vol | xargs -r docker start || true; done"
|
||||
},
|
||||
"conditions": ["CONDITION_SNAPSHOT_END"],
|
||||
"onError": "ON_ERROR_RETRY_1MINUTE"
|
||||
}
|
||||
],
|
||||
"retention": {
|
||||
"policyKeepLastN": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Create a New Plan
|
||||
1. Go to **Plans** > **Add Plan**.
|
||||
2. **Repo**: Select `jarvis-restic-repo`.
|
||||
3. **Paths**: Add directories (e.g., `/opt/stacks/homepage/config`).
|
||||
4. **Schedule**: Set frequency (e.g., daily).
|
||||
5. **Hooks**: Add pre/post commands (e.g., for non-DB backups).
|
||||
6. **Retention**: Keep last N snapshots.
|
||||
7. **Save & Run**: Test with **Run Backup Now**.
|
||||
|
||||
#### Example: Volume Backup Plan
|
||||
```json
|
||||
{
|
||||
"id": "volumes-backup",
|
||||
"repo": "jarvis-restic-repo",
|
||||
"paths": [
|
||||
"/docker_volumes/gitea_data/_data",
|
||||
"/docker_volumes/nextcloud_html/_data"
|
||||
],
|
||||
"schedule": {"maxFrequencyDays": 1},
|
||||
"retention": {"policyKeepLastN": 14}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Running & Monitoring Backups
|
||||
- **Manual**: Plans > Select plan > **Run Backup**.
|
||||
- **Scheduled**: Runs automatically per schedule.
|
||||
- **Logs**: Check **Logs** tab for output/errors.
|
||||
- **Status**: View snapshots in repo details.
|
||||
|
||||
#### Restic Commands (via Backrest)
|
||||
Backrest runs Restic under the hood. Examples:
|
||||
- Backup: `restic backup /path --repo /repo`
|
||||
- List: `restic snapshots --repo /repo`
|
||||
- Restore: `restic restore latest --repo /repo --target /restore/path`
|
||||
- Prune: `restic forget --keep-last 30 --repo /repo`
|
||||
|
||||
### 5. Restoring Data
|
||||
1. Go to **Repos** > Select repo > **Snapshots**.
|
||||
2. Choose snapshot > **Restore**.
|
||||
3. Select paths/files > Target directory.
|
||||
4. Run restore.
|
||||
|
||||
#### Example Restore Command
|
||||
```bash
|
||||
restic restore latest --repo /repos/jarvis-restic-repo --target /tmp/restore --path /docker_volumes/bookstack_mysql/_data
|
||||
```
|
||||
|
||||
### 6. Advanced Features
|
||||
- **Excludes**: Add glob patterns (e.g., `*.log`) to skip files.
|
||||
- **Compression**: Enable in backup flags: `--compression max`.
|
||||
- **Notifications**: Configure webhooks in Backrest settings.
|
||||
- **Mounting**: `restic mount /repo /mnt/backup` to browse snapshots.
|
||||
- **Forget/Prune**: Auto-managed via retention, or manual: `restic forget --keep-daily 7 --repo /repo`.
|
||||
|
||||
### 7. Best Practices
|
||||
- **Security**: Use strong repo passwords. Limit Backrest access.
|
||||
- **Testing**: Regularly test restores.
|
||||
- **Retention**: Balance storage (e.g., keep 30 daily).
|
||||
- **Monitoring**: Check logs for failures.
|
||||
- **Offsite**: Add a remote repo for disaster recovery.
|
||||
- **Performance**: Schedule during low-usage times.
|
||||
- **Updates**: Keep Restic/Backrest updated (current versions noted).
|
||||
|
||||
### 8. Troubleshooting
|
||||
- **Hook Failures**: Check Docker socket access; ensure CLI installed.
|
||||
- **Permissions**: Bind mounts may need `chown` to match container user.
|
||||
- **Space**: Monitor repo size; prune old snapshots.
|
||||
- **Errors**: Logs show Restic output; search for "exit status" codes.
|
||||
|
||||
This covers your setup. For more, visit [Restic Docs](https://restic.net/) and [Backrest GitHub](https://github.com/garethgeorge/backrest). Let me know if you need help with specific configs!
|
||||
60
docs/core-stack-readme.md
Normal file
60
docs/core-stack-readme.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Core Stack
|
||||
|
||||
## The core stack contains the critical infrastructure for a homelab.
|
||||
|
||||
>There are always other options.
|
||||
I chose these for easy of use and file based configuration (so AI can do it all)
|
||||
|
||||
>For a multi server homelab, only install core services on one server.
|
||||
|
||||
* DuckDNS with LetsEncrypt- Free subdomains and wildcard SSL Certificates
|
||||
* Authelia - Single Sign On (SSO) Authentication with optional 2 Factor Authentication
|
||||
* Traefik - Proxy Host Routing to access your services through your duckdns url
|
||||
* Sablier - Both a container and a Traefik plugin, enables ondemand services (saving resources and power)
|
||||
|
||||
## DuckDNS with LetsEncrypt
|
||||
|
||||
Get your free subdomain at http://www.duckdns.org
|
||||
|
||||
>Copy your DuckDNS Token, you'll need to add that to the .env file
|
||||
|
||||
DuckDNS service will keep your subdomain pointing to your IP address, even if it changes.
|
||||
|
||||
LetsEncrypt service will generate 2 certificates, one for your duckdns subdomain, and one wildcard for the same domain.
|
||||
The wildcard certificate is used by all the services. No need for an individual certificate per service.
|
||||
|
||||
Certificates will auto renew. This is a set it and forget service, no webui, no changes needed when adding a new service.
|
||||
|
||||
>It can take 2-5 minutes for the certificates to be generated and applied. Until then it will use a self signed certificate. You just need to accept the browser warnings. Once it's applied the browser warnings will go away.
|
||||
|
||||
## Authelia
|
||||
|
||||
Provides Single Sign On (SSO) Authentication for your services.
|
||||
|
||||
>Some services you may not want behind SSO, like Jellyfin/Plex if you watch your media through an app on a smart TV, firestick or phone.
|
||||
|
||||
* Optional 2 Factor Authentication
|
||||
* Easy to enable/disable - Comment out 1 line in the compose file then bring the stack down and back up to disable (not restart)
|
||||
* Configured on a per service basis
|
||||
* A public service (like wordpress) can bypass authelia login and let the service handle it's own authentication
|
||||
* Admin services (like dockge/portainer) can use 2 Factor Authorization for an extra layer of security
|
||||
|
||||
## Traefik
|
||||
|
||||
Provides proxy routing for your services so you can access them at a url like wordpress.my-subdoain.duckdns.org
|
||||
|
||||
For services on a Remote Host, create a file in the traefik/dynamic folder like my-server-external-host.yml
|
||||
Create 1 file per remote host.
|
||||
|
||||
## Sablier
|
||||
|
||||
Provides ondemand container management (start/pause/stop)
|
||||
|
||||
>Important: The stack must be up and the service stopped for Sablier to work.
|
||||
Tip: If you have a lot of services, use a script to get the services to that state.
|
||||
|
||||
If a service is down and anything requests the url for that service, Sablier will start the service and redirect after a short delay (however long it takes the service to come up), usually less than 20 seconds.
|
||||
|
||||
Once the set inactivity period has elapsed, Sablier will pause or stop the container according to the settings.
|
||||
|
||||
This saves resources and electricity. Allowing you have more services installed, configured, and ready to use even if the server is incapable of running all the services simultaniously. Great for single board computers, mini PCs, low resource systems, and your power bill.
|
||||
@@ -100,7 +100,7 @@ AI will suggest `/mnt/` when data may exceed 50GB or grow continuously.
|
||||
|
||||
## Traefik and Authelia Integration
|
||||
|
||||
### Every Service Needs Traefik Labels
|
||||
### Every Local (on the same server) Service Needs Traefik Labels
|
||||
|
||||
Standard pattern for all services:
|
||||
|
||||
@@ -125,13 +125,25 @@ services:
|
||||
# Enable Let's Encrypt
|
||||
- "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
|
||||
|
||||
# Add Authelia SSO (if needed)
|
||||
# Add Authelia SSO (if needed) - comment out to disable SSO
|
||||
- "traefik.http.routers.myservice.middlewares=authelia@docker"
|
||||
|
||||
# Specify port (if not default 80)
|
||||
- "traefik.http.services.myservice.loadbalancer.server.port=8080"
|
||||
|
||||
# Optional: Sablier lazy loading (comment out to disable)
|
||||
# - "sablier.enable=true"
|
||||
# - "sablier.group=core-myservice"
|
||||
# - "sablier.start-on-demand=true"
|
||||
```
|
||||
|
||||
### If Traefik is on a Remote Server, configure routes & services on the Remote Server
|
||||
|
||||
Add a yaml file to the traefik/dynamic folder for each remote server
|
||||
|
||||
Add a section under routers: and a section on services: for each service
|
||||
|
||||
|
||||
### When to Use Authelia SSO
|
||||
|
||||
**Protect with Authelia**:
|
||||
@@ -414,6 +426,46 @@ mv docker-compose/service.yml.backup docker-compose/service.yml
|
||||
docker compose -f docker-compose/service.yml up -d
|
||||
```
|
||||
|
||||
### Common Modifications
|
||||
|
||||
**Toggle SSO**: Comment/uncomment the Authelia middleware label:
|
||||
```yaml
|
||||
# Enable SSO
|
||||
- "traefik.http.routers.service.middlewares=authelia@docker"
|
||||
|
||||
# Disable SSO (comment out)
|
||||
# - "traefik.http.routers.service.middlewares=authelia@docker"
|
||||
```
|
||||
|
||||
**Toggle Lazy Loading**: Comment/uncomment Sablier labels:
|
||||
```yaml
|
||||
# Enable lazy loading
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=core-service"
|
||||
- "sablier.start-on-demand=true"
|
||||
|
||||
# Disable lazy loading (comment out)
|
||||
# - "sablier.enable=true"
|
||||
# - "sablier.group=core-service"
|
||||
# - "sablier.start-on-demand=true"
|
||||
```
|
||||
|
||||
**Change Port**: Update the loadbalancer server port:
|
||||
```yaml
|
||||
- "traefik.http.services.service.loadbalancer.server.port=8080"
|
||||
```
|
||||
|
||||
**Add VPN Routing**: Change network mode and update Gluetun ports:
|
||||
```yaml
|
||||
network_mode: "service:gluetun"
|
||||
# Add port mapping in Gluetun service
|
||||
```
|
||||
|
||||
**Update Subdomain**: Modify the Host rule:
|
||||
```yaml
|
||||
- "traefik.http.routers.service.rule=Host(`newservice.${DOMAIN}`)"
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Service Names
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
# Getting Started Guide
|
||||
|
||||
Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 60+ services.
|
||||
Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 70+ services.
|
||||
|
||||
## Getting Started Checklist
|
||||
- [ ] Clone this repository to your home folder
|
||||
- [ ] Configure `.env` file with your domain and tokens
|
||||
- [ ] Run setup script (generates Authelia secrets and admin user)
|
||||
- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](#prerequisites))
|
||||
- [ ] Run setup script (generates Authelia secrets and admin user) ([setup-homelab.sh](../scripts/setup-homelab.sh))
|
||||
- [ ] Log out and back in for Docker group permissions
|
||||
- [ ] Run deployment script (deploys all core, infrastructure & dashboard services)
|
||||
- [ ] Access Dockge web UI
|
||||
- [ ] Set up 2FA with Authelia
|
||||
- [ ] (optional) Deploy additional stacks as needed via Dockge
|
||||
- [ ] Configure and use VS Code with Github Copilot to manage the server
|
||||
- [ ] Run deployment script (deploys all core, infrastructure & dashboard services) ([deploy-homelab.sh](../scripts/deploy-homelab.sh))
|
||||
- [ ] Access Dockge web UI ([https://dockge.yourdomain.duckdns.org](https://dockge.yourdomain.duckdns.org))
|
||||
- [ ] Set up 2FA with Authelia ([Authelia setup guide](service-docs/authelia.md))
|
||||
- [ ] (optional) Deploy additional stacks as needed via Dockge ([services overview](services-overview.md))
|
||||
- [ ] Configure and use VS Code with Github Copilot to manage the server ([AI management](.github/copilot-instructions.md))
|
||||
|
||||
## Quick Setup (Recommended)
|
||||
|
||||
@@ -35,7 +35,7 @@ For most users, the automated setup script handles everything:
|
||||
3. **Clone the rep**:
|
||||
```bash
|
||||
git clone https://github.com/kelinfoxy/AI-Homelab.git
|
||||
cd AI-Homeb
|
||||
cd AI-Homelab
|
||||
4. **Configure environment**:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
@@ -363,7 +363,7 @@ docker compose up -d --build service-name
|
||||
## Next Steps
|
||||
|
||||
1. **Explore services** through Dockge
|
||||
2. **Configure backups** with Backrest/Duplicati
|
||||
2. **Set up backups** with Backrest (default Restic-based solution)
|
||||
3. **Set up monitoring** with Grafana/Prometheus
|
||||
4. **Add external services** via Traefik proxying
|
||||
5. **Use AI assistance** for custom configurations
|
||||
|
||||
@@ -29,6 +29,7 @@ For detailed information about the deployment scripts, their features, and usage
|
||||
- `setup-homelab.sh` - First-run system setup and Authelia configuration
|
||||
- `deploy-homelab.sh` - Deploy all core services and prepare additional stacks
|
||||
- `reset-test-environment.sh` - Testing/development only - removes all deployed services
|
||||
- `reset-ondemand-services.sh` - Reload services for Sablier lazy loading
|
||||
|
||||
## Common Commands
|
||||
|
||||
@@ -182,6 +183,7 @@ docker image prune -a
|
||||
### Core Infrastructure (core.yml)
|
||||
- **80/443**: Traefik (reverse proxy)
|
||||
- **8080**: Traefik dashboard
|
||||
- **10000**: Sablier (lazy loading service)
|
||||
|
||||
### Infrastructure Services (infrastructure.yml)
|
||||
- **5001**: Dockge (stack manager)
|
||||
@@ -304,16 +306,17 @@ After deployment, access services at:
|
||||
Core Infrastructure:
|
||||
https://traefik.${DOMAIN} - Traefik dashboard
|
||||
https://auth.${DOMAIN} - Authelia login
|
||||
http://sablier.${DOMAIN}:10000 - Sablier lazy loading (internal)
|
||||
|
||||
Infrastructure:
|
||||
https://dockge.${DOMAIN} - Stack manager (PRIMARY)
|
||||
https://portainer.${DOMAIN} - Docker UI (secondary)
|
||||
http://${SERVER_IP}:8082 - Pi-hole admin
|
||||
http://pihole.${DOMAIN} - Pi-hole admin
|
||||
https://dozzle.${DOMAIN} - Log viewer
|
||||
https://glances.${DOMAIN} - System monitor
|
||||
|
||||
Dashboards:
|
||||
https://home.${DOMAIN} - Homepage dashboard
|
||||
https://homepage.${DOMAIN} - Homepage dashboard
|
||||
https://homarr.${DOMAIN} - Homarr dashboard
|
||||
|
||||
Media:
|
||||
@@ -322,17 +325,19 @@ https://jellyfin.${DOMAIN} - Jellyfin (no auth)
|
||||
https://sonarr.${DOMAIN} - TV automation
|
||||
https://radarr.${DOMAIN} - Movie automation
|
||||
https://prowlarr.${DOMAIN} - Indexer manager
|
||||
https://qbit.${DOMAIN} - Torrent client
|
||||
https://torrents.${DOMAIN} - Torrent client
|
||||
|
||||
Productivity:
|
||||
https://nextcloud.${DOMAIN} - File sync
|
||||
https://git.${DOMAIN} - Git service
|
||||
https://docs.${DOMAIN} - Documentation
|
||||
https://nextcloud.${DOMAIN} - Cloud Storage
|
||||
https://gitea.${DOMAIN} - Gitea
|
||||
|
||||
Monitoring:
|
||||
https://grafana.${DOMAIN} - Metrics dashboard
|
||||
https://prometheus.${DOMAIN} - Metrics collection
|
||||
https://status.${DOMAIN} - Uptime monitoring
|
||||
|
||||
Utilities:
|
||||
https://backrest.${DOMAIN} - Backup management (Restic)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -588,3 +588,15 @@ Authelia is your homelab's security layer. It:
|
||||
- Integrates seamlessly with Traefik
|
||||
|
||||
Setting up Authelia properly is one of the most important security steps for your homelab. Take time to understand access control rules and test your configuration thoroughly. Always keep the `users_database.yml` and `db.sqlite3` backed up, as they contain critical authentication data.
|
||||
|
||||
## Related Services
|
||||
|
||||
- **[Traefik](traefik.md)** - Reverse proxy that integrates with Authelia for authentication
|
||||
- **[DuckDNS](duckdns.md)** - Dynamic DNS required for SSL certificates
|
||||
- **[Sablier](sablier.md)** - Lazy loading that can work with Authelia-protected services
|
||||
|
||||
## See Also
|
||||
|
||||
- **[SSO Bypass Guide](../docker-guidelines.md#when-to-use-authelia-sso)** - When to disable authentication for services
|
||||
- **[2FA Setup](../getting-started.md#set-up-2fa-with-authelia)** - Enable two-factor authentication
|
||||
- **[Access Control Rules](../docker-guidelines.md#authelia-bypass-example-jellyfin)** - Configure bypass rules for specific services
|
||||
|
||||
@@ -1,151 +1,244 @@
|
||||
# Backrest - Backup Solution
|
||||
# Backrest - Comprehensive Backup Solution
|
||||
|
||||
## Table of Contents
|
||||
- [Overview](#overview)
|
||||
- [What is Backrest?](#what-is-backrest)
|
||||
- [Why Use Backrest?](#why-use-backrest)
|
||||
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
|
||||
- [Official Resources](#official-resources)
|
||||
- [Docker Configuration](#docker-configuration)
|
||||
**Category:** Backup & Recovery
|
||||
|
||||
**Description:** Backrest is a web-based UI for Restic, providing scheduled backups, retention policies, and a beautiful interface for managing backups across multiple repositories and destinations. It serves as the default backup strategy for AI-Homelab.
|
||||
|
||||
**Docker Image:** `garethgeorge/backrest:latest`
|
||||
|
||||
**Documentation:** [Backrest GitHub](https://github.com/garethgeorge/backrest)
|
||||
|
||||
## Overview
|
||||
|
||||
**Category:** Backup & Recovery
|
||||
**Docker Image:** [garethgeorge/backrest](https://hub.docker.com/r/garethgeorge/backrest)
|
||||
**Default Stack:** `utilities.yml`
|
||||
**Web UI:** `http://SERVER_IP:9898`
|
||||
**Backend:** Restic
|
||||
**Ports:** 9898
|
||||
### What is Backrest?
|
||||
Backrest (latest: v1.10.1) is a web-based UI for Restic, built with Go and SvelteKit. It simplifies Restic management:
|
||||
- **Web Interface**: Create repos, plans, and monitor backups.
|
||||
- **Automation**: Scheduled backups, hooks (pre/post commands).
|
||||
- **Integration**: Runs Restic under the hood.
|
||||
- **Features**: Multi-repo support, retention policies, notifications.
|
||||
|
||||
## What is Backrest?
|
||||
### What is Restic?
|
||||
Restic (latest: v0.18.1) is a modern, open-source backup program written in Go. It provides:
|
||||
- **Deduplication**: Efficiently stores only changed data.
|
||||
- **Encryption**: All data is encrypted with AES-256.
|
||||
- **Snapshots**: Point-in-time backups with metadata.
|
||||
- **Cross-Platform**: Works on Linux, macOS, Windows.
|
||||
- **Backends**: Supports local, SFTP, S3, etc.
|
||||
- **Features**: Compression, locking, pruning, mounting snapshots.
|
||||
|
||||
Backrest is a web UI and orchestration layer for Restic, a powerful backup tool. It provides scheduled backups, retention policies, and a beautiful interface for managing backups across multiple repositories and destinations. Think of it as a user-friendly wrapper around Restic's power.
|
||||
## Configuration
|
||||
|
||||
### Key Features
|
||||
- **Web Interface:** Manage backups visually
|
||||
- **Multiple Repos:** Backup to different locations
|
||||
- **Schedules:** Cron-based automatic backups
|
||||
- **Retention Policies:** Keep last N backups
|
||||
- **Compression:** Automatic compression
|
||||
- **Deduplication:** Save storage space
|
||||
- **Encryption:** AES-256 encryption
|
||||
- **Destinations:** Local, S3, B2, SFTP, WebDAV
|
||||
- **Notifications:** Alerts on failure
|
||||
- **Browse & Restore:** Visual file restoration
|
||||
### Environment Variables
|
||||
|
||||
## Why Use Backrest?
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `BACKREST_DATA` | Internal data directory | `/data` |
|
||||
| `BACKREST_CONFIG` | Configuration file path | `/config/config.json` |
|
||||
| `BACKREST_UI_CONFIG` | UI configuration JSON | `{"baseURL": "https://backrest.${DOMAIN}"}` |
|
||||
|
||||
1. **Easy Backups:** Simple web interface
|
||||
2. **Restic Power:** Proven backup engine
|
||||
3. **Automated:** Set and forget
|
||||
4. **Multiple Destinations:** Flexibility
|
||||
5. **Encrypted:** Secure backups
|
||||
6. **Deduplicated:** Efficient storage
|
||||
7. **Free & Open Source:** No cost
|
||||
### Ports
|
||||
|
||||
## Configuration in AI-Homelab
|
||||
- **9898** - Web UI port
|
||||
|
||||
```
|
||||
/opt/stacks/utilities/backrest/data/ # Backrest config
|
||||
/opt/stacks/utilities/backrest/cache/ # Restic cache
|
||||
### Volumes
|
||||
|
||||
- `./data:/data` - Backrest internal data and repositories
|
||||
- `./config:/config` - Configuration files
|
||||
- `./cache:/cache` - Restic cache for performance
|
||||
- `/var/lib/docker/volumes:/docker_volumes:ro` - Access to Docker volumes
|
||||
- `/opt/stacks:/opt/stacks:ro` - Access to service configurations
|
||||
- `/var/run/docker.sock:/var/run/docker.sock` - Docker API access for hooks
|
||||
|
||||
## Usage
|
||||
|
||||
### Accessing Backrest
|
||||
- **URL**: `https://backrest.${DOMAIN}`
|
||||
- **Authentication**: Via Authelia SSO
|
||||
- **UI Sections**: Repos, Plans, Logs
|
||||
|
||||
### Managing Repositories
|
||||
Repositories store your backups. Create one for your main backup location.
|
||||
|
||||
#### Create Repository
|
||||
1. Go to **Repos** → **Add Repo**
|
||||
2. **Name**: `main-backup-repo`
|
||||
3. **Storage**: Choose backend (Local, SFTP, S3, etc.)
|
||||
4. **Password**: Set strong encryption password
|
||||
5. **Initialize**: Backrest runs `restic init`
|
||||
|
||||
### Creating Backup Plans
|
||||
Plans define what, when, and how to back up.
|
||||
|
||||
#### Database Backup Plan (Recommended)
|
||||
```json
|
||||
{
|
||||
"id": "database-backup",
|
||||
"repo": "main-backup-repo",
|
||||
"paths": [
|
||||
"/docker_volumes/*_mysql/_data",
|
||||
"/docker_volumes/*_postgres/_data"
|
||||
],
|
||||
"schedule": {
|
||||
"maxFrequencyDays": 1
|
||||
},
|
||||
"hooks": [
|
||||
{
|
||||
"actionCommand": {
|
||||
"command": "for vol in $(docker volume ls -q | grep '_mysql$'); do docker ps -q --filter volume=$vol | xargs -r docker stop || true; done"
|
||||
},
|
||||
"conditions": ["CONDITION_SNAPSHOT_START"]
|
||||
},
|
||||
{
|
||||
"actionCommand": {
|
||||
"command": "for vol in $(docker volume ls -q | grep '_mysql$'); do docker ps -a -q --filter volume=$vol | xargs -r docker start || true; done"
|
||||
},
|
||||
"conditions": ["CONDITION_SNAPSHOT_END"]
|
||||
}
|
||||
],
|
||||
"retention": {
|
||||
"policyKeepLastN": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Official Resources
|
||||
#### Service Configuration Backup Plan
|
||||
```json
|
||||
{
|
||||
"id": "config-backup",
|
||||
"repo": "main-backup-repo",
|
||||
"paths": [
|
||||
"/opt/stacks"
|
||||
],
|
||||
"excludes": [
|
||||
"**/cache",
|
||||
"**/tmp",
|
||||
"**/log"
|
||||
],
|
||||
"schedule": {
|
||||
"maxFrequencyDays": 1
|
||||
},
|
||||
"retention": {
|
||||
"policyKeepLastN": 14
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **GitHub:** https://github.com/garethgeorge/backrest
|
||||
- **Restic:** https://restic.net
|
||||
### Running Backups
|
||||
- **Manual**: Plans → Select plan → **Run Backup Now**
|
||||
- **Scheduled**: Runs automatically per plan schedule
|
||||
- **Monitor**: Check **Logs** tab for status and errors
|
||||
|
||||
## Docker Configuration
|
||||
### Restoring Data
|
||||
1. Go to **Repos** → Select repo → **Snapshots**
|
||||
2. Choose snapshot → **Restore**
|
||||
3. Select paths/files → Set target directory
|
||||
4. Run restore operation
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security
|
||||
- Use strong repository passwords
|
||||
- Limit Backrest UI access via Authelia
|
||||
- Store passwords securely (not in config files)
|
||||
|
||||
### Performance
|
||||
- Schedule backups during low-usage hours
|
||||
- Use compression for large backups
|
||||
- Monitor repository size growth
|
||||
|
||||
### Retention
|
||||
- Keep 30 daily snapshots for critical data
|
||||
- Keep 14 snapshots for configurations
|
||||
- Regularly prune old snapshots
|
||||
|
||||
### Testing
|
||||
- Test restore procedures regularly
|
||||
- Verify backup integrity
|
||||
- Document restore processes
|
||||
|
||||
## Integration with AI-Homelab
|
||||
|
||||
### Homepage Dashboard
|
||||
Add Backrest to your Homepage dashboard:
|
||||
|
||||
```yaml
|
||||
backrest:
|
||||
image: garethgeorge/backrest:latest
|
||||
container_name: backrest
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- traefik-network
|
||||
ports:
|
||||
- "9898:9898"
|
||||
environment:
|
||||
- BACKREST_DATA=/data
|
||||
- BACKREST_CONFIG=/config/config.json
|
||||
- XDG_CACHE_HOME=/cache
|
||||
volumes:
|
||||
- /opt/stacks/utilities/backrest/data:/data
|
||||
- /opt/stacks/utilities/backrest/config:/config
|
||||
- /opt/stacks/utilities/backrest/cache:/cache
|
||||
- /opt/stacks:/backup-source:ro # What to backup
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.backrest.rule=Host(`backrest.${DOMAIN}`)"
|
||||
# In homepage/services.yaml
|
||||
- Infrastructure:
|
||||
- Backrest:
|
||||
icon: backup.png
|
||||
href: https://backrest.${DOMAIN}
|
||||
description: Backup management
|
||||
widget:
|
||||
type: iframe
|
||||
url: https://backrest.${DOMAIN}
|
||||
```
|
||||
|
||||
## Setup
|
||||
### Monitoring
|
||||
Monitor backup success with Uptime Kuma or Grafana alerts.
|
||||
|
||||
1. **Start Container:**
|
||||
```bash
|
||||
docker compose up -d backrest
|
||||
```
|
||||
## Troubleshooting
|
||||
|
||||
2. **Access UI:** `http://SERVER_IP:9898`
|
||||
### Common Issues
|
||||
|
||||
3. **Create Repository:**
|
||||
- Add Repository
|
||||
- Location: Local, S3, B2, etc.
|
||||
- Encryption password
|
||||
- Initialize repository
|
||||
**Backup Failures**
|
||||
- Check repository access and credentials
|
||||
- Verify source paths exist and are readable
|
||||
- Review hook commands for syntax errors
|
||||
|
||||
4. **Create Plan:**
|
||||
- Add backup plan
|
||||
- Source: `/backup-source` (mounted volume)
|
||||
- Repository: Select created repo
|
||||
- Schedule: `0 2 * * *` (2 AM daily)
|
||||
- Retention: Keep last 7 daily, 4 weekly, 12 monthly
|
||||
**Hook Issues**
|
||||
- Ensure Docker socket is accessible
|
||||
- Check that containers can be stopped/started
|
||||
- Verify hook commands work manually
|
||||
|
||||
5. **Run Backup:**
|
||||
- Manual: Click "Backup Now"
|
||||
- Or wait for schedule
|
||||
**Performance Problems**
|
||||
- Check available disk space
|
||||
- Monitor CPU/memory usage during backups
|
||||
- Consider excluding large, frequently changing files
|
||||
|
||||
6. **Restore:**
|
||||
- Browse backups
|
||||
- Select snapshot
|
||||
- Browse files
|
||||
- Restore to location
|
||||
**Restore Issues**
|
||||
- Ensure target directory exists and is writable
|
||||
- Check file permissions
|
||||
- Verify snapshot integrity
|
||||
|
||||
## Summary
|
||||
## Advanced Features
|
||||
|
||||
Backrest provides web-based backup management offering:
|
||||
- Visual Restic interface
|
||||
- Scheduled automated backups
|
||||
- Multiple backup destinations
|
||||
- Retention policies
|
||||
- Encryption and deduplication
|
||||
- Easy restore
|
||||
- Free and open-source
|
||||
### Multiple Repositories
|
||||
- **Local**: For fast, local backups
|
||||
- **Remote**: SFTP/S3 for offsite storage
|
||||
- **Hybrid**: Local for speed, remote for safety
|
||||
|
||||
**Perfect for:**
|
||||
- Homelab backups
|
||||
- Docker volume backups
|
||||
- Off-site backup management
|
||||
- Automated backup schedules
|
||||
- Visual backup management
|
||||
### Custom Hooks
|
||||
```bash
|
||||
# Pre-backup: Stop services
|
||||
docker compose -f /opt/stacks/core/docker-compose.yml stop
|
||||
|
||||
**Key Points:**
|
||||
- Built on Restic
|
||||
- Web interface
|
||||
- Supports many backends
|
||||
- Encryption by default
|
||||
- Deduplication saves space
|
||||
- Cron-based scheduling
|
||||
- Easy restore interface
|
||||
# Post-backup: Start services
|
||||
docker compose -f /opt/stacks/core/docker-compose.yml start
|
||||
```
|
||||
|
||||
**Remember:**
|
||||
- Mount volumes to backup
|
||||
- Set retention policies
|
||||
- Test restores regularly
|
||||
- Off-site backup recommended
|
||||
- Keep repository password safe
|
||||
- Monitor backup success
|
||||
- Schedule during low usage
|
||||
### Notifications
|
||||
Configure webhooks in Backrest settings for backup status alerts.
|
||||
|
||||
Backrest makes Restic backups manageable!
|
||||
## Migration from Other Solutions
|
||||
|
||||
### From Duplicati
|
||||
1. Export Duplicati configurations
|
||||
2. Create equivalent Backrest plans
|
||||
3. Test backups and restores
|
||||
4. Decommission Duplicati
|
||||
|
||||
### From Manual Scripts
|
||||
1. Identify current backup sources and schedules
|
||||
2. Create Backrest plans with same parameters
|
||||
3. Add appropriate hooks for service management
|
||||
4. Test and validate
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[Backup Strategy Guide](../Restic-BackRest-Backup-Guide.md)** - Comprehensive setup and usage guide
|
||||
- **[Docker Guidelines](../docker-guidelines.md)** - Volume management and persistence
|
||||
- **[Quick Reference](../quick-reference.md)** - Command reference and troubleshooting
|
||||
|
||||
---
|
||||
|
||||
**Backrest provides enterprise-grade backup capabilities with an intuitive web interface, making it the perfect default backup solution for AI-Homelab.**
|
||||
|
||||
532
docs/service-docs/sablier.md
Normal file
532
docs/service-docs/sablier.md
Normal file
@@ -0,0 +1,532 @@
|
||||
# Sablier - Lazy Loading Service
|
||||
|
||||
## Table of Contents
|
||||
- [Overview](#overview)
|
||||
- [What is Sablier?](#what-is-sablier)
|
||||
- [Why Use Sablier?](#why-use-sablier)
|
||||
- [How It Works](#how-it-works)
|
||||
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
|
||||
- [Official Resources](#official-resources)
|
||||
- [Educational Resources](#educational-resources)
|
||||
- [Docker Configuration](#docker-configuration)
|
||||
- [Using Sablier](#using-sablier)
|
||||
- [Advanced Topics](#advanced-topics)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Overview
|
||||
|
||||
**Category:** Core Infrastructure
|
||||
**Docker Image:** [sablierapp/sablier](https://hub.docker.com/r/sablierapp/sablier)
|
||||
**Default Stack:** `core.yml`
|
||||
**Web UI:** No web UI (API only)
|
||||
**Authentication:** None required
|
||||
**Purpose:** On-demand container startup and resource management
|
||||
|
||||
## What is Sablier?
|
||||
|
||||
Sablier is a lightweight service that enables lazy loading for Docker containers. It automatically starts containers when they're accessed through Traefik and stops them after a period of inactivity, helping to conserve system resources and reduce power consumption.
|
||||
|
||||
### Key Features
|
||||
- **On-Demand Startup:** Containers start automatically when accessed
|
||||
- **Automatic Shutdown:** Containers stop after configurable inactivity periods
|
||||
- **Traefik Integration:** Works seamlessly with Traefik reverse proxy
|
||||
- **Resource Conservation:** Reduces memory and CPU usage for unused services
|
||||
- **Group Management:** Related services can be managed as groups
|
||||
- **Health Checks:** Waits for services to be ready before forwarding traffic
|
||||
- **Minimal Overhead:** Lightweight with low resource requirements
|
||||
|
||||
## Why Use Sablier?
|
||||
|
||||
1. **Resource Efficiency:** Save memory and CPU by only running services when needed
|
||||
2. **Power Savings:** Reduce power consumption on always-on systems
|
||||
3. **Faster Boot:** Services start quickly when accessed vs. waiting for full system startup
|
||||
4. **Scalability:** Handle more services than would fit in memory simultaneously
|
||||
5. **Cost Effective:** Lower resource requirements mean smaller/fewer servers needed
|
||||
6. **Environmental:** Reduce energy consumption and carbon footprint
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
User Request → Traefik → Sablier Check → Container Start → Health Check → Forward Traffic
|
||||
↓
|
||||
Container Stop (after timeout)
|
||||
```
|
||||
|
||||
When a request comes in for a service with Sablier enabled:
|
||||
|
||||
1. **Route Detection:** Sablier monitors Traefik routes for configured services
|
||||
2. **Container Check:** Verifies if the target container is running
|
||||
3. **Startup Process:** If not running, starts the container via Docker API
|
||||
4. **Health Verification:** Waits for the service to report healthy
|
||||
5. **Traffic Forwarding:** Routes traffic to the now-running service
|
||||
6. **Timeout Monitoring:** Tracks inactivity and stops containers after timeout
|
||||
|
||||
## Configuration in AI-Homelab
|
||||
|
||||
Sablier is deployed as part of the core infrastructure stack and requires no additional configuration for basic operation. It automatically discovers services with the appropriate labels.
|
||||
|
||||
### Service Integration
|
||||
|
||||
Add these labels to any service that should use lazy loading:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
myservice:
|
||||
# ... other configuration ...
|
||||
labels:
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=core-myservice" # Optional: group related services
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.myservice.rule=Host(`myservice.${DOMAIN}`)"
|
||||
# ... other Traefik labels ...
|
||||
```
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
For services requiring custom timeouts or group management:
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=media-services" # Group name for related services
|
||||
- "sablier.timeout=300" # 5 minutes inactivity timeout (default: 300)
|
||||
- "sablier.theme=dark" # Optional: theme for Sablier UI (if used)
|
||||
```
|
||||
|
||||
## Official Resources
|
||||
|
||||
- **GitHub Repository:** https://github.com/sablierapp/sablier
|
||||
- **Docker Hub:** https://hub.docker.com/r/sablierapp/sablier
|
||||
- **Documentation:** https://sablierapp.github.io/sablier/
|
||||
|
||||
## Educational Resources
|
||||
|
||||
- **Traefik Integration:** https://doc.traefik.io/traefik/middlewares/http/forwardauth/
|
||||
- **Docker Lazy Loading:** Search for "docker lazy loading" or "container on-demand"
|
||||
- **Resource Management:** Linux container resource management best practices
|
||||
|
||||
## Docker Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default | Required |
|
||||
|----------|-------------|---------|----------|
|
||||
| `SABLIER_PROVIDER` | Container runtime provider | `docker` | Yes |
|
||||
| `SABLIER_DOCKER_API_VERSION` | Docker API version | `1.53` | No |
|
||||
| `SABLIER_DOCKER_NETWORK` | Docker network for containers | `traefik-network` | Yes |
|
||||
| `SABLIER_LOG_LEVEL` | Logging level (debug, info, warn, error) | `debug` | No |
|
||||
| `DOCKER_HOST` | Docker socket endpoint | `tcp://docker-proxy:2375` | Yes |
|
||||
|
||||
### Ports
|
||||
|
||||
- **10000** - Sablier API endpoint (internal use only)
|
||||
|
||||
### Volumes
|
||||
|
||||
None required - Sablier communicates with Docker via API
|
||||
|
||||
### Networks
|
||||
|
||||
- **traefik-network** - Required for communication with Traefik
|
||||
- **homelab-network** - Required for Docker API access
|
||||
|
||||
## Using Sablier
|
||||
|
||||
### Basic Usage
|
||||
|
||||
1. **Enable on Service:** Add `sablier.enable=true` label to any service
|
||||
2. **Access Service:** Navigate to the service URL in your browser
|
||||
3. **Automatic Startup:** Sablier detects the request and starts the container
|
||||
4. **Wait for Ready:** Service starts and health checks pass
|
||||
5. **Use Service:** Container is now running and accessible
|
||||
6. **Automatic Shutdown:** Container stops after 5 minutes of inactivity
|
||||
|
||||
### Monitoring Lazy Loading
|
||||
|
||||
Check which services are managed by Sablier:
|
||||
|
||||
```bash
|
||||
# View all containers with Sablier labels
|
||||
docker ps --filter "label=sablier.enable=true" --format "table {{.Names}}\t{{.Status}}"
|
||||
|
||||
# Check Sablier logs
|
||||
docker logs sablier
|
||||
|
||||
# View Traefik routes that trigger lazy loading
|
||||
docker logs traefik | grep sablier
|
||||
```
|
||||
|
||||
### Service Groups
|
||||
|
||||
Group related services that should start/stop together:
|
||||
|
||||
```yaml
|
||||
# Database and web app in same group
|
||||
services:
|
||||
myapp:
|
||||
labels:
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=myapp-stack"
|
||||
|
||||
myapp-db:
|
||||
labels:
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=myapp-stack"
|
||||
```
|
||||
|
||||
### Custom Timeouts
|
||||
|
||||
Set different inactivity timeouts per service:
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "sablier.enable=true"
|
||||
- "sablier.timeout=600" # 10 minutes
|
||||
```
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
- **Startup Time:** Services take longer to respond on first access
|
||||
- **Resource Spikes:** Multiple services starting simultaneously can cause load
|
||||
- **Health Checks:** Ensure services have proper health checks for reliable startup
|
||||
|
||||
### Troubleshooting Startup Issues
|
||||
|
||||
- **Container Won't Start:** Check Docker logs for the failing container
|
||||
- **Health Check Fails:** Verify service health endpoints are working
|
||||
- **Network Issues:** Ensure containers are on the correct Docker network
|
||||
|
||||
### Integration with Monitoring
|
||||
|
||||
Sablier works with existing monitoring:
|
||||
|
||||
- **Prometheus:** Can monitor Sablier API metrics
|
||||
- **Grafana:** Visualize container start/stop events
|
||||
- **Dozzle:** View logs from lazy-loaded containers
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Won't Start Automatically
|
||||
|
||||
**Symptoms:** Accessing service URL shows connection error
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# Check if Sablier is running
|
||||
docker ps | grep sablier
|
||||
|
||||
# Verify service has correct labels
|
||||
docker inspect container-name | grep sablier
|
||||
|
||||
# Check Sablier logs
|
||||
docker logs sablier
|
||||
|
||||
# Test manual container start
|
||||
docker start container-name
|
||||
```
|
||||
|
||||
### Containers Not Stopping
|
||||
|
||||
**Symptoms:** Containers remain running after inactivity timeout
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# Check timeout configuration
|
||||
docker inspect container-name | grep sablier.timeout
|
||||
|
||||
# Verify Sablier has access to Docker API
|
||||
docker exec sablier curl -f http://docker-proxy:2375/_ping
|
||||
|
||||
# Check for active connections
|
||||
netstat -tlnp | grep :port
|
||||
```
|
||||
|
||||
### Traefik Routing Issues
|
||||
|
||||
**Symptoms:** Service accessible but Sablier not triggering
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# Verify Traefik labels
|
||||
docker inspect container-name | grep traefik
|
||||
|
||||
# Check Traefik configuration
|
||||
docker logs traefik | grep "Creating router"
|
||||
|
||||
# Test direct access (bypass Sablier)
|
||||
curl http://container-name:port/health
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue:** Services start but are not accessible
|
||||
**Fix:** Ensure services are on the `traefik-network`
|
||||
|
||||
**Issue:** Sablier can't connect to Docker API
|
||||
**Fix:** Verify `DOCKER_HOST` environment variable and network connectivity
|
||||
|
||||
**Issue:** Containers start but health checks fail
|
||||
**Fix:** Add proper health checks to service configurations
|
||||
|
||||
**Issue:** High resource usage during startup
|
||||
**Fix:** Stagger service startups or increase system resources
|
||||
|
||||
### Performance Tuning
|
||||
|
||||
- **Increase Timeouts:** For services that need longer inactivity periods
|
||||
- **Group Services:** Related services can share startup/shutdown cycles
|
||||
- **Monitor Resources:** Use Glances or Prometheus to track resource usage
|
||||
- **Optimize Health Checks:** Ensure health checks are fast and reliable
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **GitHub Issues:** https://github.com/sablierapp/sablier/issues
|
||||
- **Community:** Check Traefik and Docker forums for lazy loading discussions
|
||||
- **Logs:** Enable debug logging with `SABLIER_LOG_LEVEL=debug`
|
||||
- "sablier.start-on-demand=true" # Enable lazy loading
|
||||
```
|
||||
|
||||
### Traefik Middleware
|
||||
|
||||
Configure Sablier middleware in Traefik dynamic configuration:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
middlewares:
|
||||
sablier-service:
|
||||
plugin:
|
||||
sablier:
|
||||
sablierUrl: http://sablier-service:10000
|
||||
group: core-service-name
|
||||
sessionDuration: 2m # How long to keep service running after access
|
||||
ignoreUserAgent: curl # Don't start service for curl requests
|
||||
dynamic:
|
||||
displayName: Service Name
|
||||
theme: ghost
|
||||
show-details-by-default: true
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Service with Lazy Loading
|
||||
|
||||
```yaml
|
||||
services:
|
||||
my-service:
|
||||
image: my-service:latest
|
||||
container_name: my-service
|
||||
restart: "no" # Important: Must be "no" for Sablier to control start/stop
|
||||
networks:
|
||||
- traefik-network
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.my-service.rule=Host(`my-service.${DOMAIN}`)"
|
||||
- "traefik.http.routers.my-service.entrypoints=websecure"
|
||||
- "traefik.http.routers.my-service.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.routers.my-service.middlewares=authelia@docker"
|
||||
- "traefik.http.services.my-service.loadbalancer.server.port=8080"
|
||||
# Sablier lazy loading
|
||||
- "sablier.enable=true"
|
||||
- "sablier.group=core-my-service"
|
||||
- "sablier.start-on-demand=true"
|
||||
```
|
||||
|
||||
### Remote Service Proxy
|
||||
|
||||
For services on remote servers, configure Traefik routes with Sablier middleware:
|
||||
|
||||
```yaml
|
||||
# In /opt/stacks/core/traefik/dynamic/remote-services.yml
|
||||
http:
|
||||
routers:
|
||||
remote-service:
|
||||
rule: "Host(`remote-service.${DOMAIN}`)"
|
||||
entryPoints:
|
||||
- websecure
|
||||
service: remote-service
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
middlewares:
|
||||
- sablier-remote-service@file
|
||||
|
||||
services:
|
||||
remote-service:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://remote-server-ip:port"
|
||||
|
||||
middlewares:
|
||||
sablier-remote-service:
|
||||
plugin:
|
||||
sablier:
|
||||
sablierUrl: http://sablier-service:10000
|
||||
group: remote-server-group
|
||||
sessionDuration: 5m
|
||||
displayName: Remote Service
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Won't Start
|
||||
|
||||
**Check Sablier logs:**
|
||||
```bash
|
||||
cd /opt/stacks/core
|
||||
docker compose logs sablier-service
|
||||
```
|
||||
|
||||
**Verify container permissions:**
|
||||
```bash
|
||||
# Check if Sablier can access Docker API
|
||||
docker exec sablier-service curl -f http://localhost:10000/health
|
||||
```
|
||||
|
||||
### Services Not Starting on Demand
|
||||
|
||||
**Check Traefik middleware configuration:**
|
||||
```bash
|
||||
# Verify middleware is loaded
|
||||
docker logs traefik | grep sablier
|
||||
```
|
||||
|
||||
**Check service labels:**
|
||||
```bash
|
||||
# Verify Sablier labels are present
|
||||
docker inspect service-name | grep sablier
|
||||
```
|
||||
|
||||
### Services Stop Too Quickly
|
||||
|
||||
**Increase session duration:**
|
||||
```yaml
|
||||
middlewares:
|
||||
sablier-service:
|
||||
plugin:
|
||||
sablier:
|
||||
sessionDuration: 10m # Increase from default
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Check resource usage:**
|
||||
```bash
|
||||
docker stats sablier-service
|
||||
```
|
||||
|
||||
**Monitor Docker API calls:**
|
||||
```bash
|
||||
docker logs sablier-service | grep "API call"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Resource Management
|
||||
|
||||
- Use lazy loading for services that aren't accessed frequently
|
||||
- Set appropriate session durations based on usage patterns
|
||||
- Monitor resource usage to ensure adequate system capacity
|
||||
|
||||
### Configuration
|
||||
|
||||
- **Always set `restart: "no"`** for Sablier-managed services to allow full lifecycle control
|
||||
- Group related services together for coordinated startup
|
||||
- Use descriptive display names for the loading page
|
||||
- Configure appropriate timeouts for your use case
|
||||
|
||||
### Security
|
||||
|
||||
- Sablier runs with Docker API access - ensure proper network isolation
|
||||
- Use Docker socket proxy for additional security
|
||||
- Monitor Sablier logs for unauthorized access attempts
|
||||
|
||||
## Integration with Other Services
|
||||
|
||||
### Homepage Dashboard
|
||||
|
||||
Add Sablier status to Homepage:
|
||||
|
||||
```yaml
|
||||
# In homepage config
|
||||
- Core Infrastructure:
|
||||
- Sablier:
|
||||
icon: docker.png
|
||||
href: http://sablier-service:10000
|
||||
description: Lazy loading service
|
||||
widget:
|
||||
type: iframe
|
||||
url: http://sablier-service:10000
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
Monitor Sablier with Prometheus metrics (if available) or basic health checks:
|
||||
|
||||
```yaml
|
||||
# Health check
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:10000/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Themes
|
||||
|
||||
Sablier supports different loading page themes:
|
||||
|
||||
```yaml
|
||||
dynamic:
|
||||
displayName: My Service
|
||||
theme: ghost # Options: ghost, hacker, ocean, etc.
|
||||
show-details-by-default: true
|
||||
```
|
||||
|
||||
### Group Management
|
||||
|
||||
Services can be grouped for coordinated startup:
|
||||
|
||||
```yaml
|
||||
# All services in the same group start together
|
||||
labels:
|
||||
- "sablier.group=media-stack"
|
||||
- "sablier.enable=true"
|
||||
- "sablier.start-on-demand=true"
|
||||
```
|
||||
|
||||
### API Access
|
||||
|
||||
Sablier provides a REST API for programmatic control:
|
||||
|
||||
```bash
|
||||
# Get service status
|
||||
curl http://sablier-service:10000/api/groups
|
||||
|
||||
# Start a service group
|
||||
curl -X POST http://sablier-service:10000/api/groups/media-stack/start
|
||||
|
||||
# Stop a service group
|
||||
curl -X POST http://sablier-service:10000/api/groups/media-stack/stop
|
||||
```
|
||||
|
||||
## Migration from Manual Management
|
||||
|
||||
When adding Sablier to existing services:
|
||||
|
||||
1. **Change restart policy** to `"no"` in the compose file (critical for Sablier control)
|
||||
2. **Add Sablier labels** to the service compose file
|
||||
3. **Configure Traefik middleware** for the service
|
||||
4. **Stop the service** initially (let Sablier manage it)
|
||||
5. **Test access** - service should start automatically
|
||||
6. **Monitor logs** to ensure proper operation
|
||||
|
||||
> **Important**: Services managed by Sablier must have `restart: "no"` to allow Sablier full control over container lifecycle. Do not use `unless-stopped`, `always`, or `on-failure` restart policies.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Traefik Documentation](traefik.md) - Reverse proxy configuration
|
||||
- [Authelia Documentation](authelia.md) - SSO authentication
|
||||
- [On-Demand Remote Services](../Ondemand-Remote-Services.md) - Remote service setup guide
|
||||
@@ -502,3 +502,16 @@ Traefik is the heart of your homelab's networking infrastructure. It:
|
||||
- Scales from simple to complex setups
|
||||
|
||||
Understanding Traefik is crucial for managing your homelab effectively. Take time to explore the dashboard and understand how routing works - it will make troubleshooting and adding new services much easier.
|
||||
|
||||
## Related Services
|
||||
|
||||
- **[Authelia](authelia.md)** - SSO authentication that integrates with Traefik
|
||||
- **[Sablier](sablier.md)** - Lazy loading that works with Traefik routing
|
||||
- **[DuckDNS](duckdns.md)** - Dynamic DNS for SSL certificate validation
|
||||
- **[Gluetun](gluetun.md)** - VPN routing that can work alongside Traefik
|
||||
|
||||
## See Also
|
||||
|
||||
- **[Traefik Labels Guide](../docker-guidelines.md#traefik-label-patterns)** - How to configure services for Traefik
|
||||
- **[SSL Certificate Setup](../getting-started.md#notes-about-ssl-certificates-from-letsencrypt-with-duckdns)** - How SSL certificates work with Traefik
|
||||
- **[External Host Proxying](../proxying-external-hosts.md)** - Route non-Docker services through Traefik
|
||||
|
||||
@@ -209,7 +209,7 @@ tar -czf vaultwarden-backup-$(date +%Y%m%d).tar.gz \
|
||||
# Start container
|
||||
docker start vaultwarden
|
||||
|
||||
# Or use Backrest/Duplicati for automatic backups
|
||||
# Or use Backrest (default) for automatic backups
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Services Overview
|
||||
|
||||
This document provides a comprehensive overview of all 60+ pre-configured services available in the AI-Homelab repository.
|
||||
This document provides a comprehensive overview of all 70+ pre-configured services available in the AI-Homelab repository.
|
||||
|
||||
## Services Overview
|
||||
|
||||
|
||||
Reference in New Issue
Block a user