7 |
12 |
13 |
8 |
11 | Docker Containers
9 |Overview of all Docker containers on your Unraid server
10 |
14 |
26 |
27 |
15 |
16 |
17 |
18 |
21 |
24 |
25 |
28 |
29 |
30 |
117 |
118 |
119 | {% if not containers %}
120 | | Name | 32 |Image | 33 |Status | 34 |Ports | 35 |Volumes | 36 |Environment Variables | 37 |
|---|---|---|---|---|---|
| 43 | {{ container.name }} 44 | | 45 |
46 | {{ container.image }}
47 | |
48 | 49 | {% if container.status == 'running' %} 50 | 51 | {{ container.status }} 52 | 53 | {% elif container.status == 'exited' %} 54 | 55 | {{ container.status }} 56 | 57 | {% else %} 58 | 59 | {{ container.status }} 60 | 61 | {% endif %} 62 | | 63 |64 | {% if container.ports %} 65 | {% for port in container.ports %} 66 | {{ port }} 67 | {% endfor %} 68 | {% else %} 69 | None 70 | {% endif %} 71 | | 72 |
73 | {% if container.volumes %}
74 |
80 |
81 | {% for volume in container.volumes %}
82 |
85 | {% else %}
86 | None
87 | {% endif %}
88 | {{ volume }}
83 | {% endfor %}
84 | |
89 |
90 | {% if container.environment %}
91 |
97 |
98 | {% for key, value in container.environment.items() %}
99 |
100 | {{ key }}:
101 | {% if value == '***MASKED***' %}
102 | {{ value }}
103 | {% else %}
104 |
109 | {% else %}
110 | None
111 | {% endif %}
112 | {{ value }}
105 | {% endif %}
106 |
107 | {% endfor %}
108 | |
113 |
121 |
122 | No containers found. Make sure Docker is running and accessible.
123 |
124 | {% endif %}
125 |
126 | {% endblock %}
127 |
128 | {% block scripts %}
129 |
141 | {% endblock %}
142 |
--------------------------------------------------------------------------------
/src/health_check.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | """
3 | Health check script for Unraid Config Guardian container
4 | """
5 |
6 | import os
7 | import sys
8 | from pathlib import Path
9 |
10 |
11 | def check_docker_connection():
12 | """Check if Docker daemon is accessible."""
13 | try:
14 | # Try importing docker library
15 | import docker
16 |
17 | # Priority 1: Use DOCKER_HOST if set (recommended for socket proxy)
18 | docker_host = os.getenv("DOCKER_HOST")
19 |
20 | if docker_host:
21 | # DOCKER_HOST is set, use it directly
22 | client = docker.DockerClient(base_url=docker_host)
23 | client.ping()
24 | print(f"Successfully connected to Docker daemon at {docker_host}")
25 | return True
26 |
27 | # Priority 2: Fall back to DOCKER_SOCK_PATH for backward compatibility
28 | docker_sock_path = os.getenv("DOCKER_SOCK_PATH")
29 |
30 | if docker_sock_path:
31 | # Legacy variable - check if socket file exists
32 | docker_sock = Path(docker_sock_path)
33 | if not docker_sock.exists():
34 | print(f"Docker socket not found at {docker_sock_path}")
35 | return False
36 |
37 | client = docker.DockerClient(base_url=f"unix://{docker_sock_path}")
38 | client.ping()
39 | print(f"Successfully connected to Docker daemon at {docker_sock_path}")
40 | return True
41 |
42 | # Priority 3: Default to socket proxy
43 | default_host = "tcp://docker-socket-proxy:2375"
44 | client = docker.DockerClient(base_url=default_host)
45 | client.ping()
46 | print(f"Successfully connected to Docker daemon at {default_host}")
47 | return True
48 |
49 | except ImportError as e:
50 | print(f"Docker library not available: {e}")
51 | print("This may be normal during container startup")
52 | return False
53 | except Exception as e:
54 | print(f"Docker connection failed: {e}")
55 | print("Tip: Set DOCKER_HOST environment variable to your Docker Socket Proxy")
56 | print("Example: DOCKER_HOST=tcp://docker-socket-proxy:2375")
57 | return False
58 |
59 |
60 | def check_output_directory():
61 | """Check if output directory is writable."""
62 | try:
63 | output_dir = Path(os.getenv("OUTPUT_DIR", "/output"))
64 |
65 | # Check if directory exists
66 | if not output_dir.exists():
67 | print(f"Output directory does not exist: {output_dir}")
68 | return False
69 |
70 | # Check if directory is writable (less invasive test)
71 | if not os.access(output_dir, os.W_OK):
72 | print(f"Output directory not writable: {output_dir}")
73 | return False
74 |
75 | # Try to create a test file only if we have write access
76 | test_file = output_dir / ".health_check"
77 | try:
78 | test_file.touch()
79 | test_file.unlink()
80 | except PermissionError:
81 | # Directory exists but no write permission
82 | print(f"No write permission for output directory: {output_dir}")
83 | return False
84 |
85 | return True
86 | except Exception as e:
87 | print(f"Output directory check failed: {e}")
88 | return False
89 |
90 |
91 | def check_config_directory():
92 | """Check if config directory is accessible."""
93 | try:
94 | config_dir = Path("/config")
95 | if not config_dir.exists():
96 | print(f"Config directory does not exist: {config_dir}")
97 | return False
98 | if not config_dir.is_dir():
99 | print(f"Config path is not a directory: {config_dir}")
100 | return False
101 | return True
102 | except Exception as e:
103 | print(f"Config directory check failed: {e}")
104 | return False
105 |
106 |
107 | def check_application_files():
108 | """Check if core application files are accessible."""
109 | try:
110 | app_files = [
111 | Path("/app/src/unraid_config_guardian.py"),
112 | Path("/app/src/web_gui.py"),
113 | ]
114 |
115 | for app_file in app_files:
116 | if not app_file.exists():
117 | print(f"Core application file missing: {app_file}")
118 | return False
119 |
120 | return True
121 | except Exception as e:
122 | print(f"Application files check failed: {e}")
123 | return False
124 |
125 |
126 | def main():
127 | """Main health check function."""
128 | print(f"Health check running as user: {os.getuid()}:{os.getgid()}")
129 |
130 | checks = [
131 | ("Application files", check_application_files),
132 | ("Config directory", check_config_directory),
133 | ("Output directory", check_output_directory),
134 | ("Docker connection", check_docker_connection),
135 | ]
136 |
137 | all_passed = True
138 | results = []
139 |
140 | for check_name, check_func in checks:
141 | try:
142 | if check_func():
143 | print(f"✅ {check_name}: OK")
144 | results.append(f"{check_name}: OK")
145 | else:
146 | print(f"❌ {check_name}: FAILED")
147 | results.append(f"{check_name}: FAILED")
148 | all_passed = False
149 | except Exception as e:
150 | print(f"❌ {check_name}: ERROR - {e}")
151 | results.append(f"{check_name}: ERROR - {e}")
152 | all_passed = False
153 |
154 | # Summary
155 | print("-" * 40)
156 | for result in results:
157 | print(f" {result}")
158 |
159 | if all_passed:
160 | print("🟢 All health checks passed")
161 | sys.exit(0)
162 | else:
163 | print("🔴 One or more health checks failed")
164 | sys.exit(1)
165 |
166 |
167 | if __name__ == "__main__":
168 | main()
169 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | # Unraid Config Guardian
4 |
5 | 
6 |
7 | [](https://github.com/stephondoestech/unraid-config-guardian/actions/workflows/ci-cd.yml)
8 | [](https://hub.docker.com/r/stephondoestech/unraid-config-guardian)
9 | [](https://github.com/stephondoestech/unraid-config-guardian/releases)
10 | [](LICENSE)
11 |
12 | **Your Unraid flash drive crashed and you don't have a backup?**
13 |
14 | This tool saves you from complete disaster by automatically documenting your entire Unraid configuration.
15 |
16 |
17 |
18 | ## Flash Drive Disaster Recovery
19 |
20 | **The Problem:** Your Unraid flash drive dies, taking with it:
21 | - All Docker container configurations
22 | - System settings and user shares
23 | - Plugin configurations and templates
24 | - Years of careful setup work
25 |
26 | **The Solution:** Config Guardian automatically backs up everything needed to rebuild your server:
27 | - **All running containers** → Docker templates + compose files
28 | - **System configuration** → Settings, shares, plugins
29 | - **Complete rebuild guide** → Step-by-step restoration
30 | - **Change tracking** → See what changed between backups
31 |
32 | ## Application
33 |
34 |
6 |
7 | [](https://github.com/stephondoestech/unraid-config-guardian/actions/workflows/ci-cd.yml)
8 | [](https://hub.docker.com/r/stephondoestech/unraid-config-guardian)
9 | [](https://github.com/stephondoestech/unraid-config-guardian/releases)
10 | [](LICENSE)
11 |
12 | **Your Unraid flash drive crashed and you don't have a backup?**
13 |
14 | This tool saves you from complete disaster by automatically documenting your entire Unraid configuration.
15 |
16 |
35 |
36 | ### Dashboard Overview
37 | 
38 |
39 | ### Container Management
40 | 
41 |
42 |
43 |
44 |
45 |
46 | ## Emergency Setup (Flash Drive Died)
47 |
48 | ### Quick Install on Fresh Unraid
49 |
50 | 1. **Install fresh Unraid** on new hardware/flash drive
51 | 2. **Set up basic array** and enable Docker
52 | 3. **Install Config Guardian:**
53 |
54 | ```bash
55 | # SSH into Unraid and run:
56 | mkdir -p /mnt/user/appdata/unraid-config-guardian
57 | mkdir -p /mnt/user/backups/unraid-docs
58 |
59 | docker run -d \
60 | --name unraid-config-guardian \
61 | --restart unless-stopped \
62 | -p 7842:7842 \
63 | -v /mnt/user/appdata/unraid-config-guardian:/config \
64 | -v /mnt/user/backups/unraid-docs:/output \
65 | -v /var/run/docker.sock:/var/run/docker.sock:ro \
66 | -v /boot:/boot:ro \
67 | -e PUID=99 -e PGID=100 \
68 | -e SCHEDULE="0 2 * * 0" \
69 | stephondoestech/unraid-config-guardian:latest
70 | ```
71 |
72 | 4. **Access:** `http://your-unraid-ip:7842`
73 | 5. **Generate backup** to start protecting your new setup
74 |
75 | ### Preventive Setup (Normal Use)
76 |
77 | Install via **Community Apps** → Search "Config Guardian" → Install
78 |
79 | **Pro Tip:** Set up weekly automated backups immediately after configuring any new containers!
80 |
81 | ## Your Backup Contains Everything Needed
82 |
83 | ```
84 | unraid-backup/
85 | ├── container-templates.zip # Native Unraid XML templates → Drop in Docker tab
86 | ├── docker-compose.yml # Emergency fallback containers
87 | ├── unraid-config.json # System settings, shares, plugins
88 | ├── restore.sh # Automated restoration script
89 | ├── changes.log # What changed since last backup
90 | └── README.md # Step-by-step recovery guide
91 | ```
92 |
93 | **Data Sources:**
94 | - Running Docker containers (via Docker API)
95 | - Unraid system configuration (`/boot/config/`)
96 | - User shares and disk settings
97 | - Plugin configurations and templates
98 |
99 | ## Super Simple Recovery
100 |
101 | **When disaster strikes:**
102 |
103 | 1. **Fresh Unraid install** → Set up array
104 | 2. **Restore from backup:**
105 | ```bash
106 | cd /mnt/user/backups/unraid-docs/latest
107 | bash restore.sh
108 | ```
109 | 3. **Add containers:** Docker tab → Your templates are in the dropdown
110 | 4. **Copy back appdata** from your separate backups
111 |
112 | **That's it!** Your entire server configuration is restored.
113 |
114 | ## IMPORTANT: This is NOT a Data Backup Solution
115 |
116 | **Config Guardian only backs up your CONFIGURATION, not your data.** You still need a proper backup solution for your appdata and media files.
117 |
118 | **Recommended backup solutions:**
119 | - **Kopia** - Modern, fast, encrypted backups
120 | - **Duplicacy** - Web-based backup management
121 | - **Rustic** - Rust-based restic alternative
122 | - **Unraid Plugins:** CA Backup/Restore, Appdata Backup
123 |
124 | **What Config Guardian backs up:**
125 | - Docker container configurations and templates
126 | - Unraid system settings and shares
127 | - Plugin configurations
128 | - Recovery scripts and documentation
129 |
130 | **What you still need to backup separately:**
131 | - `/mnt/user/appdata/` (your container data)
132 | - `/mnt/user/` (your media and files)
133 | - Any custom scripts or configurations
134 |
135 | ## Configuration
136 |
137 | **Essential Settings:**
138 | ```bash
139 | SCHEDULE="0 2 * * 0" # Weekly backup (Sunday 2 AM)
140 | PUID=99 PGID=100 # Standard Unraid permissions
141 | MASK_PASSWORDS=true # Hide sensitive data in backups
142 | ```
143 |
144 | **Common Issues:**
145 | - **No templates in dropdown:** Enable Template Authoring Mode in Docker settings
146 | - **Permission errors:** See [troubleshooting guide](docs/troubleshooting.md)
147 |
148 | ## Manual Usage
149 |
150 | ```bash
151 | # Generate backup now
152 | docker exec unraid-config-guardian python3 src/unraid_config_guardian.py
153 |
154 | # View logs
155 | docker logs unraid-config-guardian
156 |
157 | # Check what changed
158 | cat /mnt/user/backups/unraid-docs/latest/changes.log
159 | ```
160 |
161 | ## License
162 |
163 | This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
164 |
165 | ---
166 |
167 | **Built by [Stephon Parker](https://github.com/stephondoestech) for the Unraid community**
168 |
169 | *Development supported by Claude (Anthropic)*
170 |
171 | [⭐ Star](https://github.com/stephondoestech/unraid-config-guardian/stargazers) | [🐛 Issues](https://github.com/stephondoestech/unraid-config-guardian/issues) | [💡 Features](https://github.com/stephondoestech/unraid-config-guardian/issues)
172 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | # Unraid Config Guardian Makefile
2 |
3 | PYTHON ?= python3
4 | PIP ?= pip3
5 | APP_DIRS := src tests
6 | DOCKER_COMPOSE := docker-compose
7 | DOCKER_COMPOSE_DEV := $(DOCKER_COMPOSE) -f docker-compose.dev.yml
8 | IMAGE_NAME := unraid-config-guardian
9 | IMAGE_TAG ?= latest
10 | CONTAINER_NAME := unraid-config-guardian
11 |
12 | BLACK := black $(APP_DIRS)
13 | ISORT := isort $(APP_DIRS)
14 | FLAKE8 := flake8 $(APP_DIRS) --max-line-length=100 --extend-ignore=E203,W503,E231,E221,E272,E201,E202,E702,E271
15 | PYTEST := pytest tests/ -v
16 | PYTEST_COV := $(PYTEST) --cov=src/ --cov-report=html --cov-report=term
17 |
18 | COLOR ?= 1
19 | ifeq ($(COLOR),1)
20 | BLUE := \033[0;34m
21 | GREEN := \033[0;32m
22 | YELLOW := \033[0;33m
23 | NC := \033[0m
24 | else
25 | BLUE :=
26 | GREEN :=
27 | YELLOW :=
28 | NC :=
29 | endif
30 |
31 | .PHONY: help dev-setup install install-dev hooks lint format format-check type-check test test-cov run run-gui run-prod health clean clean-all check fix-and-check docker-build docker-run docker-dev docker-stop docker-stop-dev docker-logs docker-logs-dev docker-shell docker-health docker-clean ci-test ci-build ci-push tag release-patch release-minor release-major list-releases all deploy
32 |
33 | help: ## Show this help message
34 | @echo "$(BLUE)Unraid Config Guardian - Development Commands$(NC)"
35 | @grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(GREEN)%-18s$(NC) %s\n", $$1, $$2}'
36 |
37 | dev-setup: ## Create venv and print next steps
38 | @echo "$(BLUE)Setting up development environment...$(NC)"
39 | $(PYTHON) -m venv venv
40 | @echo "$(YELLOW)Activate with: source venv/bin/activate$(NC)"
41 | @echo "$(YELLOW)Then run: make install-dev$(NC)"
42 |
43 | install: ## Install runtime dependencies
44 | $(PIP) install -r requirements.txt
45 |
46 | hooks: ## Install git hooks
47 | pre-commit install --install-hooks
48 | cp .githooks/pre-push .git/hooks/pre-push
49 | chmod +x .git/hooks/pre-push
50 |
51 | install-dev: install hooks ## Install runtime + development dependencies
52 | $(PIP) install -r requirements-dev.txt
53 |
54 | lint: ## Run flake8
55 | $(FLAKE8)
56 |
57 | format: ## Format with black and isort
58 | $(BLACK)
59 | $(ISORT)
60 |
61 | format-check: ## Check formatting
62 | $(BLACK) --check
63 | $(ISORT) --check-only
64 |
65 | type-check: ## Run type checks with mypy
66 | mypy src/ --ignore-missing-imports
67 |
68 | test: ## Run tests
69 | $(PYTEST)
70 |
71 | test-cov: ## Run tests with coverage
72 | $(PYTEST_COV)
73 |
74 | run: ## Run the CLI locally (debug)
75 | mkdir -p ./output
76 | $(PYTHON) src/unraid_config_guardian.py --output ./output --debug
77 |
78 | run-gui: ## Run the dev web GUI
79 | mkdir -p ./output
80 | $(PYTHON) src/web_gui_dev.py
81 |
82 | run-prod: ## Run the CLI in production mode
83 | mkdir -p ./output
84 | $(PYTHON) src/unraid_config_guardian.py --output ./output
85 |
86 | health: ## Run health check
87 | $(PYTHON) src/health_check.py
88 |
89 | docker-build: ## Build Docker image
90 | docker build -t $(IMAGE_NAME):$(IMAGE_TAG) .
91 |
92 | docker-run: ## Run Docker container (production/Unraid)
93 | $(DOCKER_COMPOSE) up -d
94 |
95 | docker-dev: ## Run Docker container (local development)
96 | mkdir -p ./config ./output
97 | $(DOCKER_COMPOSE_DEV) up -d
98 |
99 | docker-stop: ## Stop Docker container
100 | $(DOCKER_COMPOSE) down
101 |
102 | docker-stop-dev: ## Stop development Docker container
103 | $(DOCKER_COMPOSE_DEV) down
104 |
105 | docker-logs: ## Show Docker container logs
106 | $(DOCKER_COMPOSE) logs -f
107 |
108 | docker-logs-dev: ## Show development container logs
109 | $(DOCKER_COMPOSE_DEV) logs -f
110 |
111 | docker-shell: ## Get shell in running container
112 | docker exec -it $(CONTAINER_NAME) /bin/bash
113 |
114 | docker-health: ## Check container health
115 | docker exec $(CONTAINER_NAME) $(PYTHON) src/health_check.py
116 |
117 | docker-clean: ## Clean up Docker resources
118 | $(DOCKER_COMPOSE) down --volumes --rmi all
119 | docker system prune -f
120 |
121 | clean: ## Clean up generated files
122 | find . -type f -name "*.pyc" -delete
123 | find . -type d -name "__pycache__" -delete
124 | find . -type d -name "*.egg-info" -exec rm -rf {} +
125 | rm -rf build/ dist/ .pytest_cache/ .coverage htmlcov/ output/ logs/
126 |
127 | clean-all: clean docker-clean ## Clean everything including Docker resources
128 |
129 | check: format-check lint type-check test ## Run all quality checks
130 |
131 | fix-and-check: format lint type-check test ## Auto-format then run checks
132 |
133 | all: clean install-dev check docker-build ## Run complete development workflow
134 |
135 | deploy: check docker-build docker-run ## Deploy to production
136 |
137 | ci-test: ## Run CI tests (coverage XML for CI)
138 | $(PYTEST) --cov=src/ --cov-report=xml --cov-report=term
139 |
140 | ci-build: ## Build multi-platform image
141 | docker buildx build --platform linux/amd64,linux/arm64 -t $(IMAGE_NAME):$(IMAGE_TAG) .
142 |
143 | ci-push: ## Push to Docker Hub
144 | docker push $(IMAGE_NAME):$(IMAGE_TAG)
145 |
146 | tag: ## Create and push a new tag (usage: make tag VERSION=v1.0.0)
147 | @if [ -z "$(VERSION)" ]; then echo "Usage: make tag VERSION=v1.0.0"; exit 1; fi
148 | @VERSION_NUM=$$(echo $(VERSION) | sed 's/^v//'); \
149 | sed -i '' "s/__version__ = \".*\"/__version__ = \"$$VERSION_NUM\"/" src/version.py; \
150 | git add src/version.py; \
151 | git commit -m "Update version to $$VERSION_NUM"; \
152 | git tag -a $(VERSION) -m "Release $(VERSION)"; \
153 | git push origin main; \
154 | git push origin $(VERSION)
155 |
156 | release-patch: ## Create patch release (v1.0.0 -> v1.0.1)
157 | @LATEST=$$(git tag -l "v*.*.*" | sort -V | tail -1); \
158 | if [ -z "$$LATEST" ]; then NEW_VERSION="v1.0.0"; \
159 | else MAJOR=$$(echo $$LATEST | cut -d. -f1); MINOR=$$(echo $$LATEST | cut -d. -f2); PATCH=$$(echo $$LATEST | cut -d. -f3); \
160 | NEW_PATCH=$$((PATCH + 1)); NEW_VERSION="$$MAJOR.$$MINOR.$$NEW_PATCH"; fi; \
161 | echo "Next version: $$NEW_VERSION"; \
162 | make tag VERSION=$$NEW_VERSION
163 |
164 | release-minor: ## Create minor release (v1.0.x -> v1.1.0)
165 | @LATEST=$$(git tag -l "v*.*.*" | sort -V | tail -1); \
166 | if [ -z "$$LATEST" ]; then NEW_VERSION="v1.0.0"; \
167 | else MAJOR=$$(echo $$LATEST | cut -d. -f1); MINOR=$$(echo $$LATEST | cut -d. -f2); \
168 | NEW_MINOR=$$((MINOR + 1)); NEW_VERSION="$$MAJOR.$$NEW_MINOR.0"; fi; \
169 | echo "Next version: $$NEW_VERSION"; \
170 | make tag VERSION=$$NEW_VERSION
171 |
172 | release-major: ## Create major release (v1.x.x -> v2.0.0)
173 | @LATEST=$$(git tag -l "v*.*.*" | sort -V | tail -1); \
174 | if [ -z "$$LATEST" ]; then NEW_VERSION="v1.0.0"; \
175 | else MAJOR=$$(echo $$LATEST | cut -d. -f1 | sed 's/v//'); \
176 | NEW_MAJOR=$$((MAJOR + 1)); NEW_VERSION="v$$NEW_MAJOR.0.0"; fi; \
177 | echo "Next version: $$NEW_VERSION"; \
178 | make tag VERSION=$$NEW_VERSION
179 |
180 | list-releases: ## List recent releases
181 | @git tag -l "v*.*.*" | sort -V | tail -10
182 |
--------------------------------------------------------------------------------
/docs/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing to Unraid Config Guardian
2 |
3 | Thank you for your interest in contributing! This guide will help you get started.
4 |
5 | ## 🚀 Quick Development Setup
6 |
7 | ```bash
8 | # Clone the repository
9 | git clone https://github.com/stephondoestech/unraid-config-guardian.git
10 | cd unraid-config-guardian
11 |
12 | # Set up development environment
13 | make dev-setup
14 | source venv/bin/activate
15 | make install-dev
16 |
17 | # Run tests and quality checks
18 | make check
19 |
20 | # Start development server
21 | make run-gui # Web GUI at http://localhost:7842
22 | # OR
23 | make run # CLI version
24 | ```
25 |
26 | ## 🧪 Testing
27 |
28 | ### Local Testing
29 | ```bash
30 | # Run all tests
31 | make test
32 |
33 | # Run with coverage
34 | make test-cov
35 |
36 | # Run specific test file
37 | pytest tests/test_unraid_config_guardian.py -v
38 |
39 | # Run linting and type checking
40 | make lint
41 | make type-check
42 | make format
43 | ```
44 |
45 | ### Docker Testing
46 | ```bash
47 | # Build and test locally
48 | make docker-build
49 | make docker-dev
50 |
51 | # Access at http://localhost:7842
52 | ```
53 |
54 | ## 📋 Development Workflow
55 |
56 | 1. **Create a feature branch:**
57 | ```bash
58 | git checkout -b feature/your-feature-name
59 | ```
60 |
61 | 2. **Make your changes:**
62 | - Write tests for new functionality
63 | - Follow existing code style
64 | - Update documentation if needed
65 |
66 | 3. **Test your changes:**
67 | ```bash
68 | make check # Runs all quality checks
69 | ```
70 |
71 | 4. **Commit and push:**
72 | ```bash
73 | git add .
74 | git commit -m "Add: description of your changes"
75 | git push origin feature/your-feature-name
76 | ```
77 |
78 | 5. **Create a Pull Request:**
79 | - Use the PR template
80 | - Link any related issues
81 | - Ensure all CI checks pass
82 |
83 | ## 🎯 Areas for Contribution
84 |
85 | ### High Priority
86 | - **Container Detection**: Improve container analysis and edge cases
87 | - **Backup Formats**: Add support for other backup formats (Kubernetes YAML, etc.)
88 | - **Notifications**: Implement email/webhook notifications
89 | - **Scheduling**: Enhance cron scheduling with more options
90 | - **Testing**: Expand test coverage, especially integration tests
91 |
92 | ### Medium Priority
93 | - **UI Improvements**: Enhance the web interface
94 | - **Documentation**: Better user guides and API docs
95 | - **Performance**: Optimize for servers with many containers
96 | - **Plugins**: Support for Unraid plugin backup
97 |
98 | ### Good First Issues
99 | - **Bug Fixes**: Check GitHub issues labeled `good first issue`
100 | - **Documentation**: Improve README, add examples
101 | - **Templates**: Create more Unraid Community App templates
102 | - **Testing**: Add unit tests for specific functions
103 |
104 | ## 🏗️ Architecture Overview
105 |
106 | ```
107 | src/
108 | ├── unraid_config_guardian.py # Main CLI application
109 | ├── web_gui.py # Production web interface
110 | ├── web_gui_dev.py # Development web interface with mocks
111 | └── health_check.py # Container health monitoring
112 |
113 | templates/ # HTML templates for web UI
114 | ├── base.html # Base template
115 | ├── dashboard.html # Main dashboard
116 | ├── containers.html # Container overview
117 | └── backups.html # Backup management
118 |
119 | docker/
120 | └── entrypoint.sh # Container entrypoint script
121 | ```
122 |
123 | ## 🎨 Code Style Guidelines
124 |
125 | ### Python Code
126 | - **Black** for formatting: `make format`
127 | - **Flake8** for linting: `make lint`
128 | - **MyPy** for type checking: `make type-check`
129 | - **Line length**: 88 characters (Black default)
130 | - **Type hints**: Required for all functions
131 | - **Docstrings**: Google-style docstrings for all public functions
132 |
133 | ### Example:
134 | ```python
135 | def process_container(container: Dict[str, Any]) -> ContainerInfo:
136 | """Process a Docker container and extract configuration.
137 |
138 | Args:
139 | container: Raw Docker container data
140 |
141 | Returns:
142 | ContainerInfo object with parsed configuration
143 |
144 | Raises:
145 | ValueError: If container data is invalid
146 | """
147 | # Implementation here
148 | ```
149 |
150 | ### Web Templates
151 | - **Bootstrap 5** for styling
152 | - **Semantic HTML** structure
153 | - **Accessibility** considerations (ARIA labels, etc.)
154 | - **Mobile-responsive** design
155 |
156 | ## 🔄 CI/CD Pipeline
157 |
158 | Our GitHub Actions workflow:
159 |
160 | 1. **Test Stage**: Runs tests, linting, type checking
161 | 2. **Build Stage**: Builds Docker image for multiple platforms
162 | 3. **Security Stage**: Vulnerability scanning with Trivy
163 | 4. **Deploy Stage**: Pushes to Docker Hub (main branch & tags)
164 |
165 | ### Running CI Locally
166 | ```bash
167 | # Run the same checks as CI
168 | make check
169 |
170 | # Build multi-platform (requires Docker Buildx)
171 | make ci-build
172 |
173 | # Test Docker image
174 | make docker-build
175 | make docker-dev
176 | ```
177 |
178 | ## 📦 Release Process
179 |
180 | ### Creating a Release
181 |
182 | 1. **Update version numbers** in relevant files
183 | 2. **Update CHANGELOG.md** with new features/fixes
184 | 3. **Create and push a tag:**
185 | ```bash
186 | make tag VERSION=v1.2.0
187 | ```
188 | 4. **GitHub Actions** will automatically:
189 | - Run full test suite
190 | - Build multi-platform Docker images
191 | - Push to Docker Hub
192 | - Create GitHub release
193 |
194 | ### Version Numbering
195 | We follow [Semantic Versioning](https://semver.org/):
196 | - `v1.0.0` - Major release (breaking changes)
197 | - `v1.1.0` - Minor release (new features)
198 | - `v1.1.1` - Patch release (bug fixes)
199 |
200 | ## 🐛 Bug Reports
201 |
202 | When reporting bugs, please include:
203 | - Unraid version
204 | - Container/application version
205 | - Steps to reproduce
206 | - Expected vs actual behavior
207 | - Relevant logs
208 | - Screenshots (for UI issues)
209 |
210 | ## 💡 Feature Requests
211 |
212 | For new features:
213 | - Describe the use case
214 | - Explain why it would be valuable
215 | - Consider implementation complexity
216 | - Provide mockups for UI changes
217 |
218 | ## 🔒 Security
219 |
220 | For security issues:
221 | - **DO NOT** open public GitHub issues
222 | - Email: security@stephondoestech.com
223 | - Include details about the vulnerability
224 | - Allow reasonable time for fixes before disclosure
225 |
226 | ## 📄 License
227 |
228 | By contributing, you agree that your contributions will be licensed under the MIT License.
229 |
230 | ## 🙋♂️ Questions?
231 |
232 | - **GitHub Discussions**: For general questions
233 | - **GitHub Issues**: For bug reports and feature requests
234 | - **Discord**: [Join our community](https://discord.gg/unraid-config-guardian) (coming soon)
235 |
236 | Thank you for contributing to Unraid Config Guardian! 🎉
237 |
--------------------------------------------------------------------------------
/templates/base.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
38 |
39 | ### Container Management
40 |
41 |
42 |
60 | {% block content %}{% endblock %}
61 |
62 |
63 |
64 |
65 |
80 |
81 |
82 |
167 | {% block scripts %}{% endblock %}
168 |
169 |
170 |
--------------------------------------------------------------------------------
/templates/dashboard.html:
--------------------------------------------------------------------------------
1 | {% extends "base.html" %}
2 |
3 | {% block title %}Dashboard - Unraid Config Guardian{% endblock %}
4 |
5 | {% block content %}
6 |
66 |
78 |
79 |
7 |
12 |
13 | {% if stats.error %}
14 |
8 |
11 | Dashboard
9 |Monitor your Unraid server and manage configuration backups
10 |
15 | Error: {{ stats.error }}
16 |
17 | {% else %}
18 |
19 |
20 |
21 |
58 |
59 |
60 |
22 |
30 |
23 |
29 |
24 |
25 |
28 | {{ stats.total_containers }}
26 |Total Containers
27 |
31 |
39 |
32 |
38 |
33 |
34 |
37 | {{ stats.running_containers }}
35 |Running
36 |
40 |
48 |
41 |
47 |
42 |
43 |
46 | {{ stats.system_info.hostname }}
44 |Hostname
45 |
49 |
57 |
50 |
56 |
51 |
52 |
55 | {{ stats.system_info.get('unraid_version', 'Unknown') }}
53 |Unraid Version
54 |
61 |
83 |
84 |
85 |
62 |
82 |
63 |
81 |
64 |
66 | Quick Actions
65 |
67 |
70 |
71 | Download All (ZIP)
72 |
73 |
74 | View Containers
75 |
76 |
77 | View Backups
78 |
79 |
80 |
86 |
144 |
145 |
146 |
87 |
113 |
88 |
112 |
89 |
91 | System Information
90 |
92 |
93 |
110 |
111 | | Hostname: | 95 |{{ stats.system_info.hostname }} | 96 |
| Unraid Version: | 99 |{{ stats.system_info.get('unraid_version', 'Unknown') }} | 100 |
| Guardian Version: | 103 |{{ stats.system_info.get('guardian_version', 'Unknown') }} | 104 |
| Last Scan: | 107 |{{ stats.system_info.timestamp[:19] if stats.system_info.timestamp else 'Never' }} | 108 |
114 |
143 |
115 |
142 |
116 |
118 | Last Backup
117 |
119 | {% if stats.last_backup %}
120 |
121 |
134 | {% else %}
135 |
141 | | Date: | 123 |{{ stats.last_backup.timestamp[:19] if stats.last_backup.timestamp else 'Unknown' }} | 124 |
| Containers: | 127 |{{ stats.last_backup.containers }} | 128 |
| Size: | 131 |{{ "%.1f"|format(stats.last_backup.size / 1024) }} KB | 132 |
No backups found
136 | 139 | {% endif %} 140 |
147 |
180 |
181 | {% endif %}
182 | {% endblock %}
183 |
--------------------------------------------------------------------------------
/docs/DEPLOYMENT.md:
--------------------------------------------------------------------------------
1 | # Deployment Guide
2 |
3 | ## 🚀 CI/CD Pipeline Setup
4 |
5 | ### 1. GitHub Repository Setup
6 |
7 | The repository now includes a complete CI/CD pipeline with:
8 |
9 | ```
10 | .github/
11 | ├── workflows/
12 | │ ├── ci-cd.yml # Main CI/CD pipeline
13 | │ └── release.yml # Automatic releases
14 | └── ISSUE_TEMPLATE/
15 | ├── bug_report.md # Bug report template
16 | └── feature_request.md # Feature request template
17 | ```
18 |
19 | ### 2. Docker Hub Configuration
20 |
21 | **Required GitHub Secrets:**
22 |
23 | 1. **Go to Repository Settings** → **Secrets and variables** → **Actions**
24 | 2. **Add these secrets:**
25 |
26 | ```
27 | DOCKER_USERNAME = your-dockerhub-username
28 | DOCKER_TOKEN = your-dockerhub-access-token
29 | ```
30 |
31 | **Creating Docker Hub Token:**
32 | 1. Login to [Docker Hub](https://hub.docker.com)
33 | 2. Go to **Account Settings** → **Security**
34 | 3. Click **New Access Token**
35 | 4. Name: `unraid-config-guardian-github`
36 | 5. Permissions: **Read, Write, Delete**
37 | 6. Copy the token and add it to GitHub secrets
38 |
39 | ### 3. Automated Workflows
40 |
41 | The CI/CD pipeline automatically:
42 |
43 | **On Pull Requests:**
44 | - ✅ Runs tests (pytest)
45 | - ✅ Code quality checks (black, flake8, mypy)
46 | - ✅ Builds Docker image
47 | - ✅ Security scanning (Trivy)
48 |
49 | **On Push to `main`:**
50 | - ✅ Everything above, plus:
51 | - ✅ Deploys to Docker Hub as `latest`
52 | - ✅ Multi-platform build (AMD64 + ARM64)
53 |
54 | **On Version Tags (`v1.0.0`):**
55 | - ✅ Everything above, plus:
56 | - ✅ Creates GitHub Release
57 | - ✅ Deploys versioned Docker image
58 | - ✅ Updates Docker Hub description
59 |
60 | ### 4. Release Process
61 |
62 | **Create a new release:**
63 |
64 | ```bash
65 | # Make sure your changes are committed and pushed
66 | git add .
67 | git commit -m "Add: new feature description"
68 | git push origin main
69 |
70 | # Create and push a version tag
71 | make tag VERSION=v1.0.0
72 | ```
73 |
74 | **What happens automatically:**
75 | 1. GitHub Actions builds and tests
76 | 2. Multi-platform Docker image is created
77 | 3. Image is pushed to Docker Hub
78 | 4. GitHub Release is created with changelog
79 | 5. Unraid users can pull the new version
80 |
81 | ## 📦 Docker Hub Deployment
82 |
83 | ### Manual Deployment (if needed)
84 |
85 | ```bash
86 | # Build for multiple platforms
87 | docker buildx create --use
88 | docker buildx build --platform linux/amd64,linux/arm64 \
89 | -t stephondoestech/unraid-config-guardian:latest \
90 | -t stephondoestech/unraid-config-guardian:v1.0.0 \
91 | --push .
92 | ```
93 |
94 | ### Image Tags Strategy
95 |
96 | - **`latest`** - Latest stable release from main branch
97 | - **`v1.0.0`** - Specific version tags
98 | - **`main`** - Latest development from main branch
99 | - **`develop`** - Development branch builds
100 |
101 | ## 🐳 Production Deployment
102 |
103 | ### Option 1: Docker Command (Unraid)
104 |
105 | ```bash
106 | docker run -d \
107 | --name unraid-config-guardian \
108 | --restart unless-stopped \
109 | -p 7842:7842 \
110 | -v /mnt/user/appdata/unraid-config-guardian:/config \
111 | -v /mnt/user/backups/unraid-docs:/output \
112 | -v /var/run/docker.sock:/var/run/docker.sock:ro \
113 | -v /boot:/boot:ro \
114 | -e PUID=99 -e PGID=100 -e TZ=America/New_York \
115 | -e MASK_PASSWORDS=true \
116 | stephondoestech/unraid-config-guardian:latest
117 | ```
118 |
119 | ### Option 2: Docker Compose (Unraid)
120 |
121 | ```bash
122 | # Copy docker-compose.yml to Unraid
123 | scp docker-compose.yml root@unraid-server:/mnt/user/appdata/unraid-config-guardian/
124 |
125 | # SSH into Unraid
126 | ssh root@unraid-server
127 | cd /mnt/user/appdata/unraid-config-guardian
128 |
129 | # Deploy
130 | docker-compose up -d
131 | ```
132 |
133 | ### Option 3: Unraid Community Apps
134 |
135 | 1. **Apps** → **Search** → "Config Guardian"
136 | 2. **Install** and configure paths
137 | 3. **Start** container
138 |
139 | ## 🔧 Environment Configuration
140 |
141 | ### Production Environment Variables
142 |
143 | ```bash
144 | # Required
145 | PUID=99 # Unraid user ID
146 | PGID=100 # Unraid group ID
147 | TZ=America/New_York # Timezone
148 |
149 | # Optional
150 | SCHEDULE=0 2 * * 0 # Backup schedule (cron)
151 | MASK_PASSWORDS=true # Security
152 | INCLUDE_SYSTEM_INFO=true # System details
153 | DEBUG=false # Debug mode
154 |
155 | # Advanced (optional)
156 | WEBHOOK_URL=https://... # Notifications
157 | EMAIL_NOTIFICATIONS=admin@domain.com
158 | WEB_HOST=0.0.0.0 # Web server host
159 | WEB_PORT=8080 # Web server port
160 | ```
161 |
162 | ### Volume Mounts
163 |
164 | ```bash
165 | # Required mounts
166 | /mnt/user/appdata/unraid-config-guardian:/config # App config
167 | /mnt/user/backups/unraid-docs:/output # Generated backups
168 | /var/run/docker.sock:/var/run/docker.sock:ro # Docker access
169 | /boot:/boot:ro # Unraid flash drive
170 |
171 | # Optional mounts
172 | /mnt/user:/mnt/user:ro # User shares
173 | /etc/unraid:/etc/unraid:ro # System config
174 | ```
175 |
176 | ## 🌐 Accessing the Application
177 |
178 | - **Web Interface**: `http://your-unraid-ip:7842`
179 | - **Health Check**: `http://your-unraid-ip:7842/health` (coming soon)
180 | - **API Endpoints**: `http://your-unraid-ip:7842/api/`
181 |
182 | ## 📊 Monitoring
183 |
184 | ### Container Health
185 | ```bash
186 | # Check container status
187 | docker ps | grep unraid-config-guardian
188 |
189 | # View logs
190 | docker logs unraid-config-guardian -f
191 |
192 | # Health check
193 | docker exec unraid-config-guardian python src/health_check.py
194 | ```
195 |
196 | ### Backup Verification
197 | ```bash
198 | # Check generated files
199 | ls -la /mnt/user/backups/unraid-docs/
200 |
201 | # Verify backup content
202 | cat /mnt/user/backups/unraid-docs/unraid-config.json | jq .
203 | ```
204 |
205 | ## 🔍 Troubleshooting
206 |
207 | ### Common Issues
208 |
209 | **Container won't start:**
210 | - Check Docker socket permissions
211 | - Verify mount paths exist
212 | - Check container logs: `docker logs unraid-config-guardian`
213 |
214 | **No containers detected:**
215 | - Verify Docker socket mount: `/var/run/docker.sock`
216 | - Check PUID/PGID settings
217 | - Ensure container has Docker access
218 |
219 | **Web UI not accessible:**
220 | - Check port mapping: `7842:7842`
221 | - Verify firewall settings
222 | - Check Unraid network configuration
223 |
224 | **Backup generation fails:**
225 | - Check output directory permissions
226 | - Verify `/boot` mount is read-only
227 | - Review container logs for errors
228 |
229 | ### Getting Help
230 |
231 | 1. **Check logs first**: `docker logs unraid-config-guardian`
232 | 2. **GitHub Issues**: Report bugs with logs and system info
233 | 3. **Unraid Forums**: Community support
234 | 4. **Discord**: Real-time help (coming soon)
235 |
236 | ## 📈 Scaling and Performance
237 |
238 | ### Resource Usage
239 | - **Memory**: ~100-200MB typical usage
240 | - **CPU**: Minimal (spikes during backup generation)
241 | - **Disk**: Backup files typically 1-10MB each
242 |
243 | ### Optimization Tips
244 | - Run backups during low-usage hours
245 | - Use SSD for `/config` if frequent backups
246 | - Adjust `SCHEDULE` based on server change frequency
247 | - Monitor `/output` disk usage
248 |
249 | ## 🔒 Security Considerations
250 |
251 | - Container runs as non-root user (guardian)
252 | - Docker socket is read-only mounted
253 | - Sensitive environment variables are masked
254 | - No network privileges required
255 | - Flash drive mounted read-only
256 | - Security scanning included in CI/CD
257 |
258 | ---
259 |
260 | **Ready to deploy!** 🚀 The application is now production-ready with complete CI/CD automation.
261 |
--------------------------------------------------------------------------------
/templates/backups.html:
--------------------------------------------------------------------------------
1 | {% extends "base.html" %}
2 |
3 | {% block title %}Backups - Unraid Config Guardian{% endblock %}
4 |
5 | {% block content %}
6 |
148 |
179 |
149 |
178 |
150 |
152 | Current Status
151 |
153 | {% if stats.status.running %}
154 |
177 |
155 |
156 | Backup in progress: {{ stats.status.message }} ({{ stats.status.progress }}%)
157 |
162 | {% elif stats.status.last_error %}
163 |
158 |
160 |
161 |
164 |
165 | Last backup failed: {{ stats.status.last_error }}
166 |
167 | {% else %}
168 |
169 |
170 | System ready for backup
171 | {% if stats.status.last_run %}
172 |
Last run: {{ stats.status.last_run[:19] }} 173 | {% endif %} 174 |
175 | {% endif %}
176 | Last run: {{ stats.status.last_run[:19] }} 173 | {% endif %} 174 |
7 |
12 |
13 |
8 |
11 | Backup Files
9 |Download and manage your generated backup files
10 |
14 |
32 |
33 | {% if backups %}
34 |
15 |
20 |
16 |
17 | Backup Location: /output (container) or configured output directory
18 |
19 |
21 |
24 |
25 | Download All (ZIP)
26 |
27 |
30 |
31 |
35 |
36 |
37 |
89 |
90 |
91 |
92 | | File | 39 |Size | 40 |Modified | 41 |Actions | 42 |
|---|---|---|---|
| 48 | 49 | {{ backup.name }} 50 | {% if backup.name.endswith('.json') %} 51 | Config 52 | {% elif backup.name.endswith('.yml') %} 53 | Compose 54 | {% elif backup.name.endswith('.sh') %} 55 | Script 56 | {% elif backup.name.endswith('.md') %} 57 | Docs 58 | {% endif %} 59 | | 60 |61 | {% if backup.size < 1024 %} 62 | {{ backup.size }} B 63 | {% elif backup.size < 1024 * 1024 %} 64 | {{ "%.1f"|format(backup.size / 1024) }} KB 65 | {% else %} 66 | {{ "%.1f"|format(backup.size / (1024 * 1024)) }} MB 67 | {% endif %} 68 | | 69 |70 | {{ backup.modified.strftime('%Y-%m-%d %H:%M:%S') }} 71 | | 72 |73 | 74 | Download 75 | 76 | {% if backup.name.endswith(('.json', '.yml', '.md')) %} 77 | 83 | {% endif %} 84 | | 85 |
93 |
122 |
123 | {% else %}
124 |
94 |
121 |
95 |
120 |
96 |
98 | File Descriptions
97 |
99 |
119 |
100 |
118 |
101 |
110 | unraid-config.json
102 |Complete system configuration including all containers, system info, and metadata.
103 | 104 |container-templates.zip
105 |NEW! XML templates for native Unraid restore. Extract to templates directory and use "Add Container".
106 | 107 |docker-compose.yml
108 |Docker Compose file for emergency fallback restore (not recommended for Unraid).
109 |
111 |
117 | restore.sh
112 |Automated restoration script that extracts templates and provides restore options.
113 | 114 |README.md
115 |Step-by-step recovery guide with both template and compose restore methods.
116 |
125 |
126 |
132 | {% endif %}
133 |
134 |
135 | No backup files found
127 |Generate your first backup to see files here.
128 | 131 |
136 |
154 |
155 | {% endblock %}
156 |
157 | {% block scripts %}
158 |
184 | {% endblock %}
185 |
--------------------------------------------------------------------------------
/src/config_diff.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | """
3 | Configuration change tracking for Unraid Config Guardian.
4 |
5 | Compares current configuration with previous backups to generate change logs.
6 | """
7 |
8 | import json
9 | import logging
10 | from datetime import datetime
11 | from pathlib import Path
12 | from typing import Any, Dict, List, Optional
13 |
14 | logger = logging.getLogger(__name__)
15 |
16 |
17 | def get_previous_config(output_dir: Path) -> Optional[Dict[str, Any]]:
18 | """
19 | Find and load the most recent previous config file.
20 |
21 | Args:
22 | output_dir: Directory where backups are stored
23 |
24 | Returns:
25 | Previous config dictionary or None if not found
26 | """
27 | config_file = output_dir / "unraid-config.json"
28 |
29 | if not config_file.exists():
30 | return None
31 |
32 | try:
33 | with open(config_file, "r") as f:
34 | config_data: Dict[str, Any] = json.load(f)
35 | return config_data
36 | except Exception as e:
37 | logger.warning(f"Could not read previous config: {e}")
38 | return None
39 |
40 |
41 | def compare_containers(
42 | old_containers: List[Dict], new_containers: List[Dict]
43 | ) -> Dict[str, List[str]]:
44 | """
45 | Compare container configurations between backups.
46 |
47 | Args:
48 | old_containers: Previous container configurations
49 | new_containers: Current container configurations
50 |
51 | Returns:
52 | Dictionary with added, removed, and modified containers
53 | """
54 | old_by_name = {c.get("name", "unknown"): c for c in old_containers}
55 | new_by_name = {c.get("name", "unknown"): c for c in new_containers}
56 |
57 | old_names = set(old_by_name.keys())
58 | new_names = set(new_by_name.keys())
59 |
60 | changes: Dict[str, List[str]] = {"added": [], "removed": [], "modified": []}
61 |
62 | # Find added containers
63 | for name in new_names - old_names:
64 | container = new_by_name[name]
65 | image = container.get("image", "unknown")
66 | changes["added"].append(f"+ {name} (image: {image})")
67 |
68 | # Find removed containers
69 | for name in old_names - new_names:
70 | container = old_by_name[name]
71 | image = container.get("image", "unknown")
72 | changes["removed"].append(f"- {name} (image: {image})")
73 |
74 | # Find modified containers
75 | for name in old_names & new_names:
76 | old_container = old_by_name[name]
77 | new_container = new_by_name[name]
78 |
79 | container_changes = compare_single_container(old_container, new_container)
80 | if container_changes:
81 | changes["modified"].append(f"~ {name}:")
82 | changes["modified"].extend(
83 | [f" {change}" for change in container_changes]
84 | )
85 |
86 | return changes
87 |
88 |
89 | def compare_single_container(old: Dict, new: Dict) -> List[str]:
90 | """
91 | Compare a single container configuration for changes.
92 |
93 | Args:
94 | old: Previous container configuration
95 | new: Current container configuration
96 |
97 | Returns:
98 | List of change descriptions
99 | """
100 | changes = []
101 |
102 | # Compare key fields
103 | fields_to_compare = [
104 | ("image", "Image"),
105 | ("status", "Status"),
106 | ("restart_policy", "Restart Policy"),
107 | ]
108 |
109 | for field, display_name in fields_to_compare:
110 | old_val = old.get(field, "N/A")
111 | new_val = new.get(field, "N/A")
112 | if old_val != new_val:
113 | changes.append(f"{display_name}: {old_val} → {new_val}")
114 |
115 | # Compare ports
116 | old_ports = set(old.get("ports", []))
117 | new_ports = set(new.get("ports", []))
118 | if old_ports != new_ports:
119 | if old_ports - new_ports:
120 | changes.append(f"Removed ports: {', '.join(old_ports - new_ports)}")
121 | if new_ports - old_ports:
122 | changes.append(f"Added ports: {', '.join(new_ports - old_ports)}")
123 |
124 | # Compare volumes (simplified)
125 | # Volumes are stored as strings like "/host/path:/container/path"
126 | old_volumes = set(old.get("volumes", []))
127 | new_volumes = set(new.get("volumes", []))
128 | if old_volumes != new_volumes:
129 | if old_volumes - new_volumes:
130 | changes.append(f"Removed volumes: {', '.join(old_volumes - new_volumes)}")
131 | if new_volumes - old_volumes:
132 | changes.append(f"Added volumes: {', '.join(new_volumes - old_volumes)}")
133 |
134 | # Compare environment variables (count only, not values for security)
135 | old_env_count = len(old.get("environment", {}))
136 | new_env_count = len(new.get("environment", {}))
137 | if old_env_count != new_env_count:
138 | changes.append(f"Environment variables: {old_env_count} → {new_env_count}")
139 |
140 | return changes
141 |
142 |
143 | def compare_system_info(old_system: Dict, new_system: Dict) -> List[str]:
144 | """
145 | Compare system information for changes.
146 |
147 | Args:
148 | old_system: Previous system information
149 | new_system: Current system information
150 |
151 | Returns:
152 | List of system changes
153 | """
154 | changes = []
155 |
156 | # Compare key system fields
157 | fields_to_compare = [
158 | ("unraid_version", "Unraid Version"),
159 | ("hostname", "Hostname"),
160 | ("kernel_version", "Kernel Version"),
161 | ]
162 |
163 | for field, display_name in fields_to_compare:
164 | old_val = old_system.get(field, "N/A")
165 | new_val = new_system.get(field, "N/A")
166 | if old_val != new_val:
167 | changes.append(f"{display_name}: {old_val} → {new_val}")
168 |
169 | # Compare disk array (simplified)
170 | old_disks = len(old_system.get("disks", []))
171 | new_disks = len(new_system.get("disks", []))
172 | if old_disks != new_disks:
173 | changes.append(f"Disk count: {old_disks} → {new_disks}")
174 |
175 | # Compare shares (simplified)
176 | old_shares = len(old_system.get("shares", []))
177 | new_shares = len(new_system.get("shares", []))
178 | if old_shares != new_shares:
179 | changes.append(f"Share count: {old_shares} → {new_shares}")
180 |
181 | return changes
182 |
183 |
184 | def generate_change_log(old_config: Dict[str, Any], new_config: Dict[str, Any]) -> str:
185 | """
186 | Generate a human-readable change log comparing two configurations.
187 |
188 | Args:
189 | old_config: Previous configuration
190 | new_config: Current configuration
191 |
192 | Returns:
193 | Formatted change log string
194 | """
195 | timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
196 | old_timestamp = old_config.get("system_info", {}).get("timestamp", "Unknown")
197 |
198 | log_lines = [
199 | "# Unraid Configuration Changes",
200 | f"Generated: {timestamp}",
201 | f"Previous backup: {old_timestamp}",
202 | "",
203 | "## Summary",
204 | "",
205 | ]
206 |
207 | # Compare containers
208 | container_changes = compare_containers(
209 | old_config.get("containers", []), new_config.get("containers", [])
210 | )
211 |
212 | total_changes = (
213 | len(container_changes["added"])
214 | + len(container_changes["removed"])
215 | + len(container_changes["modified"])
216 | )
217 |
218 | if total_changes == 0:
219 | log_lines.extend(
220 | [
221 | "✅ **No container changes detected**",
222 | "",
223 | "All containers remain unchanged since the last backup.",
224 | "",
225 | ]
226 | )
227 | else:
228 | log_lines.append(f"📦 **{total_changes} container changes detected**")
229 | log_lines.append("")
230 |
231 | # Added containers
232 | if container_changes["added"]:
233 | log_lines.append("### New Containers")
234 | log_lines.extend(container_changes["added"])
235 | log_lines.append("")
236 |
237 | # Removed containers
238 | if container_changes["removed"]:
239 | log_lines.append("### Removed Containers")
240 | log_lines.extend(container_changes["removed"])
241 | log_lines.append("")
242 |
243 | # Modified containers
244 | if container_changes["modified"]:
245 | log_lines.append("### Modified Containers")
246 | log_lines.extend(container_changes["modified"])
247 | log_lines.append("")
248 |
249 | # Compare system info
250 | system_changes = compare_system_info(
251 | old_config.get("system_info", {}), new_config.get("system_info", {})
252 | )
253 |
254 | if system_changes:
255 | log_lines.append("## System Changes")
256 | log_lines.append("")
257 | log_lines.extend([f"🖥️ {change}" for change in system_changes])
258 | log_lines.append("")
259 | else:
260 | log_lines.extend(
261 | ["## System Changes", "", "✅ **No system changes detected**", ""]
262 | )
263 |
264 | # Footer
265 | log_lines.extend(["---", "*Generated by Unraid Config Guardian*", ""])
266 |
267 | return "\n".join(log_lines)
268 |
269 |
270 | def create_change_log(output_dir: Path, new_config: Dict[str, Any]) -> Optional[str]:
271 | """
272 | Create a change log file by comparing with the previous backup.
273 |
274 | Args:
275 | output_dir: Directory where backups are stored
276 | new_config: Current configuration to compare
277 |
278 | Returns:
279 | Change log content or None if no previous config exists
280 | """
281 | logger.info("🔍 Checking for configuration changes...")
282 |
283 | # Get previous configuration
284 | old_config = get_previous_config(output_dir)
285 |
286 | changes_file = output_dir / "changes.log"
287 |
288 | if not old_config:
289 | # First backup - create initial change log
290 | timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
291 | container_count = len(new_config.get("containers", []))
292 | hostname = new_config.get("system_info", {}).get("hostname", "unknown")
293 |
294 | first_backup_log = f"""# Unraid Config Guardian - Change Log
295 |
296 | ## Initial Backup - {timestamp}
297 |
298 | **Server:** {hostname}
299 | **Containers:** {container_count}
300 |
301 | This is the first backup for this Unraid server. Future backups will show changes compared to this
302 | baseline.
303 |
304 | ### Summary
305 | - ✅ Initial configuration captured
306 | - ✅ {container_count} containers documented
307 | - ✅ System information recorded
308 |
309 | Future change logs will appear here when configurations are modified.
310 | """
311 | try:
312 | changes_file.write_text(first_backup_log)
313 | logger.info("✅ Initial change log created: changes.log")
314 | logger.info(f"Change log written to: {changes_file}")
315 | except Exception as e:
316 | logger.error(f"❌ Failed to write initial change log: {e}")
317 | logger.error(f"Attempted to write to: {changes_file}")
318 | return None
319 | return first_backup_log
320 |
321 | # Generate change log for subsequent backups
322 | change_log = generate_change_log(old_config, new_config)
323 |
324 | # Write change log file
325 | try:
326 | changes_file.write_text(change_log)
327 | logger.info("✅ Change log created: changes.log")
328 | logger.info(f"Change log written to: {changes_file}")
329 | except Exception as e:
330 | logger.error(f"❌ Failed to write change log: {e}")
331 | logger.error(f"Attempted to write to: {changes_file}")
332 | return None
333 |
334 | return change_log
335 |
--------------------------------------------------------------------------------
/src/web_gui.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | """
3 | Web GUI for Unraid Config Guardian
4 | FastAPI-based web interface for managing backups
5 | """
6 |
7 | import json
8 | import logging
9 | import os
10 | import zipfile
11 | from datetime import datetime
12 | from pathlib import Path
13 |
14 | import uvicorn
15 | from fastapi import BackgroundTasks, FastAPI, Form, Request
16 | from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
17 | from fastapi.templating import Jinja2Templates
18 |
19 | # Import version info
20 | from version import __version__
21 |
22 | # Import our main application
23 | try:
24 | from unraid_config_guardian import (
25 | create_readme,
26 | create_restore_script,
27 | generate_compose,
28 | get_containers,
29 | get_system_info,
30 | )
31 |
32 | DOCKER_AVAILABLE = True
33 | except Exception:
34 | DOCKER_AVAILABLE = False
35 |
36 | app = FastAPI(
37 | title="Unraid Config Guardian",
38 | description="Disaster recovery documentation for Unraid servers",
39 | )
40 |
41 | # Setup templates
42 | templates = Jinja2Templates(directory="templates")
43 |
44 | # Mock data for development when Docker isn't available
45 | MOCK_CONTAINERS = [
46 | {
47 | "name": "plex",
48 | "image": "lscr.io/linuxserver/plex:latest",
49 | "status": "running",
50 | "ports": ["32400:32400/tcp"],
51 | "volumes": ["/mnt/user/appdata/plex:/config", "/mnt/user/media:/media"],
52 | "environment": {"PUID": "99", "PGID": "100", "VERSION": "docker"},
53 | },
54 | {
55 | "name": "nginx",
56 | "image": "nginx:latest",
57 | "status": "running",
58 | "ports": ["80:80/tcp", "443:443/tcp"],
59 | "volumes": ["/mnt/user/appdata/nginx:/etc/nginx"],
60 | "environment": {"TZ": "America/New_York"},
61 | },
62 | {
63 | "name": "unifi-controller",
64 | "image": "lscr.io/linuxserver/unifi-controller:latest",
65 | "status": "exited",
66 | "ports": ["8080:8080/tcp", "8443:8443/tcp"],
67 | "volumes": ["/mnt/user/appdata/unifi:/config"],
68 | "environment": {"PUID": "99", "PGID": "100", "MONGO_PASSWORD": "***MASKED***"},
69 | },
70 | ]
71 |
72 | MOCK_SYSTEM_INFO = {
73 | "timestamp": datetime.now().isoformat(),
74 | "hostname": "unraid-server",
75 | "unraid_version": "6.12.4",
76 | "guardian_version": __version__,
77 | }
78 |
79 | # Global state for background tasks
80 | background_status = {
81 | "running": False,
82 | "progress": 0,
83 | "message": "Ready",
84 | "last_run": None,
85 | "last_error": None,
86 | }
87 |
88 |
89 | def get_containers_safe():
90 | """Get containers with fallback to mock data."""
91 | if not DOCKER_AVAILABLE:
92 | return MOCK_CONTAINERS
93 | try:
94 | return get_containers()
95 | except Exception as e:
96 | print(f"Docker not available, using mock data: {e}")
97 | return MOCK_CONTAINERS
98 |
99 |
100 | def get_system_info_safe():
101 | """Get system info with fallback to mock data."""
102 | if not DOCKER_AVAILABLE:
103 | return MOCK_SYSTEM_INFO
104 | try:
105 | return get_system_info()
106 | except Exception:
107 | return MOCK_SYSTEM_INFO
108 |
109 |
110 | @app.get("/", response_class=HTMLResponse)
111 | async def dashboard(request: Request):
112 | """Main dashboard."""
113 | # Get basic system info
114 | try:
115 | system_info = get_system_info_safe()
116 | containers = get_containers_safe()
117 |
118 | stats = {
119 | "total_containers": len(containers),
120 | "running_containers": len(
121 | [c for c in containers if c["status"] == "running"]
122 | ),
123 | "system_info": system_info,
124 | "last_backup": get_last_backup_info(),
125 | "status": background_status,
126 | }
127 | except Exception as e:
128 | stats = {"error": str(e), "status": background_status}
129 |
130 | return templates.TemplateResponse(
131 | "dashboard.html", {"request": request, "stats": stats}
132 | )
133 |
134 |
135 | @app.get("/containers", response_class=HTMLResponse)
136 | async def containers_page(request: Request):
137 | """Containers overview page."""
138 | try:
139 | containers = get_containers_safe()
140 | system_info = get_system_info_safe()
141 | stats = {"system_info": system_info}
142 | return templates.TemplateResponse(
143 | "containers.html",
144 | {"request": request, "containers": containers, "stats": stats},
145 | )
146 | except Exception as e:
147 | return templates.TemplateResponse(
148 | "error.html", {"request": request, "error": str(e)}
149 | )
150 |
151 |
152 | @app.get("/api/containers")
153 | async def api_containers():
154 | """API endpoint for container data."""
155 | try:
156 | containers = get_containers_safe()
157 | return {"containers": containers}
158 | except Exception as e:
159 | return JSONResponse(status_code=500, content={"error": str(e)})
160 |
161 |
162 | @app.post("/api/backup/start")
163 | async def start_backup(
164 | background_tasks: BackgroundTasks, output_dir: str = Form("/output")
165 | ):
166 | """Start backup process."""
167 | if background_status["running"]:
168 | return JSONResponse(
169 | status_code=409, content={"error": "Backup already running"}
170 | )
171 |
172 | background_tasks.add_task(run_backup, output_dir)
173 | return {"message": "Backup started", "status": "running"}
174 |
175 |
176 | @app.get("/api/backup/status")
177 | async def backup_status():
178 | """Get backup status."""
179 | return background_status
180 |
181 |
182 | @app.get("/api/system")
183 | async def api_system():
184 | """API endpoint for system information."""
185 | try:
186 | system_info = get_system_info_safe()
187 | return {"system": system_info}
188 | except Exception as e:
189 | return JSONResponse(status_code=500, content={"error": str(e)})
190 |
191 |
192 | @app.get("/backups")
193 | async def list_backups(request: Request):
194 | """List available backups."""
195 | output_dir = Path(os.getenv("OUTPUT_DIR", "/output"))
196 | backups = []
197 |
198 | if output_dir.exists():
199 | for item in output_dir.iterdir():
200 | if item.is_file():
201 | backups.append(
202 | {
203 | "name": item.name,
204 | "size": item.stat().st_size,
205 | "modified": datetime.fromtimestamp(item.stat().st_mtime),
206 | "path": str(item),
207 | }
208 | )
209 |
210 | backups.sort(key=lambda x: x["modified"], reverse=True) # type: ignore
211 |
212 | system_info = get_system_info_safe()
213 | stats = {"system_info": system_info}
214 |
215 | return templates.TemplateResponse(
216 | "backups.html", {"request": request, "backups": backups, "stats": stats}
217 | )
218 |
219 |
220 | @app.get("/download/{filename}")
221 | async def download_file(filename: str):
222 | """Download backup file."""
223 | output_dir = Path(os.getenv("OUTPUT_DIR", "/output"))
224 | file_path = output_dir / filename
225 |
226 | if file_path.exists() and file_path.is_file():
227 | return FileResponse(file_path, filename=filename)
228 |
229 | return JSONResponse(status_code=404, content={"error": "File not found"})
230 |
231 |
232 | @app.get("/download-all")
233 | async def download_all_files():
234 | """Download all backup files as a zip."""
235 | output_dir = Path(os.getenv("OUTPUT_DIR", "/output"))
236 |
237 | # Define the backup files to include
238 | backup_files = [
239 | "unraid-config.json",
240 | "docker-compose.yml",
241 | "restore.sh",
242 | "README.md",
243 | "container-templates.zip",
244 | ]
245 |
246 | # Check if any backup files exist
247 | existing_files = [f for f in backup_files if (output_dir / f).exists()]
248 |
249 | if not existing_files:
250 | return JSONResponse(status_code=404, content={"error": "No backup files found"})
251 |
252 | # Create temporary zip file
253 | import tempfile
254 |
255 | temp_dir = Path(tempfile.gettempdir())
256 | timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
257 | zip_filename = f"unraid-backup_{timestamp}.zip"
258 | zip_path = temp_dir / zip_filename
259 |
260 | try:
261 | with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
262 | for filename in existing_files:
263 | file_path = output_dir / filename
264 | if file_path.exists():
265 | zipf.write(file_path, filename)
266 |
267 | return FileResponse(
268 | zip_path, filename=zip_filename, media_type="application/zip"
269 | )
270 | except Exception as e:
271 | # Clean up on error
272 | if zip_path.exists():
273 | zip_path.unlink()
274 | return JSONResponse(
275 | status_code=500, content={"error": f"Failed to create zip: {str(e)}"}
276 | )
277 |
278 |
279 | async def run_backup(output_dir: str):
280 | """Run backup in background."""
281 | background_status.update(
282 | {
283 | "running": True,
284 | "progress": 0,
285 | "message": "Starting backup...",
286 | "last_error": None,
287 | }
288 | )
289 |
290 | try:
291 | # Step 1: Collect containers
292 | background_status.update(
293 | {"progress": 25, "message": "Collecting container information..."}
294 | )
295 | containers = get_containers_safe()
296 |
297 | # Step 2: Get system info
298 | background_status.update(
299 | {"progress": 50, "message": "Collecting system information..."}
300 | )
301 | system_info = get_system_info_safe()
302 |
303 | # Step 3: Generate compose
304 | background_status.update(
305 | {"progress": 75, "message": "Generating docker-compose..."}
306 | )
307 | if DOCKER_AVAILABLE:
308 | compose = generate_compose(containers)
309 | else:
310 | # Mock compose for development
311 | compose = {
312 | "version": "3.8",
313 | "services": {
314 | "plex": {
315 | "image": "lscr.io/linuxserver/plex:latest",
316 | "container_name": "plex",
317 | "restart": "unless-stopped",
318 | "ports": ["32400:32400"],
319 | "volumes": ["/mnt/user/appdata/plex:/config"],
320 | "environment": {"PUID": "99", "PGID": "100"},
321 | }
322 | },
323 | }
324 |
325 | # Step 4: Collect templates
326 | background_status.update(
327 | {"progress": 80, "message": "Collecting XML templates..."}
328 | )
329 | templates = []
330 | if DOCKER_AVAILABLE:
331 | from unraid_config_guardian import get_container_templates
332 |
333 | templates = get_container_templates()
334 |
335 | # Step 5: Write files
336 | background_status.update({"progress": 90, "message": "Writing backup files..."})
337 |
338 | output_path = Path(output_dir)
339 | output_path.mkdir(parents=True, exist_ok=True, mode=0o755)
340 | # Set permissions explicitly for Unraid compatibility
341 | os.chmod(output_path, 0o755)
342 |
343 | # Create complete config
344 | config = {
345 | "system_info": system_info,
346 | "containers": containers,
347 | "templates": templates,
348 | }
349 |
350 | # Generate change log if available
351 | change_log_content = None
352 | if DOCKER_AVAILABLE:
353 | try:
354 | from config_diff import create_change_log
355 |
356 | logging.info("Generating configuration change log...")
357 | change_log_content = create_change_log(output_path, config)
358 | if change_log_content:
359 | logging.info("Change log generated successfully")
360 | else:
361 | logging.info("No change log generated (first backup or no changes)")
362 | except ImportError:
363 | logging.warning(
364 | "Change log functionality not available (config_diff module not found)"
365 | )
366 | except Exception as e:
367 | logging.error(f"Error generating change log: {e}")
368 |
369 | # Write files
370 | import yaml
371 |
372 | if DOCKER_AVAILABLE:
373 | restore_script = create_restore_script(system_info)
374 | readme = create_readme(system_info, len(containers))
375 | else:
376 | # Mock scripts for development
377 | restore_script = """#!/bin/bash
378 | echo "🔄 Restoring Unraid setup (DEVELOPMENT MODE)..."
379 | docker-compose up -d
380 | echo "✅ Restore complete!"
381 | """
382 | readme = f"""# Unraid Backup Documentation (DEVELOPMENT MODE)
383 |
384 | **Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
385 | **Server:** {system_info['hostname']}
386 | **Containers:** {len(containers)}
387 |
388 | This is a development/demo backup.
389 | """
390 |
391 | files = {
392 | "unraid-config.json": json.dumps(config, indent=2),
393 | "docker-compose.yml": (
394 | f"# Generated by Config Guardian\n# {system_info['timestamp']}\n\n"
395 | + yaml.dump(compose, default_flow_style=False)
396 | ),
397 | "restore.sh": restore_script,
398 | "README.md": readme,
399 | }
400 |
401 | for filename, content in files.items():
402 | (output_path / filename).write_text(content)
403 |
404 | # Make restore script executable
405 | os.chmod(output_path / "restore.sh", 0o755)
406 |
407 | # Create templates zip if templates exist
408 | if templates and DOCKER_AVAILABLE:
409 | background_status.update(
410 | {"progress": 95, "message": "Creating templates zip..."}
411 | )
412 | from unraid_config_guardian import create_templates_zip
413 |
414 | zip_result = create_templates_zip(templates, output_path)
415 | if zip_result:
416 | files["container-templates.zip"] = "Binary file"
417 |
418 | background_status.update(
419 | {
420 | "running": False,
421 | "progress": 100,
422 | "message": f"Backup completed! Generated {len(files)} files.",
423 | "last_run": datetime.now().isoformat(),
424 | }
425 | )
426 |
427 | except Exception as e:
428 | background_status.update(
429 | {
430 | "running": False,
431 | "progress": 0,
432 | "message": "Backup failed",
433 | "last_error": str(e),
434 | }
435 | )
436 |
437 |
438 | def get_last_backup_info():
439 | """Get information about the last backup."""
440 | output_dir = Path(os.getenv("OUTPUT_DIR", "/output"))
441 | config_file = output_dir / "unraid-config.json"
442 |
443 | if config_file.exists():
444 | try:
445 | with open(config_file) as f:
446 | config = json.load(f)
447 |
448 | backup_info = {
449 | "timestamp": config.get("system_info", {}).get("timestamp"),
450 | "containers": len(config.get("containers", [])),
451 | "size": config_file.stat().st_size,
452 | "has_changes": False,
453 | "changes_summary": "No changes detected",
454 | }
455 |
456 | # Check for changes.log file
457 | changes_file = output_dir / "changes.log"
458 | if changes_file.exists():
459 | try:
460 | changes_content = changes_file.read_text()
461 | backup_info["has_changes"] = True
462 |
463 | # Extract summary from changes file
464 | lines = changes_content.split("\n")
465 | for line in lines:
466 | if "changes detected" in line:
467 | backup_info["changes_summary"] = line.strip().replace(
468 | "**", ""
469 | )
470 | break
471 | else:
472 | backup_info[
473 | "changes_summary"
474 | ] = "Changes detected - see changes.log"
475 |
476 | except Exception:
477 | backup_info[
478 | "changes_summary"
479 | ] = "Changes file exists but couldn't be read"
480 |
481 | return backup_info
482 | except Exception:
483 | pass
484 |
485 | return None
486 |
487 |
488 | def main():
489 | """Run the web server."""
490 | port = int(os.getenv("WEB_PORT", 7842))
491 | host = os.getenv("WEB_HOST", "0.0.0.0")
492 |
493 | print(f"🌐 Starting Unraid Config Guardian Web GUI on http://{host}:{port}")
494 | print("🔗 Access via: http://your-unraid-ip:7842")
495 |
496 | uvicorn.run("web_gui:app", host=host, port=port, reload=False, access_log=True)
497 |
498 |
499 | if __name__ == "__main__":
500 | main()
501 |
--------------------------------------------------------------------------------
/src/web_gui_dev.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | """
3 | Development version of Web GUI that handles Docker connection gracefully
4 | """
5 |
6 | import asyncio
7 | import json
8 | import logging
9 | import os
10 | import zipfile
11 | from datetime import datetime
12 | from pathlib import Path
13 |
14 | import uvicorn
15 | from fastapi import BackgroundTasks, FastAPI, Form, Request
16 | from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
17 | from fastapi.templating import Jinja2Templates
18 |
19 | # Import version info
20 | from version import __version__
21 |
22 | # Mock container data for development when Docker isn't available
23 | MOCK_CONTAINERS = [
24 | {
25 | "name": "plex",
26 | "image": "lscr.io/linuxserver/plex:latest",
27 | "status": "running",
28 | "ports": ["32400:32400/tcp"],
29 | "volumes": ["/mnt/user/appdata/plex:/config", "/mnt/user/media:/media"],
30 | "environment": {"PUID": "99", "PGID": "100", "VERSION": "docker"},
31 | },
32 | {
33 | "name": "nginx",
34 | "image": "nginx:latest",
35 | "status": "running",
36 | "ports": ["80:80/tcp", "443:443/tcp"],
37 | "volumes": ["/mnt/user/appdata/nginx:/etc/nginx"],
38 | "environment": {"TZ": "America/New_York"},
39 | },
40 | {
41 | "name": "unifi-controller",
42 | "image": "lscr.io/linuxserver/unifi-controller:latest",
43 | "status": "exited",
44 | "ports": ["8080:8080/tcp", "8443:8443/tcp"],
45 | "volumes": ["/mnt/user/appdata/unifi:/config"],
46 | "environment": {"PUID": "99", "PGID": "100", "MONGO_PASSWORD": "***MASKED***"},
47 | },
48 | ]
49 |
50 | MOCK_SYSTEM_INFO = {
51 | "timestamp": datetime.now().isoformat(),
52 | "hostname": "unraid-server",
53 | "unraid_version": "6.12.4",
54 | "guardian_version": __version__,
55 | }
56 |
57 | app = FastAPI(
58 | title="Unraid Config Guardian",
59 | description="Disaster recovery documentation for Unraid servers",
60 | )
61 |
62 | # Setup templates
63 | templates = Jinja2Templates(directory="templates")
64 |
65 | # Global state for background tasks
66 | background_status = {
67 | "running": False,
68 | "progress": 0,
69 | "message": "Ready",
70 | "last_run": None,
71 | "last_error": None,
72 | }
73 |
74 |
75 | def get_containers_safe():
76 | """Get containers with fallback to mock data."""
77 | try:
78 | # Try to import and use real Docker client
79 | from unraid_config_guardian import get_containers
80 |
81 | return get_containers()
82 | except Exception as e:
83 | print(f"Docker not available, using mock data: {e}")
84 | return MOCK_CONTAINERS
85 |
86 |
87 | def get_system_info_safe():
88 | """Get system info with fallback to mock data."""
89 | try:
90 | from unraid_config_guardian import get_system_info
91 |
92 | return get_system_info()
93 | except Exception:
94 | return MOCK_SYSTEM_INFO
95 |
96 |
97 | @app.get("/", response_class=HTMLResponse)
98 | async def dashboard(request: Request):
99 | """Main dashboard."""
100 | try:
101 | system_info = get_system_info_safe()
102 | containers = get_containers_safe()
103 |
104 | stats = {
105 | "total_containers": len(containers),
106 | "running_containers": len(
107 | [c for c in containers if c["status"] == "running"]
108 | ),
109 | "system_info": system_info,
110 | "last_backup": get_last_backup_info(),
111 | "status": background_status,
112 | }
113 | except Exception as e:
114 | stats = {"error": str(e), "status": background_status}
115 |
116 | return templates.TemplateResponse(
117 | "dashboard.html", {"request": request, "stats": stats}
118 | )
119 |
120 |
121 | @app.get("/containers", response_class=HTMLResponse)
122 | async def containers_page(request: Request):
123 | """Containers overview page."""
124 | try:
125 | containers = get_containers_safe()
126 | stats = {"system_info": MOCK_SYSTEM_INFO}
127 | return templates.TemplateResponse(
128 | "containers.html",
129 | {"request": request, "containers": containers, "stats": stats},
130 | )
131 | except Exception as e:
132 | return templates.TemplateResponse(
133 | "error.html", {"request": request, "error": str(e)}
134 | )
135 |
136 |
137 | @app.get("/api/containers")
138 | async def api_containers():
139 | """API endpoint for container data."""
140 | try:
141 | containers = get_containers_safe()
142 | return {"containers": containers}
143 | except Exception as e:
144 | return JSONResponse(status_code=500, content={"error": str(e)})
145 |
146 |
147 | @app.post("/api/backup/start")
148 | async def start_backup(
149 | background_tasks: BackgroundTasks, output_dir: str = Form("/output")
150 | ):
151 | """Start backup process."""
152 | if background_status["running"]:
153 | return JSONResponse(
154 | status_code=409, content={"error": "Backup already running"}
155 | )
156 |
157 | background_tasks.add_task(run_backup_mock, output_dir)
158 | return {"message": "Backup started", "status": "running"}
159 |
160 |
161 | @app.get("/api/backup/status")
162 | async def backup_status():
163 | """Get backup status."""
164 | return background_status
165 |
166 |
167 | @app.get("/api/system")
168 | async def api_system():
169 | """API endpoint for system information."""
170 | try:
171 | system_info = get_system_info_safe()
172 | return {"system": system_info}
173 | except Exception as e:
174 | return JSONResponse(status_code=500, content={"error": str(e)})
175 |
176 |
177 | @app.get("/backups")
178 | async def list_backups(request: Request):
179 | """List available backups."""
180 | output_dir = Path(os.getenv("OUTPUT_DIR", "./output"))
181 | backups = []
182 |
183 | if output_dir.exists():
184 | for item in output_dir.iterdir():
185 | if item.is_file():
186 | backups.append(
187 | {
188 | "name": item.name,
189 | "size": item.stat().st_size,
190 | "modified": datetime.fromtimestamp(item.stat().st_mtime),
191 | "path": str(item),
192 | }
193 | )
194 |
195 | backups.sort(key=lambda x: x["modified"], reverse=True) # type: ignore
196 |
197 | stats = {"system_info": MOCK_SYSTEM_INFO}
198 |
199 | return templates.TemplateResponse(
200 | "backups.html", {"request": request, "backups": backups, "stats": stats}
201 | )
202 |
203 |
204 | @app.get("/download/{filename}")
205 | async def download_file(filename: str):
206 | """Download backup file."""
207 | output_dir = Path(os.getenv("OUTPUT_DIR", "./output"))
208 | file_path = output_dir / filename
209 |
210 | if file_path.exists() and file_path.is_file():
211 | return FileResponse(file_path, filename=filename)
212 |
213 | return JSONResponse(status_code=404, content={"error": "File not found"})
214 |
215 |
216 | @app.get("/download-all")
217 | async def download_all_files():
218 | """Download all backup files as a zip."""
219 | output_dir = Path(os.getenv("OUTPUT_DIR", "./output"))
220 |
221 | # Define the backup files to include
222 | backup_files = [
223 | "unraid-config.json",
224 | "docker-compose.yml",
225 | "restore.sh",
226 | "README.md",
227 | "container-templates.zip",
228 | ]
229 |
230 | # Check if any backup files exist
231 | existing_files = [f for f in backup_files if (output_dir / f).exists()]
232 |
233 | if not existing_files:
234 | return JSONResponse(status_code=404, content={"error": "No backup files found"})
235 |
236 | # Create temporary zip file
237 | import tempfile
238 |
239 | temp_dir = Path(tempfile.gettempdir())
240 | timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
241 | zip_filename = f"unraid-backup_{timestamp}.zip"
242 | zip_path = temp_dir / zip_filename
243 |
244 | try:
245 | with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
246 | for filename in existing_files:
247 | file_path = output_dir / filename
248 | if file_path.exists():
249 | zipf.write(file_path, filename)
250 |
251 | return FileResponse(
252 | zip_path, filename=zip_filename, media_type="application/zip"
253 | )
254 | except Exception as e:
255 | # Clean up on error
256 | if zip_path.exists():
257 | zip_path.unlink()
258 | return JSONResponse(
259 | status_code=500, content={"error": f"Failed to create zip: {str(e)}"}
260 | )
261 |
262 |
263 | async def run_backup_mock(output_dir: str):
264 | """Mock backup process for development."""
265 |
266 | background_status.update(
267 | {
268 | "running": True,
269 | "progress": 0,
270 | "message": "Starting backup...",
271 | "last_error": None,
272 | }
273 | )
274 |
275 | try:
276 | # Simulate backup process
277 | await asyncio.sleep(1)
278 | background_status.update(
279 | {"progress": 25, "message": "Collecting container information..."}
280 | )
281 |
282 | await asyncio.sleep(1)
283 | background_status.update(
284 | {"progress": 40, "message": "Collecting system information..."}
285 | )
286 |
287 | await asyncio.sleep(1)
288 | background_status.update(
289 | {"progress": 60, "message": "Collecting XML templates..."}
290 | )
291 |
292 | await asyncio.sleep(1)
293 | background_status.update(
294 | {"progress": 80, "message": "Generating docker-compose..."}
295 | )
296 |
297 | await asyncio.sleep(1)
298 | background_status.update({"progress": 90, "message": "Writing backup files..."})
299 |
300 | # Create mock backup files
301 | output_path = Path(output_dir)
302 | output_path.mkdir(parents=True, exist_ok=True, mode=0o755)
303 | # Set permissions explicitly for Unraid compatibility
304 | os.chmod(output_path, 0o755)
305 |
306 | # Generate change log if available
307 | change_log_content = None
308 | try:
309 | from config_diff import create_change_log
310 |
311 | logging.info("Generating configuration change log...")
312 | config = {"system_info": MOCK_SYSTEM_INFO, "containers": MOCK_CONTAINERS}
313 | change_log_content = create_change_log(output_path, config)
314 | if change_log_content:
315 | logging.info("Change log generated successfully")
316 | else:
317 | logging.info("No change log generated (first backup or no changes)")
318 | except ImportError:
319 | logging.warning(
320 | "Change log functionality not available (config_diff module not found)"
321 | )
322 | except Exception as e:
323 | logging.error(f"Error generating change log: {e}")
324 |
325 | # Mock files
326 | files = {
327 | "unraid-config.json": json.dumps(
328 | {"system_info": MOCK_SYSTEM_INFO, "containers": MOCK_CONTAINERS},
329 | indent=2,
330 | ),
331 | "docker-compose.yml": """# Generated by Unraid Config Guardian
332 | version: '3.8'
333 |
334 | services:
335 | plex:
336 | image: lscr.io/linuxserver/plex:latest
337 | container_name: plex
338 | restart: unless-stopped
339 | ports:
340 | - "32400:32400"
341 | volumes:
342 | - /mnt/user/appdata/plex:/config
343 | - /mnt/user/media:/media
344 | environment:
345 | - PUID=99
346 | - PGID=100
347 | """,
348 | "restore.sh": """#!/bin/bash
349 | # Unraid Config Guardian - Restore Script (Mock Development Version)
350 |
351 | echo "🔄 Restoring Unraid setup..."
352 |
353 | # Function to restore XML templates
354 | restore_templates() {
355 | if [ -f "container-templates.zip" ]; then
356 | echo "📋 Restoring XML templates..."
357 | mkdir -p /boot/config/plugins/dockerMan/templates-user
358 | unzip -o container-templates.zip -d /boot/config/plugins/dockerMan/templates-user
359 | if [ $? -eq 0 ]; then
360 | echo "✅ XML templates restored"
361 | echo "ℹ️ Templates will appear in 'Add Container' dropdown"
362 | else
363 | echo "❌ Failed to extract templates"
364 | fi
365 | else
366 | echo "ℹ️ No container-templates.zip found - skipping template restore"
367 | fi
368 | }
369 |
370 | # Main restore process
371 | echo "📋 UNRAID RESTORE OPTIONS:"
372 | echo "Option 1: Restore XML Templates (Recommended)"
373 | restore_templates
374 |
375 | echo ""
376 | echo "Option 2: Docker-Compose Fallback (Emergency only)"
377 | if [ -f "docker-compose.yml" ]; then
378 | if command -v docker-compose &> /dev/null || docker compose version &> /dev/null; then
379 | echo "💡 Run: docker-compose up -d (or docker compose up -d)"
380 | else
381 | echo "❌ Docker Compose not available"
382 | fi
383 | fi
384 |
385 | echo ""
386 | echo "✅ Restore process complete!"
387 | echo "📋 Next: Go to Docker tab → Add Container → Select templates"
388 | """,
389 | "README.md": """# Unraid Backup Documentation
390 |
391 | **Generated:** Mock Development Data
392 | **Server:** unraid-server
393 | **Containers:** 3
394 |
395 | ## Quick Recovery (Recommended: Unraid Templates)
396 |
397 | 1. Install fresh Unraid
398 | 2. Restore flash drive from backup
399 | 3. Set up disk array
400 | 4. Run: `bash restore.sh` (restores XML templates)
401 | 5. Go to Docker tab → Add Container → Select your templates
402 | 6. Configure paths and restore appdata from backup
403 |
404 | ## Files
405 |
406 | - `unraid-config.json` - Complete system configuration
407 | - `container-templates.zip` - XML templates for native Unraid restore
408 | - `docker-compose.yml` - Fallback container definitions
409 | - `restore.sh` - Automated restoration script
410 | - `README.md` - This file
411 |
412 | ## Restore Methods
413 |
414 | ### Method 1: Native Unraid Templates (Recommended)
415 | ```bash
416 | bash restore.sh # Extracts templates to /boot/config/plugins/dockerMan/templates-user
417 | ```
418 | Then use Unraid WebUI to add containers from templates.
419 |
420 | ### Method 2: Docker Compose (Emergency Fallback)
421 | ```bash
422 | docker-compose up -d # Or: docker compose up -d
423 | ```
424 | Note: Bypasses Unraid's container management system.
425 |
426 | Keep this documentation safe and test your restore process!
427 | """,
428 | }
429 |
430 | for filename, content in files.items():
431 | (output_path / filename).write_text(content)
432 |
433 | # Create a mock container-templates.zip with sample XML templates
434 | template_zip_path = output_path / "container-templates.zip"
435 | try:
436 | with zipfile.ZipFile(template_zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
437 | # Mock Plex template
438 | plex_template = """
439 |
137 |
152 |
153 |