# Changelog

All notable changes to the portainer-core project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### In Progress
- **Authentik SSO Monitoring:** 24-48 hour stability testing for Organizr SSO before expanding to other services

### Planned
- AI Orchestrator Phase 2: Memory Systems (3-tier architecture with Qdrant) - DEFERRED
- AI Orchestrator Phases 3-6: Multi-agent workflows, tool integration, RAG, production hardening
- Authentik SSO Milestones 4-5: Protect Core API and remaining 9 services
- Disaster recovery and offsite backup strategy

## [0.8.1-authentik-organizr] - 2025-11-21

### Added
- **Standalone Authentik Proxy Outpost**
  - Container: authentik-proxy (port 9445:9443)
  - Redis configuration: redis-shared:6379/0
  - Memory usage: ~150MB
  - API token authentication with Authentik server
  - WebSocket connection to Authentik for config updates
- **Forward Authentication for Organizr**
  - NPM configuration for home.schweitz.net
  - auth_request directive pointing to standalone outpost
  - Authentication header forwarding (X-authentik-username, email, groups, name, uid)
  - Signin redirect handler for unauthenticated requests
  - WebSocket support enabled
- **Documentation**
  - Session summary: [docs/sessions/2025-11-21-authentik-troubleshooting.md](docs/sessions/2025-11-21-authentik-troubleshooting.md)
  - NPM configuration template: [docs/npm-configs/organizr-forward-auth.conf](docs/npm-configs/organizr-forward-auth.conf)
  - Deployment scripts in /tmp for reference

### Fixed
- **Embedded Outpost Issue:** Authentik 2024.8.4 embedded outpost not initializing auth endpoint (version-specific bug)
- **Network Connectivity:** NPM on host network cannot resolve docker-dataplane container names - use localhost:9445
- **NPM Config Generation:** API updates don't generate config files - manually created /data/nginx/proxy_host/2.conf
- **Redirect Loop:** Initial redirect to /outpost.goauthentik.io/start returned 404 - changed to use application domain
- **Post-Login Redirect:** Direct flow redirect sent users to /if/user/#/library - use outpost start endpoint instead
- **Organizr Auto-Login:** Headers set at server level don't forward - moved proxy_set_header to location / block

### Changed
- **Outpost Architecture:** Moved from embedded to standalone for reliability (port 9445:9443)

## [0.8.0-authentik-sso] - 2025-11-20

### Added
- **Authentik Identity Provider** (version 2024.8.4)
  - Server container (port 9000) with 512MB memory limit
  - Worker container with 384MB memory limit
  - Total memory usage: 563MB (80-90% reduction vs previous attempt)
  - Embedded outpost on port 9444
- **Shared Infrastructure Integration**
  - PostgreSQL: authentik database with authentik_user
  - Redis: Database 0 for sessions and cache
  - Docker network: docker-dataplane
- **Google OAuth Integration**
  - OAuth source configured via API
  - Google login button on authentication flow
  - Automatic user creation for external OAuth users
  - Successful test: jpmschweitzer@gmail.com user created
- **NPM Configuration**
  - Reverse proxy for https://auth.schweitz.net
  - Let's Encrypt SSL with HSTS
  - No forward auth on auth.schweitz.net (prevents redirect loops)
- **API Automation**
  - Created proxy provider "Organizr Proxy" via API
  - Created application "Organizr" via API
  - Assigned provider to embedded outpost via API
- **Documentation**
  - Session summary: docs/sessions/2025-11-20-authentik-deployment.md
  - Updated STATUS.md with SSO progress
  - Updated security implementation plan

### Fixed
- Health check failing due to missing wget/curl - switched to Python urllib
- Database user authentik_user not created - manually created with grants
- Port 9443 conflict - mapped to 9444 on host
- NPM proxy host marked as deleted - recreated via UI
- Google OAuth enrollment flow error - cleared browser cookies

### Changed
- Container count: 19 → 21 (added authentik-server, authentik-worker)
- Active priority: AI Orchestrator → Security & SSO Implementation
- Deferred AI Orchestrator Phase 2 to focus on security

### Known Issues
- **Embedded outpost auth endpoint returns 404**
  - Endpoint: `/outpost.goauthentik.io/auth/nginx` not available
  - Ping endpoint works, but auth endpoint not initialized
  - Blocking forward authentication for Organizr
  - Investigating provider mode and initialization sequence

## [0.7.1-gitea-deployment] - 2025-11-14

### Added
- Gitea Git repository hosting service (port 3002, SSH port 2222)
- PostgreSQL database backend for Gitea
- NPM reverse proxy configuration for https://git.schweitz.net with Let's Encrypt SSL
- Uptime Kuma monitoring integration for Gitea
- Organizr dashboard integration for Gitea
- Complete Gitea documentation in CONTAINERS.md

### Changed
- Updated infrastructure status to reflect 19 deployed services

## [0.7.0-ai-orchestrator-phase1] - 2025-11-13

### Added
- AI Orchestrator Phase 1: OpenAI-Compatible API
  - `/v1/chat/completions` endpoint with streaming and non-streaming support
  - `/v1/models` endpoint for model discovery
  - Model aliasing system (gpt-3.5-turbo → gemma:7b, etc.)
  - Ollama client with connection pooling
  - Pydantic request/response schemas
  - Server-Sent Events (SSE) streaming format
- Comprehensive Phase 1 testing suite
  - 10/10 tests passing, zero issues
  - 245ms average response time
  - 100% OpenAI API compatibility verified
- Phase 1 implementation guide and test results documentation

### Fixed
- Model ID formatting issue (removed extra quotes in model names)

### Security
- Deployed on isolated ai-dataplane network

## [0.6.0-applications] - 2025-11-13

### Added
- Nextcloud cloud storage and collaboration platform (port 8082)
  - MariaDB database backend
  - Redis caching
  - NPM reverse proxy with https://cloud.schweitz.net
  - Database optimization (indices, bigint conversion)
  - Cron background jobs via maintenance container
- Samba network file sharing (ports 139/445)
  - Media share (R/W)
  - Downloads share (R/W)
  - Backups share (R/O)
- UFW firewall rules for Samba ports
- Uptime Kuma multi-network bridge for monitoring all services

### Changed
- Disabled host Samba service to prevent port conflicts
- Relocated Nextcloud cron to maintenance container for centralized scheduling

### Fixed
- Uptime Kuma network connectivity issues (added bridges to all service networks)

## [0.5.2-core-api] - 2025-11-13

### Added
- Core API service for Open WebUI integration (port 8083)
- Web scraper module with Trafilatura and BeautifulSoup
- Infrastructure management API (Portainer/NPM/Kuma integration)
- OpenAPI documentation at `/docs` endpoint
- Health check endpoint
- Uptime Kuma monitoring integration
- Organizr dashboard integration

### Changed
- Upgraded system Python from 3.8 (EOL) to 3.12

### Security
- Runs as non-root user (uid 1000)
- CORS configured for same-network access only

## [0.5.1-open-webui] - 2025-11-12

### Added
- Open WebUI LLM chat interface (port 8081)
- Built-in voice capabilities (local STT/TTS)
- Ollama integration for local model inference
- Uptime Kuma monitoring integration
- Organizr dashboard integration (tab + homepage)
- Complete Open WebUI documentation in CONTAINERS.md

## [0.5.0-optimization] - 2025-11-11

### Added
- Phase 4: Optimization & Security
  - Watchtower for automatic container updates (daily at 4 AM)
  - Maintenance container for automated backups and scheduled tasks
  - Automated Docker config backups (daily at 3 AM, 30-day retention)
- Docker log rotation configuration (10MB max, 3 files per container)
- UFW firewall rules (SSH, Tailscale, infrastructure services)

### Security
- Firewall enabled and configured for all public-facing services
- Automated backup system with 30-day retention (~94MB per backup)

## [0.4.0-monitoring] - 2025-11-11

### Added
- Phase 3: Monitoring Stack
  - Uptime Kuma service monitoring (port 3001)
  - Netdata real-time system metrics (port 19999)
  - Heimdall unified dashboard (port 8888)
- Complete monitoring documentation

## [0.3.0-networking] - 2025-11-11

### Added
- Phase 2: Networking & External Access
  - Headscale mesh VPN control server (port 8085)
  - Custom 10.99.0.0/16 network range
  - Homelab user and pre-auth key system
  - Device connection procedures for all platforms
- Headscale setup documentation

## [0.2.0-foundation] - 2025-11-11

### Added
- Phase 1: Foundation Setup
  - Portainer container management (port 8001, host networking)
  - Nginx Proxy Manager reverse proxy (port 81, host networking)
  - Ollama ML model serving (port 11434, GPU-enabled)
  - NVIDIA Container Toolkit (v1.17.9-1 for driver 470 compatibility)
  - GPU management via docker-compose deploy configuration
  - 4TB media drive mounted at /mnt/media
  - User added to docker group

### Fixed
- Docker networking issues (iptables FORWARD chain, host networking solution)
- AMP integration (kept on port 8080, no conflicts)

### Security
- GPU passthrough configured securely
- Storage permissions set for dual-disk strategy

## [0.1.0-planning] - 2025-11-11

### Added
- Initial project structure and documentation
- Comprehensive research document (containers/research.md)
  - Evaluated 8 different home server solutions
  - Identified Portainer + Docker Compose as optimal choice
  - Researched SDN solutions (Headscale vs Tailscale)
- Detailed implementation plan (containers/implementation-plan.md)
  - 4-phase deployment strategy
  - Phase 1: Foundation (Portainer, NPM, Ollama, storage)
  - Phase 2: Networking (Headscale)
  - Phase 3: Monitoring (Uptime Kuma, Netdata, Heimdall)
  - Phase 4: Optimization (Watchtower, backups, security)
  - Application backlog (Jellyfin, Nextcloud, Samba)
- System documentation (SYSTEM.md)
  - Hardware specifications
  - Dual-disk storage configuration
  - Software inventory
- Agent guidelines (AGENTS.md)
  - Project-specific conventions
  - Docker Compose standards
  - GPU service requirements
  - Testing procedures
  - Commit message format
- Project status tracking (STATUS.md)
- Version-controlled infrastructure (stacks/ directory)
- Maintenance automation (scripts/ directory, Makefile)

### Documented
- Storage architecture: SSD (489GB) for configs, HDD (3.7TB) for content
- Port allocation strategy
- AMP game server integration approach
- GPU passthrough requirements for Jellyfin and Ollama
- Security considerations (Headscale, UFW, credentials management)

### Decisions
- **Architecture:** Portainer + Docker Compose (chosen over TrueNAS Scale, Unraid, Proxmox)
  - Reason: No OS reinstall required, leverages existing Docker, minimal storage footprint
- **Reverse Proxy:** Nginx Proxy Manager on port 8000 (unified web interface)
- **SDN:** Headscale (self-hosted Tailscale control server)
- **ML Infrastructure:** Ollama with GPU support (RTX 2080 Ti)
- **Monitoring:** Uptime Kuma + Netdata + Heimdall
- **Storage Strategy:** Dual-disk approach (SSD for performance, HDD for capacity)

---

## Changelog Guidelines

### Categories
Use these categories for changes:
- **Added** - New features, services, or capabilities
- **Changed** - Changes to existing functionality
- **Deprecated** - Soon-to-be-removed features
- **Removed** - Removed features
- **Fixed** - Bug fixes
- **Security** - Security improvements

### Version Numbering
- **Major (X.0.0)**: Breaking changes, major architecture changes
- **Minor (0.X.0)**: New features, service additions, phase completions
- **Patch (0.0.X)**: Bug fixes, configuration tweaks, documentation updates
- **Suffix**: `-planning`, `-alpha`, `-beta` for pre-release stages

### Example Entry Template
```markdown
## [X.Y.Z] - YYYY-MM-DD

### Added
- feat(stack): deployed nginx proxy manager for unified web interface
- feat(ollama): configured GPU passthrough for ML model inference

### Changed
- config(amp): moved from port 8080 to 8081 to avoid conflicts

### Fixed
- fix(storage): corrected permissions on media drive mount

### Security
- chore(firewall): configured UFW rules for service isolation
```

---

*This changelog is updated as features are implemented and phases are completed*