# 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]

### Planned
- AI Orchestrator Phase 2: Memory Systems (3-tier architecture with Qdrant)
- AI Orchestrator Phases 3-6: Multi-agent workflows, tool integration, RAG, production hardening
- Centralized database consolidation (PostgreSQL/MySQL container)
- Disaster recovery and offsite backup strategy

## [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*