update: enhance README with detailed service descriptions and quick start guide; remove deprecated Calibre service from docker compose

README.md

@@ -1,3 +1,249 @@
-# home-server
+# Home Server Services
 
-Collection of all resources deployed on my home server.
+Collection of all resources deployed on my home server. This repository contains Docker Compose configurations for various services organized by category.
+
+## Quick Start
+
+1. Navigate to the service directory you want to deploy
+2. Copy `env.example` to `.env` and configure the variables
+3. Run `docker compose up -d` to start the services
+
+## Directory Structure
+
+```
+komodo/
+├── arr/                    # ARR (Automated Media Management) Services
+├── automate/               # Automation & Workflow Tools
+├── common/                 # Common/Shared Services
+├── media-server/           # Media Server Applications
+├── general-purpose/        # General Purpose Applications
+└── monitor/                # Monitoring & Tracking Services
+```
+
+---
+
+## 📺 ARR Services (`komodo/arr/`)
+
+The ARR stack is a collection of automated media management tools for organizing and downloading movies, TV shows, music, books, and more.
+
+### arrs/ (`komodo/arr/arrs/`)
+
+Main collection of ARR services for different media types:
+
+- **Radarr** (Port: 7878) - Movie collection manager. Automatically monitors and downloads movies.
+- **Sonarr** (Port: 8989) - TV series collection manager. Monitors TV shows and manages episodes.
+- **Lidarr** (Port: 8686) - Music collection manager. Organizes and downloads music.
+- **Bookshelf** (Port: 8787) - Book collection manager. Alternative to Readarr for managing ebooks.
+- **Bazarr** (Port: 6767) - Subtitle manager. Automatically downloads subtitles for movies and TV shows.
+- **Jellyseerr** (Port: 5055) - Request management for media. Handles user requests for movies and TV shows.
+- **Prowlarr** (Port: 9696) - Indexer manager. Manages torrent/usenet indexers for all ARR services.
+- **Profilarr** (Port: 6868) - Profile manager for ARR services. Helps manage quality profiles across services.
+
+**Configuration:** Requires `CONFIG_PATH`, `DATA_PATH`, `PUID`, `PGID`, and `TZ` environment variables.
+
+### dispatcharr/ (`komodo/arr/dispatcharr/`)
+
+- **Dispatcharr** (Port: 1866) - Task dispatcher for ARR services. Coordinates and manages tasks across multiple ARR instances.
+
+**Configuration:** No environment variables required. Uses named volumes for data persistence.
+
+### dizquetv/ (`komodo/arr/dizquetv/`)
+
+- **DizqueTV** (Port: 8000) - Creates virtual TV channels from your media library. Streams your media as traditional TV channels.
+- **ErsatzTV** (Port: 8409) - Alternative virtual TV channel generator. Creates IPTV channels from local media.
+
+**Configuration:** No environment variables required. Uses named volumes for data persistence.
+
+### download-clients/ (`komodo/arr/download-clients/`)
+
+Download clients for fetching media:
+
+- **Transmission-OpenVPN** (Port: 9092) - BitTorrent client with VPN support via Private Internet Access (PIA). Provides secure torrenting.
+- **SABnzbd** (Port: 6798) - Usenet downloader. Downloads files from Usenet newsgroups.
+- **PIA qBittorrent** (Port: 8888) - qBittorrent client with PIA VPN integration. Alternative torrent client with built-in VPN.
+
+**Configuration:** Requires PIA VPN credentials, network configuration, and path variables.
+
+---
+
+## 🎬 Media Servers (`komodo/media-server/`)
+
+Media server applications for organizing and streaming your media library.
+
+### audio-bookshelf/ (`komodo/media-server/audio-bookshelf/`)
+
+- **AudioBookShelf** (Port: 13378) - Self-hosted audiobook and ebook server. Organizes and streams audiobooks, ebooks, and podcasts with a beautiful web interface.
+
+**Configuration:** Media paths are configured directly in compose.yaml. No environment variables required.
+
+### booklore/ (`komodo/media-server/booklore/`)
+
+- **Booklore** - Modern ebook library manager with a focus on organization and metadata management. Includes MariaDB database for data storage.
+
+**Configuration:** Requires database credentials, user/group IDs, and application port configuration.
+
+### deprecated/calibre/ (`komodo/media-server/deprecated/calibre/`)
+
+- **Calibre** - Ebook library management system. Organizes, converts, and manages your ebook collection.
+
+**Configuration:** No environment variables currently configured.
+
+**Note:** This service is in the deprecated directory.
+
+---
+
+## ⚙️ Automation (`komodo/automate/`)
+
+Automation and workflow tools for streamlining tasks and processes.
+
+### n8n/ (`komodo/automate/n8n/`)
+
+- **n8n** (Port: 5678) - Workflow automation tool. Create automated workflows with a visual interface. Similar to Zapier but self-hosted.
+
+**Configuration:** Requires timezone configuration. Additional runners can be enabled.
+
+### node-red/ (`komodo/automate/node-red/`)
+
+- **Node-RED** (Port: 1880) - Flow-based programming tool. Visual programming for connecting hardware devices, APIs, and online services.
+
+**Configuration:** No environment variables required. Uses named volumes for data persistence.
+
+### semaphore/ (`komodo/automate/semaphore/`)
+
+- **Semaphore** (Port: 3000) - Ansible automation platform. Provides a web UI for managing Ansible playbooks and deployments. Includes MySQL database.
+
+**Configuration:** Requires database credentials, email configuration for notifications, and user/group IDs.
+
+---
+
+## 🛠️ General Purpose (`komodo/general-purpose/`)
+
+Various general-purpose applications for different use cases.
+
+### actual-budget/ (`komodo/general-purpose/actual-budget/`)
+
+- **Actual Budget** (Port: 5006) - Personal finance and budgeting application. Local-first budgeting tool with sync capabilities.
+
+**Configuration:** No environment variables required. Uses named volumes for data persistence.
+
+### bookstack/ (`komodo/general-purpose/bookstack/`)
+
+- **BookStack** (Port: 6875) - Documentation and wiki platform. Knowledge management system with a book-like structure. Includes MariaDB database.
+
+**Configuration:** Requires database credentials, application key, SAML2/OAuth configuration (optional), SMTP settings, and application URL.
+
+### flink/ (`komodo/general-purpose/flink/`)
+
+- **Flink** (Port: 8080) - Streaming analytics platform. Real-time data processing and analytics engine.
+
+**Configuration:** No environment variables required. Uses default configuration.
+
+### grocy/ (`komodo/general-purpose/grocy/`)
+
+- **Grocy** (Port: 9283) - Household management system. Tracks groceries, chores, recipes, and more for household organization.
+
+**Configuration:** Requires user/group IDs and timezone configuration.
+
+### hortusfox/ (`komodo/general-purpose/hortusfox/`)
+
+- **HortusFox** (Port: 8080) - Garden management application. Tracks plants, watering schedules, and garden activities. Includes MariaDB database.
+
+**Configuration:** Requires database credentials and admin account configuration.
+
+### it-tools/ (`komodo/general-purpose/it-tools/`)
+
+- **IT Tools** (Port: 1234) - Collection of useful IT tools. Web-based utilities for developers and IT professionals.
+
+**Configuration:** No environment variables required. Simple web application.
+
+### mealie/ (`komodo/general-purpose/mealie/`)
+
+- **Mealie** (Port: 9925) - Recipe management and meal planning platform. Organize recipes, plan meals, and manage grocery lists. Includes PostgreSQL database.
+
+**Configuration:** Requires database password, base URL, OIDC/OAuth configuration (optional), and OpenAI API key (optional for AI features).
+
+### open-webui/ (`komodo/general-purpose/open-webui/`)
+
+- **Open WebUI** (Port: 11674) - Web UI for LLM (Large Language Model) applications. Provides a chat interface for OpenAI, Anthropic, and other AI models.
+
+**Configuration:** Requires API keys (OpenAI/Anthropic), OAuth configuration (optional), and redirect URI.
+
+---
+
+## 🔧 Common Services (`komodo/common/`)
+
+Shared services used across multiple applications.
+
+### newt/ (`komodo/common/newt/`)
+
+- **Newt** - Service integration tool. Connects with Pangolin endpoint for service management and integration.
+
+**Configuration:** Requires Pangolin endpoint URL, Newt ID, and Newt secret.
+
+---
+
+## 📊 Monitoring (`komodo/monitor/`)
+
+Services for monitoring and tracking various aspects of your home server.
+
+### tracearr/ (`komodo/monitor/tracearr/`)
+
+- **Tracearr** (Port: 3000) - Monitoring and tracking tool for ARR services. Tracks requests, downloads, and activity across your ARR stack. Includes PostgreSQL and Redis.
+
+**Configuration:** Requires port, timezone, and log level configuration. Secrets are auto-generated by default.
+
+---
+
+## Environment Variables
+
+Each service directory contains an `env.example` file that documents all required and optional environment variables. To use a service:
+
+1. Copy the `env.example` file to `.env` in the same directory
+2. Fill in the required values
+3. Adjust optional settings as needed
+4. Run `docker compose up -d`
+
+### Common Variables
+
+Many services use these common variables:
+
+- **PUID** - User ID (find with `id -u`)
+- **PGID** - Group ID (find with `id -g`)
+- **TZ** - Timezone (e.g., `America/New_York`, `Europe/London`, `UTC`)
+- **CONFIG_PATH** - Base path for configuration files
+- **DATA_PATH** - Base path for data/media files
+
+---
+
+## Notes
+
+- All services use Docker Compose for orchestration
+- Most services include health checks and restart policies
+- Services are configured to use named volumes for data persistence
+- Port mappings can be adjusted in the compose files if needed
+- Some services integrate with authentication providers (like Authentik) for SSO
+- VPN-enabled download clients require VPN provider credentials
+
+---
+
+## Service Dependencies
+
+Some services depend on others:
+
+- **ARR Services** typically connect to download clients (Transmission, qBittorrent, SABnzbd)
+- **Jellyseerr** connects to media servers (Jellyfin/Plex) and ARR services
+- **Bazarr** connects to Radarr and Sonarr for subtitle management
+- **Prowlarr** connects to all ARR services to provide indexers
+- **Tracearr** monitors ARR services
+- Services with databases (BookStack, Mealie, Booklore, HortusFox, Semaphore) include their database containers
+
+---
+
+## Contributing
+
+When adding new services:
+
+1. Create a new directory under the appropriate category
+2. Add a `compose.yaml` file
+3. Create an `env.example` file documenting all environment variables
+4. Update this README with service description and configuration requirements

komodo/arr/arrs/env.example

@@ -0,0 +1,12 @@
+# Common paths - adjust these to match your server setup
+CONFIG_PATH=/path/to/config
+DATA_PATH=/path/to/data
+
+# User and Group IDs - run `id` command to find your IDs
+PUID=1000
+PGID=100
+
+# Timezone - adjust to your timezone (e.g., America/New_York, Europe/London)
+# Used by: radarr, sonarr, lidarr, bookshelf, bazarr, jellyseerr, prowlarr, profilarr
+TZ=Canada/Eastern
+

komodo/arr/dispatcharr/env.example

@@ -0,0 +1,4 @@
+# Dispatcharr - No environment variables required
+# This service uses a named volume for data persistence
+# Access the web UI at http://localhost:1866
+

komodo/arr/dizquetv/env.example

@@ -0,0 +1,4 @@
+# DizqueTV - No environment variables required
+# This service uses named volumes for data persistence
+# Access the web UI at http://localhost:8000
+

komodo/arr/download-clients/env.example

@@ -0,0 +1,18 @@
+# Common paths
+DATA_PATH=/path/to/data
+
+# User and Group IDs - run `id` command to find your IDs
+PUID=1000
+PGID=100
+
+# Private Internet Access (PIA) VPN Configuration
+# Required for transmission-openvpn and pia-qbittorrent
+PIA_OPENVPN_CONFIG=CA Toronto
+PIA_REGION=ca-toronto
+PIA_USERNAME=your_pia_username
+PIA_PASSWORD=your_pia_password
+
+# Network configuration for transmission-openvpn
+# Adjust to match your local network subnet
+LOCAL_NETWORK=192.168.50.0/24
+

komodo/automate/n8n/env.example

@@ -0,0 +1,8 @@
+# n8n - Timezone configuration
+TZ=ETC
+GENERIC_TIMEZONE=America/New_York
+
+# Optional: Additional n8n configuration
+# N8N_RUNNERS_ENABLED=true
+# N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
+

komodo/automate/node-red/env.example

@@ -0,0 +1,4 @@
+# Node-RED - No environment variables required
+# This service uses a named volume for data persistence
+# Access the web UI at http://localhost:1880
+

komodo/automate/semaphore/env.example

@@ -0,0 +1,18 @@
+# User and Group IDs
+PUID=1000
+PGID=100
+
+# Database Configuration
+SEMAPHORE_DB_HOST=semaphore_db
+SEMAPHORE_DB_NAME=semaphore
+SEMAPHORE_DB_USER=semaphore_user
+SEMAPHORE_DB_PASS=your_secure_db_password
+
+# Email Configuration (for notifications)
+SEMAPHORE_EMAIL_SENDER=semaphore@yourdomain.com
+SEMAPHORE_EMAIL_HOST=smtp.yourdomain.com
+SEMAPHORE_EMAIL_PORT=587
+SEMAPHORE_EMAIL_USERNAME=smtp_username
+SEMAPHORE_EMAIL_PASSWORD=smtp_password
+SEMAPHORE_EMAIL_SECURE=false
+

komodo/common/newt/env.example

@@ -0,0 +1,5 @@
+# Newt Configuration
+PANGOLIN_ENDPOINT=your_pangolin_endpoint_url
+NEWT_ID=your_newt_id
+NEWT_SECRET=your_newt_secret
+

komodo/general-purpose/actual-budget/env.example

@@ -0,0 +1,4 @@
+# Actual Budget - No environment variables required
+# This service uses a named volume for data persistence
+# Access the web UI at http://localhost:5006
+

komodo/general-purpose/bookstack/env.example

@@ -0,0 +1,45 @@
+# User and Group IDs
+PUID=1000
+PGID=100
+
+# Timezone
+TZ=Etc/UTC
+
+# Application URL - set to the base URL where BookStack will be accessed
+APP_URL=http://localhost:6875
+
+# Application Key - Generate using:
+# docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
+API_KEY=base64:your_generated_app_key_here
+
+# Database Configuration
+DB_DATABASE=bookstack
+DB_USERNAME=bookstack_user
+DB_PASSWORD=your_secure_db_password
+DB_ROOTPASS=your_secure_root_password
+
+# Authentication Method (optional, defaults to standard)
+# Options: standard, saml2
+AUTH_METHOD=saml2
+AUTH_AUTO_INITIATE=false
+
+# SAML2 Configuration (for Authentik or other SAML providers)
+SAML2_NAME=Authentik
+SAML2_EMAIL_ATTRIBUTE=email
+SAML2_EXTERNAL_ID_ATTRIBUTE=sub
+SAML2_USER_TO_GROUPS=true
+SAML2_GROUP_ATTRIBUTE=groups
+SAML2_DISPLAY_NAME_ATTRIBUTES=displayName
+SAML2_IDP_ENTITYID=https://authentik.yourdomain.com/application/saml/bookstack/sso/binding/
+SAML2_AUTOLOAD_METADATA=https://authentik.yourdomain.com/application/saml/bookstack/sso/binding/
+
+# SMTP Configuration (for email notifications)
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.yourdomain.com
+MAIL_PORT=587
+MAIL_ENCRYPTION=tls
+MAIL_USERNAME=smtp_username
+MAIL_PASSWORD=smtp_password
+MAIL_FROM=noreply@yourdomain.com
+MAIL_FROM_NAME=BookStack
+

komodo/general-purpose/flink/env.example

@@ -0,0 +1,4 @@
+# Flink - No environment variables required
+# This service uses the default configuration
+# Access the web UI at http://localhost:8080
+

komodo/general-purpose/grocy/env.example

@@ -0,0 +1,9 @@
+# User and Group IDs
+PUID=1000
+PGID=100
+
+# Timezone
+TZ=Etc/UTC
+
+# Access the web UI at http://localhost:9283
+

komodo/general-purpose/hortusfox/env.example

@@ -0,0 +1,9 @@
+# Database Configuration
+DB_USERNAME=hortusfox
+DB_PASSWORD=your_secure_db_password
+DB_ROOT_PASSWORD=your_secure_root_password
+
+# Application Configuration
+APP_ADMIN_EMAIL=admin@yourdomain.com
+APP_ADMIN_PASSWORD=your_secure_admin_password
+

komodo/general-purpose/it-tools/env.example

@@ -0,0 +1,4 @@
+# IT Tools - No environment variables required
+# This is a simple web-based tool collection
+# Access the web UI at http://localhost:1234
+

komodo/general-purpose/mealie/env.example

@@ -0,0 +1,21 @@
+# User and Group IDs
+PUID=1000
+PGID=100
+
+# Timezone
+TZ=America/Toronto
+
+# Base URL - set to the base URL where Mealie will be accessed
+BASE_URL=http://localhost:9925
+
+# Database Configuration (PostgreSQL)
+POSTGRES_PASSWORD=your_secure_postgres_password
+
+# OIDC/OAuth Configuration (for Authentik or other OIDC providers)
+OIDC_CONFIGURATION_URL=https://authentik.yourdomain.com/application/o/mealie/.well-known/openid-configuration
+OIDC_CLIENT_ID=your_oidc_client_id
+OIDC_CLIENT_SECRET=your_oidc_client_secret
+
+# OpenAI API Key (optional, for AI features)
+OPENAI_API_KEY=your_openai_api_key
+

komodo/general-purpose/open-webui/env.example

@@ -0,0 +1,17 @@
+# API Keys
+OPEN_API_KEY=your_openai_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+
+# OAuth Configuration (for Authentik or other OIDC providers)
+OPENID_PROVIDER_URL=https://authentik.yourdomain.com/application/o/open-webui/.well-known/openid-configuration
+OAUTH_CLIENT_ID=your_oauth_client_id
+OAUTH_CLIENT_SECRET=your_oauth_client_secret
+OPENID_REDIRECT_URI=http://localhost:11674/auth/oidc/callback
+
+# OAuth Settings (optional, defaults shown)
+# ENABLE_OAUTH_SIGNUP=true
+# OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true
+# OAUTH_PROVIDER_NAME=Authentik
+# OAUTH_SCOPES=openid email profile
+# ENABLE_OAUTH_GROUP_MANAGEMENT=true
+

komodo/media-server/audio-bookshelf/env.example

@@ -0,0 +1,9 @@
+# AudioBookShelf - No environment variables required in compose file
+# Data volumes are mounted directly in the compose.yaml
+# Access the web UI at http://localhost:13378
+# 
+# Note: Media paths are hardcoded in compose.yaml, adjust there if needed:
+# - /mnt/media/books:/ebooks
+# - /mnt/media/audiobooks:/audiobooks
+# - /mnt/media/podcasts:/podcasts
+

komodo/media-server/booklore/env.example

@@ -0,0 +1,21 @@
+# User and Group IDs for the application
+APP_USER_ID=1000
+APP_GROUP_ID=100
+
+# User and Group IDs for the database
+DB_USER_ID=1000
+DB_GROUP_ID=100
+
+# Timezone
+TZ=UTC
+
+# Database Configuration
+DATABASE_URL=mysql://db_user:db_password@mariadb:3306/booklore
+DB_USER=booklore
+DB_PASSWORD=your_secure_db_password
+MYSQL_ROOT_PASSWORD=your_secure_root_password
+MYSQL_DATABASE=booklore
+
+# Booklore Application Port
+BOOKLORE_PORT=8090
+

komodo/media-server/calibre/env.example

@@ -0,0 +1,4 @@
+# Calibre - No environment variables in compose file
+# If you need to add environment variables, add them here
+# Access the web UI at the configured port
+

komodo/media-server/deprecated/calibre/env.example

@@ -0,0 +1,3 @@
+# Calibre - No environment variables in compose file
+# If you need to add environment variables, add them here
+# Access the web UI at the configured port

komodo/monitor/tracearr/env.example

@@ -0,0 +1,13 @@
+# Port - default is 3000
+PORT=3000
+
+# Timezone
+TZ=UTC
+
+# Log Level - options: debug, info, warn, error
+LOG_LEVEL=info
+
+# Optional: Override auto-generated secrets (usually not needed)
+# JWT_SECRET=your_jwt_secret
+# COOKIE_SECRET=your_cookie_secret
+