🌊
TideWatch
Security-driven Docker container update manager
What is TideWatch?
TideWatch is a container update manager for homelabbers who got tired of Watchtower's "update everything, ask questions never" approach. It watches your containers for updates, but actually lets you decide what happens next—approve, reject, snooze, or let certain policies run automatically.
The real magic is the VulnForge integration. When an update is detected, TideWatch checks if the new image has more or fewer vulnerabilities than what you're running. Set a container to "security" policy and it'll only auto-update when the new version actually improves your security posture.
It reads your docker-compose files directly, tracks updates across Docker Hub, GHCR, and LinuxServer.io registries, and keeps a full history of what changed and when. No more guessing which container updated at 3am and broke everything.
Technology Stack
Backend
- → Python 3.12+ with FastAPI and Granian ASGI server
- → SQLAlchemy 2.x + SQLite (WAL mode) via aiosqlite
- → APScheduler for background jobs with retry logic
- → Multi-registry Docker clients (Docker Hub, GHCR, LSCR)
- → CSRF protection and rate limiting middleware
- → httpx async HTTP with ntfy notifications
- → Prometheus metrics endpoint
Frontend
- → React 19 + TypeScript 5.9 with Vite 7
- → Tailwind CSS 4 with teal/orange dark theme
- → React Router v7 navigation
- → Recharts for metrics visualization
- → Sonner toast notifications
- → date-fns formatting and Lucide icons
Project Statistics
~32,300
Total Lines of Code
~22,600
Python Backend
~9,700
TypeScript Frontend
5
Interactive Pages
Powered by VulnForge
TideWatch integrates seamlessly with VulnForge to provide vulnerability intelligence for every update decision. When an update is detected, TideWatch queries VulnForge to compare vulnerability counts, identify CVEs fixed or introduced, and generate security recommendations.
This integration enables the security policy enforcement that makes TideWatch unique: containers with a "security" policy will automatically reject updates that increase vulnerability counts, ensuring your security posture never degrades.
Version History
Track the evolution of TideWatch through its version releases. Each release includes new features, improvements, and bug fixes.
v3.1.0 2025-11-28
✨ Added
- • **Multi-Service Notification System** - Support for 7 notification services beyond ntfy → **Gotify** - Self-hosted push notification server support → **Pushover** - Cross-platform push notification service ($5 one-time) → **Slack** - Incoming webhooks for team notifications → **Discord** - Webhook integration for server notifications → **Telegram** - Bot API integration with HTML formatting → **Email** - SMTP support with HTML emails and TLS → All services share unified architecture with abstract base class → Event-based routing via NotificationDispatcher → Per-service enable toggles with validation → Test Connection buttons for all services → Expandable event group UI (Updates, Restarts, System) → Service sub-tabs with enabled indicators (green dot) → Backend: `/backend/app/services/notifications/` (8 files) → Frontend: `/frontend/src/components/notifications/` (9 components) → New API endpoints: `POST /api/v1/settings/test/{service}` for all 7 services → New dependency: `aiosmtplib>=3.0.0` for async SMTP
🔄 Changed
- • **Notification Architecture** - Migrated from single-service to multi-service pattern → All notification call sites now use `NotificationDispatcher` instead of direct `NtfyService` → Updated: `update_checker.py`, `update_engine.py`, `restart_service.py`, `restart_scheduler.py`, `scheduler.py` → Removed: `ntfy_service.py` (replaced by notifications module)
🐛 Fixed
- • **Update Notification Timing** - Ntfy notifications now sent after database commit → Previously, notifications were sent before `db.commit()` completed → This caused race conditions where users received phone notifications but updates weren't visible in UI → Now commits per-container instead of batching, ensuring notifications match persisted state → Added rollback handling for failed container checks to prevent partial transaction issues
v3.0.0 2025-11-24
🔒 Security
- • **CSRF Protection** - Session-based double-submit pattern → SessionMiddleware with secure, HttpOnly cookies → Constant-time token comparison prevents timing attacks → SameSite=Lax for additional protection
- • **Rate Limiting** - Endpoint-specific limits → Container operations: 5 req/min (prevents restart spam) → Update operations: 3 req/min (prevents update flooding) → Settings changes: 10 req/min
- • **Command Injection Prevention** - Centralized input validation → Container names, service names validated against shell metacharacters → Docker compose commands use whitelist-based validation → List-based subprocess calls (no shell=True)
- • **Path Traversal Protection** - Multi-layer path validation → Dangerous pattern detection (`..`, `//`, `\`, null bytes) → Base directory containment checks → Symlink escape prevention → Extension validation for compose files
- • **Security Headers** - Comprehensive header implementation → X-Content-Type-Options: nosniff → X-Frame-Options: DENY (clickjacking protection) → X-XSS-Protection: 1; mode=block → Strict-Transport-Security (HTTPS only in production) → Content-Security-Policy
✨ Added
- • **Database Indexes** - Performance optimization for frequently queried columns → Container indexes: policy, update_available, name → Update indexes: status, container_id, created_at, snoozed_until → UpdateHistory indexes: container_id, status, created_at, started_at → Migration 019 adds all indexes on startup
- • **Retry Logic** - Exponential backoff for network failures → Decorator utilities for async and sync functions → Configurable max attempts, backoff base, and exceptions → Applied to registry HTTP requests
- • **Test Suite** - pytest configuration and initial tests → Validator tests for command injection prevention → Retry logic tests for exponential backoff → API endpoint tests (partial coverage) → Test database isolation with in-memory SQLite
🐛 Fixed
- • **CRITICAL: Missing Dependency** - Added `itsdangerous>=2.1.0` → Required by SessionMiddleware but not in dependencies → Application crashed on startup without it
- • **Migration 019 Signature** - Fixed function signature mismatch → Migration runner expects `upgrade()` without parameters → Migration had `upgrade(conn: AsyncConnection)` which failed → Now matches existing migration pattern
- • **Test Suite Database Path** - Fixed permission errors in tests → Tests tried to create `/data` directory on import → Now sets DATABASE_URL environment variable before importing → Uses in-memory SQLite for test isolation
- • **Test Import Errors** - Fixed incorrect retry API usage → test_retry.py used non-existent `with_retry` and `RetryConfig` → Updated to use actual `async_retry` decorator API
🔄 Changed
- • **CORS Configuration** - Fixed security issues → Wildcard origins now properly disable credentials → Explicit method whitelist (no wildcards) → Explicit header whitelist → Exposes rate limit headers to frontend → Configurable via CORS_ORIGINS environment variable
- • **Database Connection Pooling** - Optimized for SQLite → StaticPool for single persistent connection → WAL mode enabled for concurrent read/write → 64MB cache size, 5-second busy timeout
- • **Memory Leak Fixes** - Rate limiter bucket cleanup → Reduced cleanup threshold from 10 to 5 minutes → Hard limit of 10,000 buckets maximum → Aggressive cleanup when limit exceeded
📝 Dependencies
- • Added: `itsdangerous>=2.1.0` (session signing)
- • Dev: `pytest>=8.3.0`, `pytest-asyncio>=0.24.0`, `pytest-cov>=4.1.0`, `httpx>=0.27.2`
v2.9.1 2025-11-24
🐛 Fixed
- • **Light Theme Visual Issues** - Resolved all remaining hardcoded colors and styling issues → Fixed CSRF token authentication errors in theme switching (ThemeContext now uses settingsApi) → Replaced 106+ instances of hardcoded gray colors with theme-aware variables across all pages → Fixed Flash of Unstyled Content (FOUC) by adding inline script to index.html → Fixed card spacing visibility in light mode (container background now uses `bg-tide-surface-light`) → Fixed black backgrounds on Dashboard, Updates, and History pages → Added borders to all Test Connection buttons in Settings page → Added border to Upload button in Backup & Maintenance section → Updated Statistics cards in About page with accurate line counts
🔄 Changed
- • **Navigation Header Text Size** - Increased font sizes for better readability → App title: `text-xl` → `text-2xl` (20px → 24px) → Desktop nav links: `text-sm` → `text-base` (14px → 16px) with 18px icons → Mobile nav links: `text-base` → `text-lg` (16px → 18px) with 20px icons
- • **About Page Updates** - Updated project information → Changed author attribution from "Jamey (oaniach)" to "Operator" → Updated statistics to reflect current codebase: → Total Lines: ~16,700 → ~25,600 → Python Backend: ~11,800 → ~17,300 → TypeScript Frontend: ~4,900 → ~8,300
📝 Technical
- • Systematic replacement of hardcoded Tailwind gray classes with CSS custom properties → `bg-gray-950` → `bg-tide-bg`, `bg-gray-700` → `bg-tide-surface`, etc.
- • Theme variables properly adapt to both light and dark modes
- • All UI components now consistently use semantic color names
v2.9.0 2025-11-24
✨ Added
- • **Light/Dark Theme Toggle** - NEW: Full light and dark theme support using Tailwind 4.1.x @theme feature → Theme toggle in Settings > System tab with Sun/Moon icons → Seamless theme switching with instant visual feedback → Persistent theme preference stored in database with cross-device sync → localStorage caching for instant theme loading (no FOUC) → Semantic CSS variables (`--color-tide-bg`, `--color-tide-surface`, `--color-tide-text`) for maintainability → All UI components support both themes: → Navigation bar, footer, cards, modals → Dashboard charts and analytics → Settings panels and forms → Update cards and history views → Dynamic Sonner toast theming → Scrollbar styling for both themes → Dark theme remains default for existing users → API: `GET/PUT /api/v1/settings/theme` for programmatic theme control
🐛 Fixed
- • **Migration System** - Fixed migrations directory structure to match MyGarage pattern → Moved migrations from `/backend/migrations/` to `/backend/app/migrations/` → Auto-migration system now working correctly on container startup → Migration 014 now handles duplicate update records before applying unique constraint
🔄 Changed
- • Updated frontend to version 2.9.0
- • Updated backend to version 2.9.0
v2.8.0 2025-11-24
✨ Added
- • **HTTP Server Detection** - NEW: Automatically detect and track HTTP servers running in containers → Detects popular web servers: nginx, Apache, Caddy, Traefik, Granian, uvicorn, gunicorn, Node.js, and more → Version detection via command execution (e.g., `nginx -v`, `granian --version`) → Process-based detection with fallback to `/proc` for minimal containers without `ps` → Checks for latest versions from GitHub API (Caddy, Traefik, Granian) → Update availability tracking with severity indicators → New HTTP Servers section in Dependencies tab with stats and server cards → API endpoints: → `GET /api/v1/containers/{id}/http-servers` - Get detected servers → `POST /api/v1/containers/{id}/http-servers/scan` - Scan for servers → Auto-scans when Dependencies tab is opened
- • **Dockerfile Dependency Tracking** - COMPLETE: Full end-to-end tracking of Dockerfile base images and build dependencies → **Backend (Phase 1)** ✅: → Automatically parse Dockerfiles to detect `FROM` statements → Track base images (e.g., `node:22-alpine`, `python:3.14-slim`) as dependencies → Support for multi-stage builds with stage name tracking → Update Detection: Check Docker registries for newer base image versions → Bulk Update Checking: Scan all tracked Dockerfile dependencies for updates → New database table: `dockerfile_dependencies` with migration → New API endpoints: → `GET /api/v1/containers/{id}/dockerfile-dependencies` - Get dependencies → `POST /api/v1/containers/{id}/dockerfile-dependencies/scan` - Scan Dockerfile → `POST /api/v1/dockerfile-dependencies/check-updates` - Check all for updates → Backend service: `DockerfileParser` with full update detection support → Integrates with existing `RegistryClient` for checking Docker Hub, GHCR, LSCR, GCR, Quay → **Frontend UI (Phase 2)** ✅: → New Dockerfile Dependencies section in Container Modal Dependencies tab → Visual display of base images and build images with update indicators → Statistics cards showing total images and available updates → "Scan Dockerfile" button for manual triggering → Dependency cards showing: → Image name, current tag, and latest tag → Dependency type (Base Image / Build Image) → Stage name for multi-stage builds → Dockerfile path and line number reference → Update availability badges (Update Available / Up to date) → Loading states and empty states with helpful messages → Settings page configuration: → Auto-Scan Dockerfiles toggle → Update check schedule (Disabled / Daily / Weekly) → Info box with feature explanation → **Automation (Phase 3)** ✅: → Auto-scan Dockerfiles when containers are added via project scanner → Scheduled update checks (daily at 3 AM or weekly on Sundays) → ntfy notifications for Dockerfile dependency updates → Configurable via Settings page → Respects `dockerfile_auto_scan` and `dockerfile_scan_schedule` settings → 🎯 **Solves**: Why Tidewatch didn't notify about Node.js update (now tracks Docker base images!)
- • **Automatic Database Migrations** - NEW: Self-managing migration system for zero-downtime upgrades → Automatic migration discovery and execution on startup → Tracks applied migrations in `schema_migrations` table → Prevents re-running already-applied migrations (idempotent) → Runs migrations in chronological order (001, 002, etc.) → Graceful error handling (logs errors but doesn't fail startup) → Same battle-tested system as MyGarage → **Files Created:** → `app/migrations/runner.py` - Migration orchestration engine → `app/migrations/__init__.py` - Python package structure → **Files Modified:** → `app/db.py` - Integrated migration runner into startup sequence → **Benefits:** → No manual migration commands needed → Safe upgrades with automatic rollback on failure → Docker-friendly (just restart container to apply migrations) → Development-friendly (drop `.py` migration files, they auto-run)
- • **ESLint Flat Configuration** - Added ESLint 9.x flat config for frontend linting → Created `eslint.config.js` using modern flat config format → Installed `globals` and `typescript-eslint` packages → Configured TypeScript, React, and React Hooks rules → Simplified lint script in package.json: `eslint .`
🔄 Changed
- • **Dependencies Tab UI Layout** - Improved layout with two-column masonry design → Left column: HTTP Servers + Dockerfile Dependencies → Right column: Application Dependencies → Reduces wasted vertical space and improves information density → Responsive grid that stacks on mobile devices
- • **Application Dependencies Filter** - Changed default filter from "All" to "Updates" → Shows packages with available updates by default for quicker action → Users can still switch to "All" or "Security" filters as needed
- • **Dockerfile Dependencies Auto-Scan** - Removed manual "Scan Dockerfile" button → Auto-scans when Dependencies tab is opened (consistent with HTTP Servers and App Dependencies) → Cleaner UI with one less button
- • **Node.js Build Environment** - Updated frontend build to use Node.js 22 (from Node.js 20) → Updated Dockerfile: `FROM node:22-alpine` (was `node:20-alpine`) → Required for @vitejs/plugin-react 5.x compatibility (needs Node 20.19+ or 22.12+)
- • **Frontend Dependencies** - Updated 8 npm packages to latest versions → @vitejs/plugin-react: 4.7.0 → 5.1.1 (major update with Oxc integration for faster builds) → recharts: 3.4.1 → 3.5.0 (performance improvements for chart rendering) → vite: 7.2.2 → 7.2.4 (bug fixes) → lucide-react: 0.553.0 → 0.554.0 (new icons) → @types/react: 19.2.2 → 19.2.6 (type definition updates) → @types/react-dom: 19.2.2 → 19.2.3 (type definition updates) → @typescript-eslint/eslint-plugin: 8.46.4 → 8.47.0 (new linting rules) → @typescript-eslint/parser: 8.46.4 → 8.47.0 (parser improvements) → Kept eslint-plugin-react-hooks at 7.0.0 (7.0.1 has known regression bugs) → Added globals: ^16.5.0 and typescript-eslint: ^8.47.0 for ESLint 9.x support
🐛 Fixed
- • **Vite Build Configuration** - Removed obsolete `react-hot-toast` reference from vite.config.ts → Application uses `sonner` for notifications; `react-hot-toast` was legacy reference → Fixes build error: "Could not resolve entry module 'react-hot-toast'"
- • **ESLint Configuration Missing** - Resolved ESLint 9.x compatibility issue → ESLint 9.x requires flat config format (eslint.config.js) → Created proper flat config with all necessary plugins and rules → `npm run lint` now works correctly (reveals 56 pre-existing linting issues to be fixed separately)
- • **Dockerfile Dependencies API Errors** - Fixed missing imports preventing application startup → Added missing `DockerfileDependenciesResponse` and `DockerfileDependencySchema` imports to `containers.py` → Added missing `Optional` type import for Dockerfile scan endpoint → Fixes `NameError: name 'schemas' is not defined` and `NameError: name 'Optional' is not defined` → Application now starts successfully with Dockerfile dependency tracking enabled
v2.7.0 2025-11-22
✨ Added
- • **My Projects Auto-Discovery** - Automatically detect dev containers from projects directory → New Settings card: "My Projects Configuration" with enable toggle, projects directory path, auto-scan toggle → Project scanner service automatically discovers containers from `/projects/*/compose.yaml` files → Intelligently identifies main dev container vs infrastructure services (postgres, redis, etc.) → Prefers services ending in `-dev` over other services in multi-service compose files → Manual "Scan Projects Now" button for on-demand scanning → Auto-detected containers automatically marked as "My Project" with `is_my_project = True` → Stale container cleanup: removes "My Project" entries whose compose files no longer exist → Scan results show added, updated, skipped, and removed container counts → Backend: `ProjectScanner` service with `scan_projects_directory()` and `remove_missing_projects()` methods → Frontend: "My Projects Configuration" card follows app theme (yellow star icon, gray-800 background, teal accents) → API endpoint: `POST /api/v1/containers/scan-my-projects` for manual project scanning → Settings: `my_projects_enabled`, `my_projects_auto_scan`, `my_projects_compose_command`, `projects_directory` → Volume mount: `/srv/raid0/docker/build:/projects:ro` for read-only access to project source code → Support for custom docker compose commands for dev containers (e.g., simple `docker compose` vs complex production stacks)
🔄 Changed
- • **UI Cleanup and Improvements** → Updated "My Project" toggle description to mention auto-detection: "Dev containers are auto-detected from your projects directory" → Moved "About Docker Settings" info box inside Docker Configuration card for better organization → Removed redundant "Scan Dependencies" button from Dependencies tab (auto-scan already works on tab open) → Updated Dependencies tab header to explain auto-scanning behavior → Improved empty state message in Dependencies tab with clearer explanation
- • **Dependencies Tab Auto-Scanning** - Dependencies now scan automatically when tab is opened (no manual button needed)
🐛 Fixed
- • **Project Scanner Service Selection Logic** - Fixed scanner picking wrong services from multi-service compose files → Now correctly identifies main dev container instead of first service alphabetically → Skips infrastructure services (postgres, redis, mysql, mariadb, mongodb, rabbitmq, elasticsearch) → Prioritizes services/containers ending with `-dev` suffix → Falls back to first non-infrastructure service if no `-dev` service found → Example: `collectionsync/compose.yaml` now correctly finds `collectionsync-dev` instead of `postgres`
- • **Stale Container Cleanup** - Scanner now removes containers that are no longer found in project scans → Tracks which containers were found during scan using a set → Deletes "My Project" containers not found in current scan → Prevents stale entries like `socket-proxy-dev` and `collectionsync-postgres` from lingering
📝 Technical
- • Added database migration `015_add_is_my_project.py` to add `is_my_project` field
- • Updated `Container` model and schemas to support `is_my_project` boolean field
- • Project scanner uses `ruamel.yaml` for robust YAML parsing (already in dependencies)
- • Scanner returns tuple `(result, container_name)` to track found containers
- • Conditional UI rendering: My Project toggle only shows if `my_projects_enabled = true`
- • Info boxes use consistent styling: `bg-gray-900/50 rounded-lg p-4` for tips sections
v2.6.0 2025-11-21
✨ Added
- • **My Projects Feature** - Mark containers as "My Project" to organize and track them separately → Added `is_my_project` boolean field to containers with database migration → Dashboard now splits containers into "My Projects" (top) and "Other Containers" sections → "My Project" toggle in Container Settings tab with star icon indicator → Only "My Projects" can access the new Dependencies tab
- • **Application Dependencies Tracking** - Track and monitor application-level dependencies → New "Dependencies" tab in container modal (only visible for My Projects) → Multi-ecosystem support: npm (Node.js), PyPI (Python), Composer (PHP), Cargo (Rust), Go modules → Automatic dependency file detection (package.json, requirements.txt, composer.json, Cargo.toml, go.mod) → Real-time version checking against package registries → Displays current vs. latest versions with update availability → Security advisory tracking and severity indicators → Socket.dev security scoring integration (ready for future implementation) → Filterable view: All, Updates Available, Security Issues → Manual "Scan Dependencies" button with loading states → Stats cards showing Total, Updates Available, and Security Issues counts → Visual severity badges (Critical, High, Medium, Low, Info) based on semver differences → Ecosystem-specific icons (📦 npm, 🐍 PyPI, 🐘 Composer, 🦀 Cargo, 🐹 Go)
- • **Backend Dependency Scanner Service** - Robust multi-ecosystem dependency detection → Automatic project root detection from compose file volume mounts → Parallel scanning across all supported ecosystems → Package registry API integration (npm, PyPI, Packagist, crates.io, Go proxy) → Version comparison and update availability calculation → Severity assessment based on semantic versioning differences → Configurable timeout and error handling for external API calls
- • **New API Endpoints** → `GET /api/v1/containers/{id}/app-dependencies` - Get application dependencies with update info → `POST /api/v1/containers/{id}/app-dependencies/scan` - Force rescan of dependencies → Enhanced `PUT /api/v1/containers/{id}` to support `is_my_project` field → Permissions: Dependencies endpoints restricted to containers marked as My Projects
🔄 Changed
- • Updated frontend package version to 2.6.0
- • Updated backend package version to 2.6.0
- • Dashboard container grid now uses conditional rendering for grouped sections
- • Container modal tabs conditionally show Dependencies tab based on `is_my_project` status
v2.5.1 2025-11-18
🔒 Security
- • Fixed command injection vulnerability in container restart endpoint
- • Added path traversal protection for compose file operations
- • Fixed URL injection in health check authentication
- • Added Docker tag format validation to prevent injection attacks
- • Fixed ReDoS vulnerabilities in regex patterns with unbounded repetition
🐛 Fixed
- • Added error handling for resource cleanup to prevent connection leaks
- • Fixed SQLite connection pool configuration causing database locks
- • Fixed race condition in update creation with unique constraint and IntegrityError handling
- • Improved error handling in frontend event stream with user notifications
🔄 Changed
- • Updated update checker to handle duplicate update creation gracefully
- • Database connection pooling now adapts based on database type (SQLite vs PostgreSQL)
- • Added comprehensive input validation for container names, file paths, and Docker tags
v2.5.0 2025-11-17
✨ Added
- • **Updates Tab Masonry Layout** - Converted Settings > Updates tab to responsive two-column masonry layout → Uses CSS `columns-1 xl:columns-2` for natural card flow (matching Container Settings pattern from v2.4.1) → Cards maintain natural widths and heights with `break-inside-avoid` property → Single column on mobile/tablet (<1280px), two columns on desktop (≥1280px) → All 5 settings cards flow naturally into columns based on content height
- • **Scheduler Status Display** - Added real-time scheduler status card at top of Updates tab → Shows scheduler running state (● Running / ⏸ Paused) with color indicators → Displays next scheduled run time and last check time (relative times using `formatDistanceToNow`) → Auto-refreshes when Updates tab becomes active → Provides visibility into background update checking service
- • **Auto-Reload Scheduler on Schedule Change** - Scheduler automatically reloads when cron schedule is updated → Detects changes to `check_schedule` setting in Settings > Updates → Calls `/api/v1/updates/scheduler/reload` endpoint after successful save → Displays success toast: "Scheduler reloaded with new schedule" → Immediately refreshes scheduler status display to show new next run time
- • **Reset Settings to Defaults** - Added danger zone with reset button in Settings > System tab → Red-bordered section at bottom of System tab with warning styling → Confirmation dialog: "Reset ALL settings to defaults? Cannot be undone." → Calls `/api/v1/settings/reset` endpoint and reloads all settings after reset → Provides escape hatch for configuration issues
- • **Settings Categories Organization (EXPERIMENTAL)** - Settings now grouped by category → Changed `loadSettings()` to try `/api/v1/settings/categories` endpoint first → Falls back to flat `/api/v1/settings/` list if categories endpoint fails → Graceful degradation for backwards compatibility → Note: Backend categories endpoint already existed, now integrated into frontend
- • **Security Updates Filter** - Added dedicated filter for security-related updates on Updates page → New filter button with Shield icon: "Security (N)" showing count of CVE-related updates → Red background when active to highlight security-critical updates → Calls `/api/v1/updates/security` endpoint to fetch only updates with CVE fixes → Positioned above status filter tabs (All, Pending, Approved, etc.) → Shield icon provides visual indication of security-related updates
🔄 Changed
- • **Container Logs API Migration** - Migrated ContainerModal logs fetching from docker router to containers router → Changed `/api/v1/docker/containers/{id}/logs` → `api.containers.getLogs(id, tail)` → Uses existing containerApi endpoint for consistency → Properly handles log array formatting with `.join('\n')`
🗑️ Removed
- • **Docker Router** - Removed unused `/api/v1/docker/` router from backend → Deleted `backend/app/api/docker.py` file (139 lines) → Removed docker router import and registration from `backend/app/api/__init__.py` → Only 1 frontend reference existed (ContainerModal logs), now migrated to containers API → Reduces API surface area and eliminates redundant container endpoints
v2.4.7 2025-11-17
🐛 Fixed
- • **Cross-Distro Tag Suggestions** - Fixed variant tag filtering to preserve image variants (alpine vs debian/trixie) → Images like `python:3.12-alpine` now only suggest alpine-based updates (e.g., `3.12.12-alpine`) → Prevents cross-distribution suggestions that would break compatibility (e.g., suggesting `3.12.12-trixie` for `3.12-alpine`) → Updated all registry clients (DockerHub, GHCR, GenericRegistry, Quay) with suffix-matching logic → Closes issue from v2.4.5 where variant filtering was incomplete
- • **Python-Style Pre-release Detection** - Added support for Python-style alpha/beta/rc tags → Added patterns `a0`-`a9`, `b0`-`b9`, `rc0`-`rc9` to prerelease indicators → Versions like `3.15.0a1`, `2.1.0b2` now correctly filtered as pre-releases → Applied across all registry clients (DockerHub, GHCR, LSCR, GCR, Quay)
✨ Added
- • **Global Include Pre-releases Setting** - New toggle in Settings > Updates to control pre-release filtering → Users can now globally enable/disable pre-release versions (alpha, beta, rc, nightly) → Acts as default for containers that don't have per-container override → Located in "Update Checks" card where it logically belongs → Prevents confusion with "Exclude Dev Containers" (which only affects stale detection)
v2.4.6 2025-11-17
🐛 Fixed
- • **Settings Key Mismatch** - Retry settings (Max Attempts, Backoff Multiplier) now properly applied to updates → Fixed frontend using wrong setting keys (`max_retry_attempts` vs `update_retry_max_attempts`) → Fixed backend never reading settings when creating Update objects → Update objects now use configured retry settings instead of hardcoded defaults (3 retries, 3x backoff)
- • **No Manual Intervention for Retrying Updates** - Users can now control updates stuck in retry loops → Added "Cancel Retry" button to reset pending_retry updates back to pending state → Added "Reject" button to dismiss retrying updates permanently → Added "Delete" button as escape hatch to remove problematic updates → Fixed reject endpoint to accept both "pending" and "pending_retry" statuses
- • **Retrying Updates Hidden in UI** - Added dedicated "Retrying" filter tab on Updates page → New filter shows only updates in pending_retry status → Shows retry count with rotating icon badge for easy identification → Displays next retry time in error messages
🔄 Changed
- • **Settings UI Improvement** - Converted retry settings to sliders matching app theme → Replaced number input fields with teal-colored range sliders → Shows current values in parentheses next to labels (e.g., "Max Attempts (5)") → Consistent with existing slider patterns in Container Modal
v2.4.5 2025-11-16
🐛 Fixed
- • **Duplicate Update Entries** - Fixed deduplication query missing `from_tag` check → Added `Update.from_tag == container.current_tag` to deduplication query → Prevents multiple Update records for the same container+version combination
- • **PR Tag Detection** - Pull request tags (e.g., `pr-4234`) no longer detected as valid updates → Added `'pr-'` and `'pull-'` to prerelease_indicators across all registry clients → Filters out development PR tags from update candidates
- • **Latest Tag Detection** - "latest" tag no longer appears as update target for pinned versions → Added explicit "latest" tag filtering in both DockerHub and other registry clients → Prevents containers pinned to specific versions from showing "latest" as update
- • **Variant Tag Filtering** - Image variant suffixes now automatically filtered (future-proof) → Replaced hardcoded suffix list with smart pattern matching → Automatically rejects ANY suffix that's not a standard pre-release (rc, beta, alpha) → Filters `-enterprise`, `-scratch`, `-cluster`, `-oss`, `-alpine`, `-slim`, etc. → No manual updates needed for new variant patterns introduced by upstream projects
v2.4.4 2025-11-15
🐛 Fixed
- • **Rollback for Failed Updates** - Failed updates can now be rolled back if a backup exists → Backend now sets `can_rollback = True` for failed updates when backup is available → Removed frontend restriction requiring "success" status for rollback button visibility → Updated rollback API to accept both "success" and "failed" statuses
- • **Pre-release Tag Filtering** - Tags containing "master" (e.g., `master-omnibus`) now correctly filtered as pre-releases → Added "master" to `prerelease_indicators` list in all registry clients → Prevents unwanted dev/master tag updates when "Include Prereleases" is disabled
- • **Automatic Rollback After Max Retries** - Updates now automatically rollback after 3 failed retry attempts → When max retries reached, system attempts automatic rollback if backup exists → Update status set to "rolled_back" on successful auto-rollback → Provides clear error messages if auto-rollback fails or no backup available
- • **Health Check Error Reporting** - Fixed misleading DNS errors masking actual container failures → Health check now reports actual container status (e.g., "Container exited") instead of HTTP/DNS errors → Docker inspect error messages now properly propagated when container has crashed → Separate tracking of HTTP errors vs container runtime errors for better debugging
v2.4.3 2025-11-15
✨ Added
- • **Rollback Option in Overview** - Added rollback card to container Overview tab after successful updates → Appears alongside "Up to Date" status in a split layout (50/50) → Shows previous version and timestamp with yellow accent border → Uses existing rollback functionality from History tab
🐛 Fixed
- • **Duplicate Update Cards** - Fixed issue where failed updates would create duplicate cards during retry attempts → Updated deduplication query in `UpdateChecker` to include `pending_retry` and `approved` statuses → Prevents new update records from being created when updates are already in retry or approved state
- • **Unknown Status Display** - Fixed `pending_retry` status showing as "Unknown Update" in the UI → Added `pending_retry` status support to `StatusBadge` component with orange styling → Status now displays correctly as "pending_retry" instead of generic unknown state
- • **Updates Page Clutter** - Applied updates now hidden from "All" tab to reduce clutter → Applied updates remain accessible via the "Applied" filter tab
- • **History Status Colors** - Replaced inline status rendering with StatusBadge component for consistent colors → Ensures both 'completed' and 'success' statuses display green in container history → Added 'rolled_back' status with yellow color for consistency
- • **About Page Version Display** - Fixed version showing "1.0.0" instead of actual version (2.4.3) → Improved default state to show "Loading..." while fetching version from API
🔄 Changed
- • **Success Status Styling** - Success status badges now display in green for better visual feedback → Changed success status color from gray to green (`bg-green-500/20 text-green-400 border-green-500/30`) → Provides clear visual distinction between successful and failed operations
v2.4.2 2025-11-14
🐛 Fixed
- • **Docker Restart Policy Display** - Fixed inaccurate restart policy showing "manual" for all containers → Added `get_restart_policy()` method to `DockerStatsService` to read from Docker runtime → Added `_sync_restart_policies()` to `ComposeParser` to sync policies during container discovery → Now correctly displays actual Docker restart policy (no, on-failure, always, unless-stopped) → Syncs on every container sync operation
✨ Added
- • **TideWatch Auto-Restart Badge** - Visual indicator for intelligent auto-restart feature → Added teal badge with RefreshCw icon to container cards when auto-restart is enabled → Displays alongside Docker restart policy for clear differentiation → Shows "Docker: {policy}" for native Docker restart + "Auto-Restart" badge for TideWatch feature → Helps users quickly identify which containers have intelligent restart management enabled
🔄 Changed
- • **Container Card Restart Info** - Improved clarity between Docker and TideWatch restart features → Renamed label from "Restart:" to "Docker:" to clarify it's the Docker native restart policy → Layout now shows both Docker policy (left) and TideWatch badge (right) when both are present → Bottom section only appears if at least one restart feature is configured
v2.4.1 2025-11-14
🐛 Fixed
- • **Auto-Restart Disable Bug** - Fixed SQLAlchemy async session error when disabling auto-restart → Added missing `await db.refresh(state)` after commit in disable endpoint → Error was: `MissingGreenlet: greenlet_spawn has not been called` during Pydantic validation → All other endpoints (enable, reset, pause, resume) already had proper refresh logic
🔄 Changed
- • **Auto-Restart Slider Styling** - Updated configuration slider colors to teal (`accent-teal-500`) → Applied to Max Attempts, Base Delay, Max Delay, and Success Window sliders
- • **Settings Tab Layout** - Converted to responsive CSS columns (masonry-style) layout → Uses `columns-1 xl:columns-2` for natural card flow across columns → Cards maintain their natural widths and heights with `break-inside-avoid` → Single column on mobile/tablet (< 1280px), two columns on desktop (≥ 1280px) → Cards stack naturally in columns without forced equal widths → All five settings sections (Auto-Restart, Health Check, Release Source, Dependency Management, Update Window) flow into columns based on available space
v2.4.0 2025-11-13
✨ Added
- • **Real-time Event Streaming** - Server-Sent Events (SSE) for live update notifications → EventSource-based SSE client with automatic reconnection and exponential backoff → Toast notifications for update available, update applied, update failed, container restarted, health check failed → Connection status indicator (Live/Reconnecting/Offline) in bottom-right corner → Graceful cleanup and heartbeat ping support → Created `useEventStream` hook for centralized event handling
- • **Enhanced Log Viewer** - Powerful log analysis and management features → Search/filter functionality with case-insensitive text matching → Log level syntax highlighting (ERROR in red, WARN in yellow, INFO in blue, DEBUG in gray) → Copy to clipboard button for selected/filtered logs → Download logs as .txt file with timestamp → Follow mode toggle for auto-scrolling to latest logs → Adjustable tail lines selector (100, 500, 1000, All) → Visual feedback for filtered results
- • **Better Backup Management UI** - Enhanced backup safety and information display → File size display with both bytes and MB formatting → Relative timestamps ("2 hours ago") with full datetime on hover → Safety backup visual indicators (Shield icon, protected badge) → Delete confirmation modal with backup details (filename, size, date) → Restore preview modal showing backup size vs current database size → Safety backup protection (automatic creation before restore, cannot delete) → Improved UX with detailed warning messages
- • **Metrics History Improvements** - Advanced metrics visualization and export → CSV export functionality with timestamp and all metric columns → Multi-metric comparison mode for CPU + Memory (dual Y-axes) → Better axis labels with units (%, MB, MB/s) → Export button with data validation → Comparison toggle for correlating CPU and Memory usage → Enhanced chart tooltips and formatting
🔄 Changed
- • **Migrated toast library** from react-hot-toast to sonner for consistency → Unified toast notifications across all pages → Removed react-hot-toast dependency → Updated ContainerModal to use sonner → Improved toast styling with dark theme integration
- • **Improved UI/UX polish** across multiple components → Better visual hierarchy with consistent spacing → Enhanced button groups and action controls → Improved modal designs with semantic color coding → Better mobile responsiveness for backup and log viewer
🗑️ Removed
- • react-hot-toast dependency (replaced with sonner)
v2.3.0 2025-11-13
✨ Added
- • **Intelligent Auto-Restart Configuration UI** - Complete frontend interface for container restart management → Real-time restart state display (consecutive failures, total restarts, current backoff, max retries status) → Comprehensive configuration panel with backoff strategy selection (exponential/linear/fixed) → Configurable max attempts, base delay, max delay, and success window sliders → Health check integration with timeout configuration → Rollback on health fail toggle → Pause/Resume controls with duration selector → Reset state button to clear failure counters → Visual indicators for paused state and retry limits
- • **Dependency Management UI** - Control container update order based on dependencies → Add/remove container dependencies with visual tags → Automatic bidirectional dependency tracking (dependencies ↔ dependents) → Select from all available containers to set as dependencies → Read-only display of containers that depend on this container → Circular dependency prevention via backend validation
- • **Update Window Scheduling UI** - Restrict updates to specific time periods → Configure time-based update windows with format validation → Quick preset buttons for common scenarios: → Night Window (02:00-06:00 daily) → Weekends Only (Sat,Sun:00:00-23:59) → Weeknights (Mon-Fri:22:00-06:00) → Weekend Mornings (Sat,Sun:02:00-10:00) → Support for day-specific windows (Mon-Fri, Sat,Sun, etc.) → Support for windows that cross midnight → Clear button to remove restrictions → Format help with examples
- • **New API Service Methods** - Frontend API client expanded with: → Complete restart API integration (getState, enable, disable, reset, pause, resume, getHistory, manualRestart, getStats) → Dependency management endpoints (getDependencies, updateDependencies) → Update window endpoints (getUpdateWindow, updateUpdateWindow) → Auto-detection endpoints (detectHealthCheck, detectReleaseSource)
- • **TypeScript Type Definitions** - Added comprehensive types for: → RestartState, EnableRestartConfig, RestartLog, RestartStats → DependencyInfo → UpdateWindowInfo → AnalyticsSummary → ServerEvent for future event streaming
🔄 Changed
- • Updated Auto-Restart toggle to properly integrate with backend API → Now calls `/restarts/{id}/enable` and `/restarts/{id}/disable` endpoints → Saves complete configuration when enabling → Shows expanded configuration panel when enabled
- • Enhanced ContainerModal with new Settings tab sections → Auto-Restart section expanded with state display and configuration → Added Dependency Management section after Release Source → Added Update Window section after Dependency Management
- • Improved visual consistency across all new sections → Consistent dark theme (bg-gray-700/50, bg-gray-800, border-gray-600) → Primary color accents for interactive elements → Icon badges for section headers (RotateCw, Network, Calendar)
🐛 Fixed
- • Fixed duplicate "Release Source" field in Settings tab → Removed older "Release Notes Source" section (lines 1048-1078) → Kept newer "Release Source" section with auto-fill button
- • Fixed Python package discovery issue in pyproject.toml → Added `[tool.setuptools.packages.find]` configuration → Explicitly includes `app*` packages
v2.2.1 2025-11-12
🐛 Fixed
- • **CRITICAL:** Fixed event bus race condition causing runtime errors → Added list copy in publish method to prevent modification during iteration → Added proper logging for slow consumer removal
- • **Fixed HTTPS mixed content errors** when running behind Traefik with Authentik forward auth → Added trailing slashes to frontend API calls (`/containers/`, `/updates/`, `/history/`) → Prevents FastAPI 307 redirects that were downgrading HTTPS to HTTP → Resolves browser blocking of HTTP resources on HTTPS pages
- • Fixed HTTP client resource leaks → Added `__aenter__`/`__aexit__` context managers to RegistryClient, VulnForgeClient, and NtfyService → Ensures proper cleanup of HTTP connections
- • Fixed Dashboard N+1 query problem → Replaced O(n*m) `.some()` calls with O(1) Map lookup → Improves performance with large container counts
- • Fixed unsafe UTC datetime usage (Python 3.12+ deprecation) → Replaced `datetime.utcnow()` with `datetime.now(timezone.utc)` across codebase
- • Fixed missing HTTP client timeout in health check requests
- • Fixed useEffect dependency ordering in Dashboard component
⚡ Performance
- • **Added registry tag caching** (15-minute TTL) → In-memory cache for all registry clients (DockerHub, GHCR, LSCR, GCR, Quay) → Reduces redundant API calls by up to 90% → Automatic expiration and cleanup → Cache hit/miss logging for debugging
- • **Added dependency resolution caching** → MD5-based cache keys for topological sort results → 100-entry LRU eviction policy → Automatic cache invalidation when dependencies change → Significantly improves bulk update ordering performance
- • **Migrated Docker CLI to SDK in ContainerMonitorService** → Replaced subprocess `docker inspect` calls with Docker Python SDK → Better error handling and performance → Eliminates shell overhead
- • Added database connection pooling → pool_size: 10 concurrent connections → max_overflow: 20 additional connections during peak load → pool_recycle: 3600 seconds (1 hour) → pool_pre_ping: enabled for connection health checks
- • Added database indexes to frequently queried columns → Container: `update_available`, `policy`, `last_checked` → Update: `status` → UpdateHistory: `status`, `started_at`, `created_at` → Improves query performance for dashboard and filtering operations
✨ Added
- • **Prometheus metrics endpoint** at `/metrics` → Container metrics: total, with updates, by policy, by registry → Update metrics: pending, approved, rejected, applied, failed → History metrics: success, failed, rolled back → Compatible with standard Prometheus scrapers → Automatically collects current state from database
- • **Configurable timing values** for health checks and restarts → `health_check_retry_delay`: Initial delay between health check retries (default: 5s) → `health_check_use_exponential_backoff`: Enable exponential backoff (default: true) → `health_check_max_delay`: Maximum delay for exponential backoff (default: 30s) → `container_startup_delay`: Wait time after container restart before health check (default: 2s)
- • **Exponential backoff for health checks** → Implements 5s → 10s → 20s → 30s backoff pattern → Reduces load on failing services during health check retries → Applied to both HTTP exceptions and non-200 status codes → Configurable via settings (can be disabled for fixed delay)
- • **Frontend code splitting for large components** → Lazy-loaded ContainerModal component (1204 lines, ~40KB) → Modal only loads when opened, reducing initial bundle size → Added Suspense boundary with loading spinner
- • **Container health status** in container details API → Real-time health check using ContainerMonitorService → Returns status: "healthy", "unhealthy", or "stopped" → Includes last health check timestamp
📝 Improved
- • **Type hints coverage** - Added return type hints to 15+ functions → All `__init__` methods now have `-> None` return type → Async context managers (`__aenter__`, `__aexit__`) have proper typing → Utility and service methods include return type annotations → Improves IDE autocomplete and static analysis
📝 Technical Notes
- • See `/srv/raid0/docker/documents/history/tidewatch/2025-11-15-dependency-updates-granian-tailwind-v4-migration.md` for Tailwind v4 migration details
- • See `/srv/raid0/docker/documents/history/tidewatch/2025-11-15-endpoint-logging-filter.md` for logging enhancements
v2.2.0 2025-11-12
🔄 Changed
- • **MAJOR:** Migrated from Tailwind CSS v3 to v4 → Updated PostCSS configuration to use `@tailwindcss/postcss` plugin → Migrated CSS imports from `@tailwind` directives to `@import "tailwindcss"` → Moved configuration from JavaScript to CSS-based `@theme` directive → Custom color theme (primary/accent) now defined as CSS custom properties
- • Updated frontend dependencies: → `react-router-dom`: 7.3.1 → 7.9.6 → `lucide-react`: 0.468.0 → 0.553.0 (now includes 1,647 icons) → `sonner`: 1.7.0 → 2.0.7 → `@typescript-eslint/*`: 8.46.3 → 8.46.4 → `eslint-plugin-react-refresh`: 0.4.16 → 0.4.24 → `autoprefixer`: 10.4.21 → 10.4.22 → `postcss`: 8.4.42 → 8.5.6
- • Removed `tailwind.config.js` (no longer needed in Tailwind v4)
- • Improved build script by removing `tsc &&` prefix for faster builds
📝 Technical Notes
- • Tailwind v4 requires modern browsers (Safari 16.4+, Chrome 111+, Firefox 128+)
- • Theme colors are now CSS variables for better runtime flexibility
v2.1.1 2025-11-12
🔄 Changed
- • **MAJOR:** Migrated from uvicorn to Granian ASGI server → Updated `Dockerfile` to use Granian with single worker configuration → Changed logger filter in `app/main.py` from `uvicorn.access` to `granian.access` → Granian provides ~15-20% memory reduction and better async handling
- • Updated backend dependencies to latest stable versions: → `fastapi`: 0.115.0 → 0.121.2 → `sqlalchemy`: 2.0.36 → 2.0.44 (improved async support) → `pydantic`: 2.9.0 → 2.12.0 (minor behavior changes in dataclass Field handling) → `apscheduler`: 3.10.4 → 3.11.1 (dependency cleanup) → `docker`: 7.0.0 → 7.1.0
- • Updated frontend dependencies: → `typescript`: 5.7.4 → 5.9.3 (stable version) → `eslint-plugin-react-hooks`: 5.1.0 → 7.0.0 (⚠️ avoid 7.0.1 - broken resolution)
⚡ Performance
- • Reduced memory footprint with Granian's Rust-based architecture
- • Better async request handling and backpressure management
- • Auto-tuned thread configuration for optimal performance
📝 Technical Notes
- • Single worker required due to stateful APScheduler service
- • Granian is fully ASGI-compliant and a drop-in replacement for uvicorn
v2.1.0 2025-11-11
✨ Added
- • Initial stable release of TideWatch
- • Intelligent Docker container update management
- • Real-time container monitoring and update tracking
- • Integration with VulnForge for security analysis
- • Automated update scheduling with configurable policies
- • Update history tracking and rollback capabilities
- • Comprehensive web UI with dashboard and analytics
📝 Technical Stack
- • Backend: Python 3.14, FastAPI, SQLAlchemy, APScheduler
- • Frontend: React 19, TypeScript, Tailwind CSS
- • Database: SQLite with async support (aiosqlite)
- • Container Management: Docker SDK for Python
- • **2.2.1**: Security fixes + performance optimizations
- • **2.2.0**: Tailwind v4 migration + dependency updates
- • **2.1.1**: Granian migration + backend dependency updates
- • **2.1.0**: Initial stable release
Key Features
Update Workflow
Pending updates queue up for review. Approve, reject, or snooze them. See release notes and CVE changes before deciding.
VulnForge Integration
Every update shows vulnerability counts for old vs new images. "Security" policy containers only auto-update when CVEs go down.
Update Policies
Per-container policies: manual (you approve everything), auto (updates immediately), security (only if CVEs decrease), or disabled.
Compose-Aware
Point it at your compose files and it discovers services automatically. Updates use your compose config, not raw docker commands.
Multi-Registry Support
Checks Docker Hub, GitHub Container Registry, and LinuxServer.io for updates. Handles digest-based version tracking.
Dependency Scanning
Scans containers for HTTP servers, Dockerfile base images, and npm/pip packages. Shows what's outdated inside your running containers.
Update History
Full audit trail of every update: what version, when it happened, how long it took, whether it succeeded or failed.
Multi-Service Notifications
Push notifications via ntfy, Gotify, Pushover, Slack, Discord, Telegram, or Email. Event-based routing with per-service configuration.
Light/Dark Theme
Toggle between light and dark themes. Your preference syncs across devices and persists in the database.
Why Not Just Use Watchtower?
You want to review updates first
Watchtower updates everything automatically. TideWatch lets you see what changed and decide if you want it.
You care about security
TideWatch shows CVE counts before and after. You can require updates to actually fix vulnerabilities, not introduce them.
You use docker-compose
TideWatch respects your compose files. It runs `docker compose up -d`, not raw docker commands that ignore your config.
You want to know what happened
Full history of every update with timestamps, durations, and success/failure status. Debug at 3am with actual data.
Screenshots
Dashboard
At-a-glance view of all containers with update frequency stats, CVE resolution tracking, and policy distribution. My Projects section highlights development containers separately from infrastructure.
Updates Management
Review and manage container updates with workflow states (Pending, Approved, Rejected, Stale, Applied). Expandable release notes and CVE fix indicators help make informed update decisions.
Update History
Complete audit trail of all container updates with version transitions, duration tracking, timestamps, and performer attribution for compliance and troubleshooting.
Notification Settings
Multi-service notification configuration with support for ntfy, Gotify, Pushover, Slack, Discord, Telegram, and Email. Event-based routing lets you control exactly what notifications you receive.
Container Details
Deep-dive into individual containers with a tabbed interface covering overview, metrics, logs, history, dependencies, and settings.
Overview
Metrics
Live Logs
Dependencies
