docs: updated documentation

chutch3 · chutch3 · commit 2ae0f5843b03 · 2026-03-15T01:47:20.000Z
diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ Most homelab setups require weeks of configuration, trial and error, and manual
 
 | Feature | Description |
 |---------|-------------|
-| 🚀 **One-Command Deploy** | Entire infrastructure deployed with `task ansible:deploy:full` |
+| 🚀 **One-Command Deploy** | Entire infrastructure deployed with `task ansible:deploy` |
 | 🔐 **Centralized SSO** | Authentik integrated with 8+ services for unified authentication |
 | 📊 **Full Observability** | Prometheus + Grafana + Loki for metrics, dashboards, and logs |
 | 🔒 **Automatic SSL** | Traefik + Cloudflare for zero-config HTTPS certificates |
@@ -222,7 +222,7 @@ task ansible:bootstrap
 task ansible:cluster:init
 
 # Deploy all services
-task ansible:deploy:full
+task ansible:deploy
 ```
 
 ### 3. Access Your Services
diff --git a/docs/architecture/storage.md b/docs/architecture/storage.md
@@ -433,6 +433,125 @@ volumes:
 
 **Solution:** SQLite database on OCFS2 cluster filesystem
 
+## Ansible Storage Role
+
+The `ansible/roles/storage` role automates the full iSCSI + OCFS2 setup across all cluster nodes. It is invoked during bootstrap and runs only when `iscsi_enabled` is `true`.
+
+### What the Role Does
+
+**`tasks/main.yml`** - Entry point that conditionally includes:
+1. `ocfs2-setup.yml` - Installs `ocfs2-tools`, configures the O2CB cluster daemon, and brings the `homelab` cluster online
+2. `iscsi-mount.yml` - Discovers iSCSI targets, logs in, creates OCFS2 filesystems (first run only), mounts them, and verifies cluster-wide access
+
+**`tasks/ocfs2-setup.yml`** - Configures the OCFS2 cluster stack:
+- Installs `ocfs2-tools` package
+- Writes `/etc/ocfs2/cluster.conf` from a Jinja2 template
+- Enables and starts the `o2cb` systemd service
+- Brings the `homelab` cluster online and verifies status
+
+**`tasks/iscsi-mount.yml`** - Loop-based iSCSI mounting (supports up to 3 mounts):
+- Discovers all iSCSI targets from the NAS via `iscsiadm`
+- Logs into each enabled target and verifies active sessions
+- Creates OCFS2 filesystems on first use (`mkfs.ocfs2`, runs once on manager)
+- Creates mount points and adds entries to `/etc/fstab`
+- Mounts OCFS2 filesystems and verifies write access on every node
+- Runs a cluster test to confirm the shared filesystem is visible across all nodes
+
+### Configuration Variables
+
+All variables are defined in `ansible/inventory/group_vars/all.yml` and sourced from the root `.env` file:
+
+#### Primary iSCSI Mount (`media-apps`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `iscsi_enabled` | `false` | Master switch - enables the storage role |
+| `iscsi_target_ip` | `192.168.86.189` | NAS IP address hosting the iSCSI target |
+| `iscsi_target_port` | `3260` | iSCSI target port |
+| `iscsi_target_iqn` | *(required)* | IQN of the iSCSI target for media-apps |
+| `iscsi_mount_path` | `/mnt/iscsi/media-apps` | Mount point on cluster nodes |
+
+#### Second iSCSI Mount (`app-data`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `iscsi_app_data_enabled` | `false` | Enable the app-data mount |
+| `iscsi_app_data_iqn` | *(required)* | IQN of the iSCSI target for app-data |
+| `iscsi_app_data_mount_path` | `/mnt/iscsi/app-data` | Mount point on cluster nodes |
+
+#### Third iSCSI Mount (`cache`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `iscsi_cache_enabled` | `false` | Enable the cache mount |
+| `iscsi_cache_iqn` | *(required)* | IQN of the iSCSI target for cache |
+| `iscsi_cache_mount_path` | `/mnt/iscsi/cache` | Mount point on cluster nodes |
+
+### How to Enable iSCSI Mounts
+
+**Step 1: Configure iSCSI targets on your NAS**
+
+Create iSCSI LUNs on your NAS (OpenMediaVault, TrueNAS, etc.) and note the IQN for each. Common IQN format:
+```
+iqn.2023-01.com.example:storage.media-apps
+```
+
+**Step 2: Add variables to your `.env` file**
+
+```bash
+# Enable iSCSI storage
+ISCSI_ENABLED=true
+NAS_IP=192.168.1.100               # Your NAS IP
+ISCSI_TARGET_PORT=3260             # Default iSCSI port
+ISCSI_TARGET_IQN=iqn.2023-01.com.example:storage.media-apps
+ISCSI_MOUNT_PATH=/mnt/iscsi/media-apps
+
+# Optional: app-data mount
+ISCSI_APP_DATA_ENABLED=true
+ISCSI_APP_DATA_IQN=iqn.2023-01.com.example:storage.app-data
+ISCSI_APP_DATA_MOUNT_PATH=/mnt/iscsi/app-data
+
+# Optional: cache mount
+ISCSI_CACHE_ENABLED=true
+ISCSI_CACHE_IQN=iqn.2023-01.com.example:storage.cache
+ISCSI_CACHE_MOUNT_PATH=/mnt/iscsi/cache
+```
+
+**Step 3: Run bootstrap to configure storage**
+
+```bash
+# Re-run bootstrap to apply storage configuration
+task ansible:bootstrap
+
+# Or run with the storage tag only
+task ansible:tags -- storage,iscsi
+```
+
+**Step 4: Verify mounts**
+
+```bash
+# Check active iSCSI sessions
+task ansible:cmd -- iscsiadm -m session
+
+# Verify OCFS2 mounts
+task ansible:cmd -- mount | grep ocfs2
+
+# Check iSCSI/OCFS2 reconfigure (if NAS IP changed)
+task ansible:iscsi:reconfigure -- -e "old_nas_ip=192.168.1.100"
+```
+
+### Role Tags
+
+The storage role tasks are tagged for selective execution:
+
+- `storage` - All storage-related tasks
+- `iscsi` - iSCSI-specific tasks (subset of `storage`)
+
+```bash
+# Run only storage tasks during bootstrap
+task ansible:tags -- storage
+```
+
 ## Summary
 
 The hybrid storage architecture provides:
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -105,7 +105,7 @@ task ansible:bootstrap
 task ansible:cluster:init
 
 # Deploy all services
-task ansible:deploy:full
+task ansible:deploy
 ```
 Or deploy specific services only:
 ```bash
@@ -162,7 +162,7 @@ The Homepage dashboard will show all your deployed services!
 
 ```bash
 # Deployment Commands
-task ansible:deploy:full                     # Deploy all services
+task ansible:deploy                     # Deploy all services
 task ansible:deploy:stack -- -e "stack_name=service1"  # Deploy a specific service
 
 # Cluster Management
diff --git a/docs/index.md b/docs/index.md
@@ -75,7 +75,7 @@ A Docker Swarm-based homelab deployment platform that simplifies running multipl
 
     ---
 
-    Deploy everything with `task ansible:deploy:full` after a one-time setup.
+    Deploy everything with `task ansible:deploy` after a one-time setup.
 
 </div>
 
@@ -163,7 +163,7 @@ task ansible:install
 # 5. Deploy everything
 task ansible:bootstrap
 task ansible:cluster:init
-task ansible:deploy:full
+task ansible:deploy
 ```
 
 **That's it!** All services deploy automatically with:
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -84,8 +84,8 @@ Our mission is to create the ultimate self-hosting platform that makes running y
                          ║
 ```
 
-## ✅ MILE 2: Essential Services (25 Deployed)
-**Status:** COMPLETED • **Services Live:** 25
+## ✅ MILE 2: Essential Services (27 Deployed)
+**Status:** COMPLETED • **Services Live:** 27
 
 ### 🏗️ Infrastructure Layer
 - ✅ Technitium DNS - Local DNS server
@@ -120,18 +120,20 @@ Our mission is to create the ultimate self-hosting platform that makes running y
 
 ### 🛡️ Prepper & Resilience
 - ✅ Kiwix - Offline Wikipedia (119GB) + Project Gutenberg + Stack Overflow + Medical knowledge
+- ✅ Kolibri - Offline K-12 educational platform (Khan Academy, CK-12, and more)
 
 ### 🔐 Security & Privacy
 - ✅ Vaultwarden - Password manager (with Authentik SSO)
 
 ### 🤖 AI & Development
 - ✅ LibreChat - AI chat interface
 - ✅ MLflow - ML experiment tracking
+- ✅ Forgejo - Self-hosted Git service with issue tracking and CI/CD
 
 ### 💾 Backup & Recovery
 - ✅ Kopia - Automated encrypted backups to Backblaze B2
 
-**Rest Stop Summary:** Production platform with 25 services ✅
+**Rest Stop Summary:** Production platform with 27 services ✅
 
 ---
 
@@ -196,16 +198,21 @@ Our mission is to create the ultimate self-hosting platform that makes running y
 
 ## 🗺️ The Road Ahead: Future Destinations
 
+### ✅ Recently Completed
+
+| Service | Details |
+|---------|---------|
+| **Forgejo** | Self-hosted Git service with PostgreSQL backend, Authentik OIDC SSO, SSH access on port 2222, and iSCSI storage. Deployed at `git.yourdomain.com` |
+| **Kolibri** | Offline K-12 educational platform with Khan Academy content, hybrid iSCSI + CIFS storage, optional Authentik OIDC. Deployed at `kolibri.yourdomain.com` |
+
 ### 🎯 NEEDS (High Priority - Real Gaps to Fill)
 
 | Need / Current Gap | Solution | Why It Matters |
 |-------------------|----------|----------------|
 | **Document Management & Archival**<br>No system for organizing scanned documents, PDFs, receipts, tax forms, contracts | **Paperless-ngx** | Long-term archival with OCR, tagging, full-text search, automated organization |
 | **File Sync, Calendar, & Contacts**<br>No unified cloud storage replacement or calendar/contacts synchronization | **NextCloud** | Self-hosted file sync across devices, calendar management, contacts storage, document collaboration |
-| **Source Code Hosting**<br>No local git repository with issue tracking and CI/CD capabilities | **Forgejo**<br>(community-driven Gitea fork) | Self-hosted git repos, issue tracking, pull requests, built-in CI/CD pipelines |
 | **Offline AI Assistance**<br>LibreChat requires external API calls - no true offline AI capability | **Ollama**<br>(integrates with LibreChat) | Run LLMs locally for offline AI assistance, privacy, no API costs |
 | **Offline Navigation Maps**<br>Kiwix has OSM Wiki documentation but not actual map tiles for GPS navigation | **OpenStreetMap Tile Server** | Render and serve map tiles locally for offline navigation and mapping apps |
-| **Offline Educational Content**<br>Wikipedia provides general knowledge but lacks structured K-12 curriculum with video lessons | **Kolibri**<br>(Khan Academy content) | Structured learning paths, video lessons, interactive exercises, progress tracking |
 | **Web Page Archiving**<br>No way to preserve important websites before they disappear or change | **ArchiveBox** | Archive critical web pages, articles, and sites for offline reference and preservation |
 
 ---
diff --git a/docs/services/index.md b/docs/services/index.md
@@ -86,13 +86,21 @@ Browse our comprehensive catalog of self-hosted services. Each service is pre-co
 
     **1 service available**
 
+- :material-source-branch: **[Development & CI/CD](#development-cicd)**
+
+    ---
+
+    Self-hosted source code hosting and collaboration
+
+    **1 service available**
+
 - :material-book-open-variant: **[Knowledge & Learning](#knowledge-learning)**
 
     ---
 
     Offline knowledge bases and reference materials
 
-    **1 service available**
+    **2 services available**
 
 - :material-view-dashboard: **[Core Infrastructure](#core-infrastructure)**
 
@@ -1102,6 +1110,52 @@ task ansible:deploy:stack -- -e "stack_name=mlflow"
 
 ---
 
+## Development & CI/CD
+
+### Forgejo {#forgejo}
+
+<div class="service-card">
+
+**Self-hosted lightweight software forge with Git hosting and CI/CD**
+
+- **Domain**: `git.yourdomain.com`
+- **Port**: `3000` (web), `2222` (SSH)
+- **Status**: ✅ Available
+- **Tags**: `development` `git` `ci-cd` `code` `sso`
+
+#### Features
+- Git repository hosting with web interface
+- Issue tracking and pull requests
+- Wiki and project management
+- SSH and HTTPS clone support
+- Built-in CI/CD pipeline (Forgejo Actions)
+- Lightweight Gitea fork by the community
+
+#### Authentik SSO Integration
+- **Method**: OAuth/OIDC
+- Group-based admin rights via `forgejo-admins` group
+- Users can link existing local accounts to SSO
+
+#### Storage Requirements
+- PostgreSQL data: iSCSI mount (`/mnt/iscsi/app-data/forgejo/postgresql`)
+- Git repositories: iSCSI mount (`/mnt/iscsi/app-data/forgejo/data`)
+- Configuration: iSCSI mount (`/mnt/iscsi/app-data/forgejo/config`)
+
+#### Prerequisites
+- iSCSI storage directories created and permissions set
+- PostgreSQL credentials configured
+
+#### Quick Deploy
+```bash
+task ansible:deploy:stack -- -e "stack_name=forgejo"
+```
+
+[Learn more about Forgejo →](https://forgejo.org/)
+
+</div>
+
+---
+
 ## Knowledge & Learning
 
 ### Kiwix {#kiwix}
@@ -1156,6 +1210,49 @@ task ansible:deploy:stack -- -e "stack_name=kiwix"
 
 </div>
 
+### Kolibri {#kolibri}
+
+<div class="service-card">
+
+**Offline educational platform with structured K-12 curriculum content**
+
+- **Domain**: `kolibri.yourdomain.com`
+- **Port**: `8080`
+- **Status**: ✅ Available
+- **Tags**: `knowledge` `offline` `education` `k12` `sso`
+
+#### Features
+- Structured learning paths with video lessons and exercises
+- Khan Academy, CK-12, and other educational content channels
+- User management with learner, coach, and admin roles
+- Classroom and progress tracking for coaches
+- Full-text search across imported content
+- No internet required after content download
+
+#### Authentik SSO Integration
+- **Method**: OAuth/OIDC (via kolibri-oidc-client-plugin)
+- Auto-registration enabled for new users
+
+#### Storage Requirements
+- Application data (SQLite DB, user data): iSCSI mount (`/mnt/iscsi/app-data/kolibri`) - 5-10 GB
+- Educational content (videos, exercises): CIFS mount (`//${NAS_SERVER}/kolibri_content`) - 20-200 GB
+
+#### Prerequisites
+- iSCSI storage for application database
+- CIFS share on NAS for educational content
+- Authentik OIDC provider configured (optional, for SSO)
+
+#### Quick Deploy
+```bash
+task ansible:deploy:stack -- -e "stack_name=kolibri"
+```
+
+**Offline Education**: Provides structured K-12 curriculum access during network outages or for environments with limited connectivity.
+
+[Learn more about Kolibri →](https://learningequality.org/kolibri/)
+
+</div>
+
 ---
 
 ## Core Infrastructure
@@ -1260,9 +1357,10 @@ Consider contributing your service definition to help others!
 | Home Automation | 2 |
 | AI & Chat | 1 |
 | Development & ML | 1 |
-| Knowledge & Learning | 1 |
+| Development & CI/CD | 1 |
+| Knowledge & Learning | 2 |
 | Core Infrastructure | 1 |
-| **Total Application Services** | **25** |
+| **Total Application Services** | **27** |
 
 **Plus 4 Infrastructure Stacks:**
 - Traefik (Reverse Proxy)
diff --git a/docs/user-guide/service-management.md b/docs/user-guide/service-management.md
