From c50e0d7c47e32201628c01579a853a8c722d29e5 Mon Sep 17 00:00:00 2001 From: Schulz Date: Mon, 16 Feb 2026 21:05:58 +0100 Subject: [PATCH] Add versioning system and development workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add VERSION file (0.1.0) as single source of truth - Add CHANGELOG.md with complete version history - Update main.py to load version from VERSION file - Remove hardcoded version strings from templates and emails - Document versioning schema in README and CLAUDE.md - Setup develop branch for active development Versioning Schema: - Big changes: +0.1 (e.g., 0.1.0 → 0.2.0) - Small changes: +0.0.1 (e.g., 0.1.0 → 0.1.1) - Major release (1.x): Only on instruction Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 113 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 29 +++++++++- README.md | 39 +++++++++++--- VERSION | 1 + app/email_handler.py | 5 +- app/main.py | 14 +++-- app/templates/login.html | 2 +- 7 files changed, 185 insertions(+), 18 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 VERSION diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bcf728a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,113 @@ +# Changelog + +Alle wichtigen Änderungen an diesem Projekt werden in dieser Datei dokumentiert. + +Das Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/). + +## Versionierung + +- **Große Änderungen** (neue Features, Breaking Changes): +0.1 (z.B. 0.1 → 0.2) +- **Kleine Änderungen** (Bugfixes, kleinere Verbesserungen): +0.0.1 (z.B. 0.1 → 0.1.1) +- **Major Release** (1.x): Nur auf Anweisung + +## [Unreleased] + +### In Arbeit +- Entwicklung läuft im `develop` Branch + +--- + +## [0.1.0] - 2024-02-16 + +### Added - Neue Features +- ✨ **OPNsense Monitoring System** - Vollständiges Monitoring-System + - DHCP Lease Überwachung (filterbar nach Interface) + - Neue Geräte Erkennung via ARP (mit Known-Devices Abgleich) + - Interface Status Monitoring (up/down) + - Gateway Status Monitoring + +- 🖥️ **Web Dashboard** + - Login-System mit Passwort-Schutz (Flask-Login) + - Responsive Bootstrap 5 Interface + - Echtzeit Event-Tabelle mit Auto-Refresh (10s) + - Filterung nach Event-Typ und Interface + - Statistik-Übersicht (Gesamt, Heute, Letzte Stunde, Bekannte Geräte) + +- 📧 **E-Mail Benachrichtigungen** + - SMTP Support mit TLS + - HTML-formatierte E-Mails + - Event-spezifische Templates + - Startup-Benachrichtigung + - Intelligente Filterung (nur unbekannte Geräte bei new_device) + +- 💾 **SQLite Datenbank** + - Events Tabelle mit vollständiger Event-Historie + - Known Devices Tabelle (auto-populated) + - Automatische Retention (alte Events löschen) + - Indizierung für schnelle Queries + +- 🔧 **Konfiguration** + - Vollständig über `config/config.yaml` konfigurierbar + - OPNsense API Integration + - Monitoring-Intervall anpassbar + - Interface-Filterung + - Event-Toggles (einzeln an/ausschaltbar) + +- 🐳 **Docker Support** + - Dockerfile mit Python 3.11-slim + - docker-compose.yml mit Healthcheck + - Volume-Mapping für config & data + - Auto-Restart + +- 📚 **Dokumentation** + - Vollständige README mit Setup-Anleitung + - OPNsense API Setup Guide + - Troubleshooting Sektion + - CLAUDE.md für KI-assistierte Entwicklung + +### Technical Details +- **Backend:** Python 3.11, Flask 3.0.0, APScheduler 3.10.4 +- **Database:** SQLite mit JSON-Support +- **Frontend:** Bootstrap 5, Vanilla JavaScript +- **API Client:** Requests mit OPNsense REST API +- **Auth:** Flask-Login mit Werkzeug password hashing +- **Email:** SMTP mit HTML/MIME multipart + +### Initial Files +``` +watchdog-docker/ +├── Dockerfile +├── docker-compose.yml +├── requirements.txt +├── README.md +├── CHANGELOG.md +├── CLAUDE.md +├── .gitignore +├── config/ +│ └── config.yaml +├── app/ +│ ├── main.py +│ ├── opnsense_api.py +│ ├── monitor.py +│ ├── database.py +│ ├── email_handler.py +│ └── templates/ +│ ├── login.html +│ └── dashboard.html +└── data/ + └── .gitkeep +``` + +--- + +## Legende + +- **Added** - Neue Features +- **Changed** - Änderungen an bestehender Funktionalität +- **Deprecated** - Bald zu entfernende Features +- **Removed** - Entfernte Features +- **Fixed** - Bugfixes +- **Security** - Sicherheits-Fixes + +[Unreleased]: https://tea.ffw-ak-ff.de/FFW-VG-AK-FF/watchdog-docker/compare/v0.1.0...HEAD +[0.1.0]: https://tea.ffw-ak-ff.de/FFW-VG-AK-FF/watchdog-docker/releases/tag/v0.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index 4b24a10..ba4a8b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Watchdog Docker v0.1 - OPNsense monitoring system with web dashboard and email notifications. Monitors DHCP leases, new devices (ARP), interface status changes, and gateway status changes. +Watchdog Docker - OPNsense monitoring system with web dashboard and email notifications. Monitors DHCP leases, new devices (ARP), interface status changes, and gateway status changes. + +**Current Version:** See [VERSION](VERSION) file +**Changelog:** [CHANGELOG.md](CHANGELOG.md) ## Tech Stack @@ -81,8 +84,10 @@ python -c "from werkzeug.security import generate_password_hash; print(generate_ ## Key Files +- **VERSION** - Current version number (single source of truth) +- **CHANGELOG.md** - Complete version history and changes - **config/config.yaml** - ALL settings (OPNsense, monitoring, web, email, database) -- **app/main.py** - Flask app entry point +- **app/main.py** - Flask app entry point (loads VERSION file) - **app/monitor.py** - Core monitoring logic with state tracking - **app/database.py** - SQLite operations - **app/email_handler.py** - Email notifications with HTML templates @@ -108,6 +113,26 @@ All settings in `config/config.yaml`: - **Retention:** Old events auto-cleanup based on retention_days (default 90) - **Password:** Admin password must be werkzeug scrypt hash in config.yaml +## Versioning + +### Version Schema +- **Big changes** (new features, breaking changes): +0.1 (e.g., 0.1.0 → 0.2.0) +- **Small changes** (bugfixes, minor improvements): +0.0.1 (e.g., 0.1.0 → 0.1.1) +- **Major release** (1.x): Only on instruction + +### Git Workflow +- **main** - Stable releases only +- **develop** - Active development (current working branch) +- Feature branches for larger features + +### Making Changes +1. Work in `develop` branch +2. Update VERSION file with new version number +3. Update CHANGELOG.md with changes (follow Keep a Changelog format) +4. Commit changes with descriptive message +5. Push to develop +6. Merge to main when stable and tested + ## Code Style - German language in UI/emails (Deutsch) diff --git a/README.md b/README.md index 81ece08..ce8adc5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -# Watchdog Docker v0.1 +# Watchdog Docker Docker Container für OPNsense Monitoring mit Web-Interface und E-Mail-Benachrichtigungen. +**Aktuelle Version:** Siehe [VERSION](VERSION) | **Changelog:** [CHANGELOG.md](CHANGELOG.md) + ## Features - 🔍 **DHCP Lease Monitoring** - Überwachung neuer IP-Vergaben @@ -334,6 +336,34 @@ cp config/config.yaml config/config.yaml.backup - ⚠️ Verwende HTTPS für das Web-Interface (z.B. mit Reverse Proxy) - ⚠️ Speichere keine API-Secrets in Git (nutze `.env` Dateien) +## Versionierung & Entwicklung + +### Versionsschema + +Das Projekt folgt einem angepassten Semantic Versioning Schema: + +- **Große Änderungen** (neue Features, Breaking Changes): **+0.1** + - Beispiel: `0.1.0` → `0.2.0` + - Trigger: Neue Monitoring-Features, API-Änderungen, UI-Redesign + +- **Kleine Änderungen** (Bugfixes, kleinere Verbesserungen): **+0.0.1** + - Beispiel: `0.1.0` → `0.1.1` + - Trigger: Bugfixes, Performance-Verbesserungen, Dokumentations-Updates + +- **Major Release** (1.x): **Nur auf Anweisung** + - Production-Ready Status + - Vollständig getestet und stabil + +### Git Workflow + +- **`main`** - Stable Release Branch (nur getestete Versionen) +- **`develop`** - Development Branch (aktive Entwicklung) +- **Feature Branches** - Für größere Features (`feature/feature-name`) + +### Changelog + +Alle Änderungen werden in [CHANGELOG.md](CHANGELOG.md) dokumentiert. Das Format folgt [Keep a Changelog](https://keepachangelog.com/de/1.0.0/). + ## Entwicklung ### Lokale Entwicklung ohne Docker @@ -374,9 +404,4 @@ MIT License ## Changelog -### v0.1 (Initial Release) -- OPNsense Monitoring (DHCP, Devices, Interfaces, Gateways) -- Web Dashboard mit Echtzeit-Updates -- E-Mail Benachrichtigungen -- SQLite Datenbank -- Docker Support +Siehe [CHANGELOG.md](CHANGELOG.md) für vollständige Versionshistorie. diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..6c6aa7c --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0 \ No newline at end of file diff --git a/app/email_handler.py b/app/email_handler.py index b3d6a8c..eed0302 100644 --- a/app/email_handler.py +++ b/app/email_handler.py @@ -105,7 +105,6 @@ class EmailHandler:

Status: Aktiv

Zeitpunkt: {datetime.now().strftime('%d.%m.%Y %H:%M:%S')}

-

Version: 0.1

OPNsense Monitoring ist aktiv und überwacht folgende Events:

    @@ -116,7 +115,7 @@ class EmailHandler:
-

Watchdog Docker v0.1 - Automatische Benachrichtigung

+

Watchdog Docker - Automatische Benachrichtigung

@@ -223,7 +222,7 @@ class EmailHandler: {details_html}
-

Watchdog Docker v0.1 - Automatische Benachrichtigung

+

Watchdog Docker - Automatische Benachrichtigung

diff --git a/app/main.py b/app/main.py index 3b0b76c..14f6dca 100644 --- a/app/main.py +++ b/app/main.py @@ -11,6 +11,10 @@ from database import Database from monitor import OPNsenseMonitor from email_handler import EmailHandler +# Load version +with open('VERSION', 'r') as f: + VERSION = f.read().strip() + # Load configuration with open('config/config.yaml', 'r') as f: config = yaml.safe_load(f) @@ -120,7 +124,7 @@ def health(): return jsonify({ 'status': 'healthy', 'timestamp': datetime.now().isoformat(), - 'version': '0.1' + 'version': VERSION }) # Initialize scheduler @@ -145,14 +149,14 @@ def start_monitoring(): email_handler.send_startup_notification() if __name__ == '__main__': - logger.info("Starting Watchdog Docker v0.1") - + logger.info(f"Starting Watchdog Docker v{VERSION}") + # Initialize database db.initialize() - + # Start monitoring start_monitoring() - + # Run Flask app.run( host=config['web']['host'], diff --git a/app/templates/login.html b/app/templates/login.html index be9ae80..a6a3c18 100644 --- a/app/templates/login.html +++ b/app/templates/login.html @@ -106,7 +106,7 @@
- Version 0.1 + Watchdog Docker