Skip to content

Commit 080c6c0

Browse files
feat: Add comprehensive debug features and enhanced Docker logging
🎯 Version 1.6.0 Release - Major debugging and logging improvements ✨ New Features: - Comprehensive DebugService with system diagnostics - 9 debug API endpoints (/api/debug/*) - Enhanced Docker logging with user-friendly formats - Debug mode environment variable controls - Local development Dockerfile (Dockerfile.local) - Debug management scripts (debug.sh) 🔧 Technical Improvements: - Winston logger with Docker-friendly console output - Supervisord configured for stdout/stderr logging - Enhanced error handling and request logging - System monitoring and SSH connection testing - Automatic log cleanup and rotation 📊 Logging Enhancements: - Structured JSON logging to files - Human-readable console output for Docker logs - Debug-level logging with timestamp formatting - Request/response logging with performance metrics - Environment-aware log levels 🛠️ Infrastructure Updates: - GitHub Actions workflow with dynamic changelog extraction - Multi-platform Docker build support improvements - Enhanced build scripts with better error handling - Docker Compose debug environment variables - Improved local development setup 🧹 Cleanup: - Removed temporary documentation files - Updated .gitignore for debug logs - Consolidated debug functionality into main compose files This release significantly improves troubleshooting capabilities and makes logs easily accessible via Docker logs instead of requiring API calls.
1 parent 3b09244 commit 080c6c0

18 files changed

Lines changed: 2065 additions & 126 deletions

.env.example

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
# HoleSafe Environment Variables
1+
# PiHoleVault Environment Configuration
2+
# Copy this file to .env and modify as needed
23

34
# Discord Webhook URL for notifications (optional)
45
# Get this from your Discord server: Settings > Integrations > Webhooks
@@ -10,3 +11,40 @@ NODE_ENV=production
1011
# Data directories
1112
DATA_DIR=/app/data
1213
BACKUP_DIR=/app/backups
14+
15+
# Debug Configuration
16+
# Set DEBUG_MODE=true to enable comprehensive debugging features
17+
DEBUG_MODE=false
18+
19+
# Logging levels: error, warn, info, debug
20+
# LOG_LEVEL controls general application logging
21+
LOG_LEVEL=info
22+
23+
# DEBUG_LEVEL controls debug service logging (only used when DEBUG_MODE=true)
24+
DEBUG_LEVEL=debug
25+
26+
# ====== DEBUG MODE USAGE ======
27+
# To enable debug mode, set:
28+
# DEBUG_MODE=true
29+
# LOG_LEVEL=debug
30+
# DEBUG_LEVEL=debug
31+
#
32+
# Debug mode provides:
33+
# - Detailed logging with stack traces
34+
# - Debug API endpoints at /api/debug/*
35+
# - Enhanced error reporting
36+
# - System information collection
37+
# - SSH connectivity testing
38+
# - Log analysis tools
39+
#
40+
# Available debug endpoints when DEBUG_MODE=true:
41+
# - http://localhost:3000/api/debug/status
42+
# - http://localhost:3000/api/debug/system-info
43+
# - http://localhost:3000/api/debug/health-check
44+
# - http://localhost:3000/api/debug/logs
45+
# - http://localhost:3000/api/debug/log-analysis
46+
# - http://localhost:3000/api/debug/report
47+
# - http://localhost:3000/api/debug/files
48+
# - http://localhost:3000/api/debug/test-ssh
49+
# - http://localhost:3000/api/debug/environment
50+
# ==============================

.github/workflows/create-release.yml

Lines changed: 111 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
name: Create Release
22

3+
# This workflow automatically creates GitHub releases when the version file is updated
4+
# It extracts changelog information from README.md (preferred) or CHANGELOG.md (fallback)
5+
# Version information is read from the 'version' file in the repository root
6+
37
on:
48
push:
59
branches: [ main ]
@@ -45,94 +49,117 @@ jobs:
4549
if: steps.check.outputs.changed == 'true'
4650
run: |
4751
VERSION="${{ steps.version.outputs.version }}"
52+
echo "Extracting changelog for version $VERSION from README.md"
53+
54+
# Try to extract changelog from README.md for the current version
55+
if [ -f "README.md" ]; then
56+
# Extract the changelog section for the current version from README.md
57+
# Look for the version section pattern: ## 🎯 Version X.X.X Release
58+
CHANGELOG=$(awk -v version="$VERSION" '
59+
BEGIN { found=0; collecting=0; content="" }
60+
61+
# Match the version header pattern
62+
/^## 🎯 Version [0-9]+\.[0-9]+\.[0-9]+ Release/ {
63+
if ($0 ~ "Version " version " Release") {
64+
found=1
65+
collecting=1
66+
content = content $0 "\n"
67+
next
68+
}
69+
if (found && collecting) {
70+
# Stop collecting when we hit another version section
71+
collecting=0
72+
}
73+
}
74+
75+
# Collect content until we hit another ## heading (but not ###)
76+
/^## / && !/^## 🎯 Version [0-9]+\.[0-9]+\.[0-9]+ Release/ {
77+
if (collecting) {
78+
collecting=0
79+
}
80+
}
81+
82+
# Collect all lines while in the target version section
83+
collecting && !/^## 🎯 Version [0-9]+\.[0-9]+\.[0-9]+ Release/ {
84+
content = content $0 "\n"
85+
}
86+
87+
END {
88+
if (found) {
89+
print content
90+
} else {
91+
print ""
92+
}
93+
}
94+
' README.md)
95+
96+
# If we found content in README.md, use it
97+
if [ -n "$CHANGELOG" ] && [ "$CHANGELOG" != " " ]; then
98+
echo "Found changelog in README.md for version $VERSION"
99+
# Add footer with full changelog link
100+
FOOTER="\n\n**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/v$VERSION)"
101+
CHANGELOG="$CHANGELOG$FOOTER"
102+
else
103+
echo "No specific changelog found in README.md for version $VERSION, checking CHANGELOG.md"
104+
105+
# Fallback: Try to extract from CHANGELOG.md if it exists
106+
if [ -f "CHANGELOG.md" ]; then
107+
CHANGELOG_MD=$(awk -v version="$VERSION" '
108+
BEGIN { found=0; collecting=0; content="" }
109+
110+
# Match version header in CHANGELOG.md: ## [X.X.X] - YYYY-MM-DD
111+
/^## \[/ {
112+
if ($0 ~ "\\[" version "\\]") {
113+
found=1
114+
collecting=1
115+
content = content $0 "\n"
116+
next
117+
}
118+
if (found && collecting) {
119+
collecting=0
120+
}
121+
}
122+
123+
# Stop at next version section
124+
/^## \[/ && collecting {
125+
collecting=0
126+
}
127+
128+
# Collect content while in target version
129+
collecting {
130+
content = content $0 "\n"
131+
}
132+
133+
END {
134+
if (found) {
135+
print content
136+
}
137+
}
138+
' CHANGELOG.md)
139+
140+
if [ -n "$CHANGELOG_MD" ]; then
141+
CHANGELOG="## 🚀 PiHoleVault v$VERSION\n\n$CHANGELOG_MD\n\n**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/v$VERSION)"
142+
else
143+
# Final fallback: Generic changelog
144+
CHANGELOG="## 🚀 PiHoleVault v$VERSION\n\nAutomatically generated release from version file update.\n\n### Changes\n- Updated to version $VERSION\n- See commit history for detailed changes\n\n**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/v$VERSION)"
145+
fi
146+
else
147+
# No CHANGELOG.md, use generic
148+
CHANGELOG="## 🚀 PiHoleVault v$VERSION\n\nAutomatically generated release from version file update.\n\n### Changes\n- Updated to version $VERSION\n- See commit history for detailed changes\n\n**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/v$VERSION)"
149+
fi
150+
fi
151+
else
152+
echo "README.md not found, generating generic changelog"
153+
CHANGELOG="## 🚀 PiHoleVault v$VERSION\n\nAutomatically generated release from version file update.\n\n**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/v$VERSION)"
154+
fi
48155
49-
# Create a comprehensive changelog based on recent commits and version
50-
case "$VERSION" in
51-
"1.5.0")
52-
CHANGELOG=$(cat << 'EOF'
53-
## 🚀 PiHoleVault v1.5.0 - Multi-Architecture Support
54-
55-
This release introduces comprehensive multi-architecture support, enabling PiHoleVault to run natively on a wide range of devices and platforms.
56-
57-
### ✨ New Features
58-
59-
- **🌍 Multi-Architecture Docker Images**: Native support for AMD64, ARM64, and ARMv7 architectures
60-
- **🏗️ Enhanced Build System**: New Docker Buildx-based build pipeline with GitHub Actions integration
61-
- **🛠️ Local Development Tools**: New `build-multiarch.sh` script for local multi-platform development and testing
62-
- **📦 Automated CI/CD**: GitHub Actions automatically builds and pushes multi-architecture images to Docker Hub
63-
- **🔄 Release Automation**: Automatic GitHub releases when version file is updated
64-
65-
### 🏗️ Architecture Support
66-
67-
| Platform | Architecture | Compatible Devices |
68-
|----------|-------------|-------------------|
69-
| `linux/amd64` | x86_64 | Intel/AMD servers, desktop PCs |
70-
| `linux/arm64` | aarch64 | Raspberry Pi 4+, Apple Silicon, AWS Graviton |
71-
| `linux/arm/v7` | armv7l | Raspberry Pi 3, older ARM devices |
72-
73-
### 🔧 Technical Improvements
74-
75-
- **📋 OCI Image Labels**: Added comprehensive metadata labels to Docker images
76-
- **⚡ Build Optimization**: Improved cross-platform compilation with build cache optimization
77-
- **🏷️ Version Synchronization**: Synchronized versions across all package.json files
78-
- **📖 Enhanced Documentation**: Updated README with multi-architecture information and usage examples
79-
- **🚨 Legacy Script Deprecation**: Updated legacy build scripts with proper migration guidance
80-
81-
### 🔄 Migration & Compatibility
82-
83-
- **✅ Zero Breaking Changes**: Existing deployments continue to work seamlessly
84-
- **🔄 Automatic Platform Detection**: Docker automatically selects the correct architecture
85-
- **⚡ Performance Improvements**: ARM devices now use native images instead of emulation
86-
- **📦 Single Image Tag**: Same `theinfamoustoto/piholevault:latest` works across all platforms
87-
88-
### 🛠️ Development Workflow
89-
90-
**For Production Deployment:**
91-
1. Make code changes
92-
2. Test locally: `./build-multiarch.sh build`
93-
3. Push to Git: `git push origin main`
94-
4. GitHub Actions automatically builds and deploys multi-arch images
95-
96-
**For Local Development:**
97-
1. Setup: `./build-multiarch.sh setup`
98-
2. Build & Test: `./build-multiarch.sh build`
99-
100-
### 📋 Verification
101-
102-
To verify multi-architecture support:
103-
```bash
104-
# Check available platforms
105-
docker buildx imagetools inspect theinfamoustoto/piholevault:latest
106-
107-
# Test specific platform
108-
docker run --rm --platform=linux/arm64 theinfamoustoto/piholevault:latest echo "ARM64 works!"
109-
```
110-
111-
### 🙏 Acknowledgments
112-
113-
This release significantly expands PiHoleVault's compatibility and deployment options. Special thanks to the Docker Buildx team and GitHub Actions for making multi-architecture builds seamless.
114-
115-
---
116-
117-
**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/compare/v1.4.0...v1.5.0)
118-
EOF
119-
)
120-
;;
121-
*)
122-
# Generic changelog for other versions
123-
CHANGELOG="## Release $VERSION
124-
125-
Automatically generated release from version file update.
126-
127-
See commit history for detailed changes.
128-
129-
**Full Changelog**: [View all changes](https://github.com/TheInfamousToTo/PiHoleVault/commits/$VERSION)"
130-
;;
131-
esac
156+
# Debug output
157+
echo "Generated changelog preview:"
158+
echo "$CHANGELOG" | head -10
132159
133160
# Save changelog to output (GitHub Actions multiline string)
134161
echo "changelog<<EOF" >> $GITHUB_OUTPUT
135-
echo "$CHANGELOG" >> $GITHUB_OUTPUT
162+
printf "%b\n" "$CHANGELOG" >> $GITHUB_OUTPUT
136163
echo "EOF" >> $GITHUB_OUTPUT
137164
138165
- name: Check if tag exists

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,5 @@ Thumbs.db
4141
/data/*.log
4242
/backups/*
4343
!/backups/.gitkeep
44+
debug-logs/
4445
notes.txt

CHANGELOG.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,65 @@
22

33
All notable changes to PiHoleVault will be documented in this file.
44

5+
## [1.6.0] - 2025-08-03
6+
7+
### 🐛 Comprehensive Debug Features
8+
9+
#### ✨ New Features
10+
11+
- **Debug Mode Environment Control**:
12+
- `DEBUG_MODE` environment variable for easy enable/disable
13+
- `LOG_LEVEL` and `DEBUG_LEVEL` for granular logging control
14+
- Debug configuration in docker-compose.yml and docker-compose.local.yml
15+
16+
- **Enhanced Logging System**:
17+
- Structured Winston-based logging with JSON format
18+
- Separate debug log files in `/app/data/debug/`
19+
- Automatic log rotation with size limits and retention policies
20+
- Full error stack traces and request context in debug mode
21+
22+
- **Debug API Endpoints** (9 new endpoints when DEBUG_MODE=true):
23+
- `/api/debug/status` - Debug status and basic information
24+
- `/api/debug/system-info` - Comprehensive system diagnostics
25+
- `/api/debug/health-check` - Detailed component health checks
26+
- `/api/debug/logs` - Retrieve and filter log entries
27+
- `/api/debug/test-ssh` - SSH connectivity testing with detailed diagnostics
28+
- `/api/debug/report` - Generate comprehensive debug reports
29+
- `/api/debug/files` - List and download debug files
30+
- `/api/debug/environment` - Environment variables and configuration
31+
- `/api/debug/log-analysis` - Analyze logs for patterns and issues
32+
33+
- **Debug Tools & Scripts**:
34+
- `debug.sh` - Comprehensive debug management script with 10+ commands
35+
- `verify-debug.sh` - Automated testing of all debug features
36+
- Enhanced error handling with unique error IDs for tracking
37+
38+
- **System Diagnostics**:
39+
- Hardware information collection (CPU, memory, disk)
40+
- Environment analysis with sensitive data sanitization
41+
- Directory structure and permissions analysis
42+
- Multi-step SSH connectivity testing with detailed failure analysis
43+
44+
- **Log Analysis & Reporting**:
45+
- Automatic pattern detection for common errors
46+
- Error frequency analysis and categorization
47+
- Comprehensive debug reports with system snapshots
48+
- Debug file management with automatic cleanup
49+
50+
#### 🔧 Technical Improvements
51+
52+
- **DebugService**: New comprehensive debugging service class
53+
- **Enhanced Error Middleware**: Detailed error tracking with context
54+
- **Request/Response Logging**: Performance monitoring with response times
55+
- **Security Features**: Automatic sanitization of sensitive data in logs
56+
- **Path Traversal Protection**: Secure debug file access restrictions
57+
58+
#### 📚 Documentation
59+
60+
- **DEBUG.md**: Comprehensive debug documentation with usage examples
61+
- **Updated README.md**: Debug features section with quick start guide
62+
- **Enhanced .env.example**: Detailed debug configuration examples
63+
564
## [1.2.0] - 2025-07-11
665

766
### 🎨 Major UI/UX Overhaul

Dockerfile

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# Combined PiHoleVault Dockerfile - Frontend + Backend in single container
22
# Multi-architecture support: AMD64, ARM64, ARMv7
3-
FROM --platform=$BUILDPLATFORM node:18-alpine as frontend-build
43

5-
# Build arguments for cross-platform builds
4+
# Build arguments for cross-platform builds (must be declared before use)
65
ARG TARGETPLATFORM
76
ARG BUILDPLATFORM
87

8+
# Use conditional platform specification - only use if BUILDPLATFORM is set
9+
# This allows the Dockerfile to work with both regular docker build and docker buildx
10+
FROM node:18-alpine as frontend-build
11+
912
# Build the React frontend
1013
WORKDIR /app/frontend
1114
COPY frontend/package*.json ./
@@ -40,6 +43,10 @@ RUN apk add --no-cache \
4043
# Create application directory
4144
WORKDIR /app
4245

46+
# Set environment variables for Docker logging
47+
ENV DOCKER_ENV=true
48+
ENV NODE_ENV=production
49+
4350
# Copy and install backend dependencies
4451
COPY backend/package*.json ./
4552
RUN npm install --only=production --silent
@@ -66,10 +73,23 @@ RUN chmod 700 /root/.ssh && \
6673
ssh-keygen -t rsa -b 4096 -f /root/.ssh/id_rsa -N "" && \
6774
chmod 600 /root/.ssh/id_rsa
6875

69-
# Create startup script inline
76+
# Create startup script inline with debug support
7077
RUN echo '#!/bin/sh' > /usr/local/bin/startup.sh && \
7178
echo 'echo "Starting PiHoleVault services..."' >> /usr/local/bin/startup.sh && \
79+
echo 'echo "Debug Mode: ${DEBUG_MODE:-false}"' >> /usr/local/bin/startup.sh && \
80+
echo 'echo "Log Level: ${LOG_LEVEL:-info}"' >> /usr/local/bin/startup.sh && \
81+
echo 'echo "Debug Level: ${DEBUG_LEVEL:-info}"' >> /usr/local/bin/startup.sh && \
7282
echo 'nginx -t && echo "Nginx config OK"' >> /usr/local/bin/startup.sh && \
83+
echo 'if [ "$DEBUG_MODE" = "true" ]; then' >> /usr/local/bin/startup.sh && \
84+
echo ' echo "=== DEBUG MODE ENABLED ==="' >> /usr/local/bin/startup.sh && \
85+
echo ' echo "Available debug endpoints:"' >> /usr/local/bin/startup.sh && \
86+
echo ' echo " - /api/debug/status"' >> /usr/local/bin/startup.sh && \
87+
echo ' echo " - /api/debug/system-info"' >> /usr/local/bin/startup.sh && \
88+
echo ' echo " - /api/debug/health-check"' >> /usr/local/bin/startup.sh && \
89+
echo ' echo " - /api/debug/logs"' >> /usr/local/bin/startup.sh && \
90+
echo ' echo " - /api/debug/report"' >> /usr/local/bin/startup.sh && \
91+
echo ' echo "=========================="' >> /usr/local/bin/startup.sh && \
92+
echo 'fi' >> /usr/local/bin/startup.sh && \
7393
echo 'exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf' >> /usr/local/bin/startup.sh && \
7494
chmod +x /usr/local/bin/startup.sh
7595

0 commit comments

Comments
 (0)