# Cluster Presentation Stack

This directory contains a sanitized, portable, and automated version of a high-performance home server stack. It is designed to be easily deployed on a single host for demonstrations and personal labs.

---

## [Section 1] The Setup Script (setup.sh)

The setup.sh script is the primary entry point. It automates the complex parts of setting up a multi-service Docker environment.

### What it does:
1.  System Audit: Checks for curl, wget, jq, and whiptail. Installs them if missing.
2.  Docker Management: Verifies Docker and Docker Compose. If not found, it installs them via the official Docker script.
3.  Hardware Detection: Identifies your GPU (NVIDIA, AMD, or Intel).
    *   NVIDIA: Prompts to install the nvidia-container-toolkit and configures the Docker runtime.
    *   Others: Provides placeholders for AMD (ROCm) or Intel (OpenVino) and defaults to CPU mode for AI workloads.
4.  Service Selection: Provides an interactive menu to choose which stacks to deploy (Nextcloud, AI, Maps, Automation, etc.).
5.  Blueprint Generation: Creates a ~/cluster directory and builds a custom docker-compose.yml based on your hardware and service choices.
6.  Environment Sync: Copies sample.env to .env in the new directory.
7.  Data Initialization: Prompts for a Map Tile URL and Ollama LLM models to pre-pull.

### How to execute:
```bash
chmod +x setup.sh
./setup.sh
```

---

## [Section 2] Cloudflare Connectivity

To access your services securely from anywhere without opening firewall ports, this stack uses Cloudflare Tunnels.

### 1. Create a Tunnel:
*   Go to the Cloudflare Zero Trust Dashboard (https://one.dash.cloudflare.com/).
*   Navigate to Networks -> Tunnels.
*   Create a new tunnel (e.g., "Home-Cluster").
*   Choose Docker as your environment.
*   Copy the Token: Find the TUNNEL_TOKEN in the provided command and paste it into your .env file.

### 2. Configure API Token (for DDNS):
*   Go to My Profile -> API Tokens in the Cloudflare Dashboard.
*   Create a Token using the Edit zone DNS template.
*   Copy this token to CLOUDFLARE_API_TOKEN in your .env.

---

## [Section 3] Map Tiles (OSM Stack)

The Map stack requires a .osm.pbf database file.

1.  Where to get them: Visit Geofabrik Download Server (https://download.geofabrik.de/).
2.  Selection: Navigate to your region (e.g., North America -> US West -> California).
3.  URL: Right-click the .osm.pbf file link and copy the address. Paste this when prompted by the setup.sh script.
4.  Wait for Import: The first time you start the Map stack, it will run a "prep" container to index the data. This can take anywhere from minutes to hours depending on the size of the region.

---

## [Section 4] Configuration (.env vs docker-compose.yml)

### The .env File:
The sample.env contains all the "secrets" and variables. You must edit this after running the setup script:
*   BASE_DOMAIN: Your primary domain (e.g., example.com).
*   NEXTCLOUD_DOMAIN: The subdomain for Nextcloud (e.g., cloud.example.com).
*   TZ: Your local timezone (e.g., America/Los_Angeles).
*   Passwords: Change every change_me value to a strong password.

### Customizing Hardware:
If you need to change hardware drivers later (e.g., you added a GPU), look for the hardware blocks in docker-compose.yml:
```yaml
# [NVIDIA]
# (NVIDIA-specific config here)
# [/NVIDIA]
```
Simply uncomment the block that matches your new hardware.

---

## [Section 5] Client-Side Setup

### Nextcloud (Files & Collaboration)
*   Desktop: Download the Nextcloud Desktop Client (https://nextcloud.com/install/#install-clients) to sync files like a local drive.
*   Mobile: Available on iOS and Android.
*   Signaling: Once your tunnel is up, your Talk video calls will work over the High-Performance Backend (HPB) included in this stack.

### Obsidian (Knowledge Base & AI RAG)
This stack includes an Obsidian Indexer that feeds your notes into the AI RAG (Retrieval Augmented Generation) system.
1.  Syncing: Use the Syncthing service (included in the stack) to sync your local Obsidian Vault folder to the server's ~/cluster/obsidian/config/Notes directory.
2.  RAG: Once synced, the indexer will automatically process your notes into the Qdrant vector database.
3.  **Usage:** In Open WebUI, you can now "talk" to your notes by selecting the Obsidian collection as a document source.

---

## [Section 6] Final Step
Once .env is configured and your data is staged:
```bash
cd ~/cluster
docker compose up -d
```
Check your logs with docker compose logs -f to monitor the startup process!