Init

2025-10-25 20:11:21 +02:00
commit fd37421245
700 changed files with 211892 additions and 0 deletions
--- a/Cloud/archive/ALTERNATIVES_CONSIDERED.md
+++ b/Cloud/archive/ALTERNATIVES_CONSIDERED.md
@@ -0,0 +1,517 @@
+# Alternatives Considered - Oracle Cloud Project
+
+**Date:** 2025-10-25
+**Status:** Archived for reference
+
+This document captures the alternatives we researched but decided not to pursue for this project.
+
+---
+
+## Git Server: Forgejo vs Gitea
+
+**Decision:** Chose **Gitea** ✅
+**Rationale:** CapRover one-click support, faster setup, adequate for personal use
+
+### Forgejo Deep Dive
+
+**What is Forgejo:**
+- Community-driven fork of Gitea (since Oct 2022)
+- Managed by non-profit Codeberg e.V.
+- Hard fork as of v10.0 (Jan 2025)
+
+**Why Forgejo Would Be Better:**
+
+1. **Security Practices:**
+   - Public security advisories for everyone (vs Gitea's paying-customers-only)
+   - Proactive disclosure to Gitea team before public release
+   - Faster vulnerability patching
+   - Example: At FOSDEM 2025, demonstrated Forgejo Runner fixed all security issues while Gitea Runner remains vulnerable
+
+2. **Development Activity (2024-2025):**
+   - 232 contributors vs Gitea's 153
+   - 3,039 commits vs Gitea's 1,228 (last 12 months)
+   - 2.5x more active development
+   - More frequent releases
+
+3. **Governance:**
+   - Community-governed non-profit
+   - No corporate control
+   - Free/libre software commitment
+   - Developed using Forgejo (dogfooding)
+
+4. **Features (v10.0, Jan 2025):**
+   - Revamped repository dialog
+   - Modify Git notes via API/UI
+   - Markdown table creation button
+   - Consolidated issues/PRs view
+   - Improved TOTP security (keying module)
+
+**Why We Didn't Choose Forgejo:**
+
+1. **No CapRover one-click app** (only feature request from Dec 2023)
+2. Manual Docker Compose setup required (15-30 minutes vs 5 minutes)
+3. Smaller user base (less community support)
+4. Harder fork = no easy migration path from Gitea after v1.22
+5. Overkill for personal knowledge repository hosting
+
+**Security Concerns with Gitea:**
+
+- Advanced security notices only for paying customers
+- Feb 2024: Published vulnerability fix embedded in large refactor, breaking embargo
+- Prioritized SOC2 audit (for SaaS business) over critical community releases
+- "Repeatedly leaves admins exposed to known vulnerabilities for extended periods"
+
+**When to Reconsider Forgejo:**
+
+- If hosting sensitive/production code
+- If security transparency is critical
+- If supporting FOSS governance matters to you
+- If you don't mind manual Docker setup
+
+**Manual Forgejo Deployment on CapRover:**
+
+```yaml
+# Custom CapRover app definition
+services:
+  forgejo:
+    image: codeberg.org/forgejo/forgejo:10
+    restart: always
+    volumes:
+      - forgejo-data:/data
+    ports:
+      - "3000:3000"
+    environment:
+      - USER_UID=1000
+      - USER_GID=1000
+      - FORGEJO__database__DB_TYPE=sqlite3
+volumes:
+  forgejo-data:
+```
+
+**Migration Path (if needed later):**
+- Gitea v1.22 or below can migrate to Forgejo
+- After Gitea v1.23, migration no longer supported
+- CapRover Gitea is on v1.21.1, so migration possible
+
+**Resources:**
+- [Forgejo vs Gitea Comparison](https://forgejo.org/compare-to-gitea/)
+- [Forgejo Security Practices](https://forgejo.org/faq/)
+- [Development Activity Analysis](https://honeypot.net/2025/05/14/gitea-vs-forgejo-development-activity.html)
+
+---
+
+## Container Management: Alternatives to CapRover
+
+**Decision:** Chose **CapRover** ✅
+**Rationale:** Best PaaS experience, one-click apps, built-in reverse proxy + SSL
+
+### Alternative 1: Portainer CE
+
+**What it is:** Full-featured Docker/Kubernetes management GUI
+
+**Pros:**
+- Most mature container management tool
+- Excellent documentation and large community
+- Full granular control over Docker
+- Multi-environment support
+- Good mobile interface
+- App templates included
+
+**Cons:**
+- Need separate reverse proxy (Traefik/Nginx Proxy Manager)
+- Manual SSL configuration for each app
+- More complex setup for each service
+- Community edition has limitations vs Business edition
+- Not a PaaS - focuses on container management, not app deployment
+
+**Best for:** Deep Docker infrastructure control, learning Docker internals
+
+**Why we didn't choose it:**
+- User wanted "TrueNAS-like app store experience"
+- More manual work per app deployment
+- No built-in reverse proxy or SSL automation
+
+---
+
+### Alternative 2: Dockge
+
+**What it is:** Lightweight Docker Compose stack manager with modern UI
+
+**Pros:**
+- Modern, fast, clean interface
+- Built specifically for docker-compose stacks
+- Direct compose.yaml editing with syntax highlighting
+- Real-time container logs
+- Interactive terminal
+- Very lightweight (~100MB RAM)
+
+**Cons:**
+- Newer/less battle-tested
+- Need separate reverse proxy
+- No app marketplace or templates
+- Focused on stacks, less granular container control
+- Smaller community
+
+**Best for:** Docker Compose power users who want modern UX
+
+**Why we didn't choose it:**
+- No one-click app marketplace
+- Still requires manual configuration for each service
+- Not a full PaaS solution
+
+---
+
+### Alternative 3: Coolify
+
+**What it is:** Modern self-hosted PaaS (Heroku/Vercel alternative)
+
+**Pros:**
+- Most similar to Vercel/Netlify experience
+- Deploy directly from Git repos
+- Built-in database management
+- Automatic SSL, backups, monitoring
+- Modern UI and active development
+- Growing community
+
+**Cons:**
+- Heavier resource usage (~500MB+ for Coolify itself)
+- More complex initial setup
+- More opinionated (less flexibility)
+- Newer than CapRover (less mature)
+
+**Best for:** Modern PaaS experience with Git-based deployments
+
+**Why we didn't choose it:**
+- Higher resource overhead
+- CapRover is lighter and more established
+- CapRover has larger one-click app marketplace
+
+---
+
+### Alternative 4: Traditional Stack (Portainer + Nginx Proxy Manager)
+
+**What it is:** Combine Portainer for container management with NPM for reverse proxy
+
+**Pros:**
+- Best of both worlds
+- Beautiful GUI for proxy management (NPM)
+- Full container control (Portainer)
+- Clean separation of concerns
+- Easy SSL certificate management in NPM
+
+**Cons:**
+- Two separate tools to learn and manage
+- More initial setup complexity
+- Still no one-click app deployment
+- Manual configuration for each service
+
+**Best for:** Those who want clean architecture with dedicated proxy GUI
+
+**Why we didn't choose it:**
+- More complexity than needed
+- No app marketplace
+- CapRover combines both in one tool
+
+---
+
+### Alternative 5: Yacht
+
+**What it is:** Template-focused Docker management with modern UI
+
+**Pros:**
+- Beautiful, modern interface
+- Strong template system for one-click deployments
+- Good for deploying common apps quickly
+- Active development
+
+**Cons:**
+- Less mature than Portainer or CapRover
+- Smaller ecosystem and community
+- Need separate reverse proxy
+- Limited compared to CapRover's marketplace
+
+**Best for:** Simple deployments with nice UI
+
+**Why we didn't choose it:**
+- CapRover has more features and larger app catalog
+- Yacht still needs separate proxy setup
+
+---
+
+## Container Runtime: Docker vs Podman
+
+**Decision:** Chose **Docker** ✅
+**Rationale:** Required by CapRover (Docker Swarm dependency)
+
+### Podman Analysis
+
+**What is Podman:**
+- Daemonless, rootless container engine
+- Drop-in replacement for Docker
+- Better security model (rootless by default)
+- Kubernetes-native (generates K8s YAML from pods)
+
+**Advantages of Podman:**
+- **Rootless by default** - containers run as non-privileged users
+- **No daemon** - no dockerd background process (reduced attack surface)
+- **Kubernetes-native** - easier path to K8s if needed
+- **Oracle Linux native** - officially supported on Oracle's OS
+- **Better security** - no root daemon, container breakout harder
+
+**Why NOT Podman:**
+- ❌ **CapRover incompatible** - CapRover requires Docker Swarm
+- ❌ **Podman explicitly won't implement Swarm** - architectural decision
+- ❌ **Less GUI tooling** - Portainer has limited Podman support
+- ❌ **Smaller ecosystem** - fewer tutorials and solutions
+- ❌ **Docker Compose compatibility** - improved but not 100%
+
+**CapRover + Podman = Impossible:**
+From CapRover GitHub discussions:
+> "CapRover is built with Docker Swarm, and Podman has docker-compose capability now, but it seems explicitly unwilling to implement swarm capabilities."
+
+**When to Use Podman:**
+- CLI-only workflow (no GUI needed)
+- Maximum security is paramount (defense/aerospace)
+- Running rootless containers is hard requirement
+- Deploying to Kubernetes eventually (Podman → K8s YAML)
+- Oracle Linux and want native tooling
+
+**Rootless Docker Alternative:**
+If you want rootless security with Docker:
+- Docker has rootless mode (not default, but available)
+- Run: `dockerd-rootless-setuptool.sh install`
+- Not as mature as Podman's implementation
+- Some features limited (like Swarm)
+
+**Verdict:** Docker is required for CapRover. If you want better security, consider Docker's rootless mode after setup, but be aware of limitations.
+
+---
+
+## Reverse Proxy: Alternatives to CapRover's Built-in Nginx
+
+**Decision:** Use **CapRover's built-in proxy** ✅
+**Rationale:** Automatic, integrated with app deployments, no separate setup
+
+### Alternative 1: Traefik
+
+**What it is:** Modern, cloud-native reverse proxy and load balancer
+
+**Pros:**
+- Automatic service discovery via Docker labels
+- Built-in Let's Encrypt support (automatic SSL)
+- Modern architecture, designed for dynamic containers
+- Great for microservices
+- Dashboard for monitoring
+
+**Cons:**
+- Steeper learning curve
+- Configuration via Docker labels can be verbose
+- Requires manual setup and configuration
+- Need to manage separately from apps
+
+**Example configuration:**
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.app.rule=Host(`app.yourdomain.com`)"
+  - "traefik.http.routers.app.entrypoints=websecure"
+  - "traefik.http.routers.app.tls.certresolver=letsencrypt"
+```
+
+**Best for:** Dynamic container environments, microservices, learning modern proxy tech
+
+**Why we didn't choose it:** CapRover already provides this functionality automatically
+
+---
+
+### Alternative 2: Caddy
+
+**What it is:** Web server with automatic HTTPS
+
+**Pros:**
+- **Zero-config HTTPS** - automatically gets Let's Encrypt certificates
+- Simple Caddyfile syntax (easier than Nginx)
+- Built-in reverse proxy
+- Great for simple setups
+- Modern and actively developed
+
+**Cons:**
+- Less dynamic than Traefik (more manual config per service)
+- Need to restart/reload for config changes
+- Less automation than CapRover's approach
+
+**Example Caddyfile:**
+```
+app.yourdomain.com {
+    reverse_proxy localhost:3000
+}
+```
+
+**Best for:** Simple setups, users who want easy HTTPS without complexity
+
+**Why we didn't choose it:** Still manual configuration, CapRover does this automatically
+
+---
+
+### Alternative 3: Nginx Proxy Manager
+
+**What it is:** Nginx with beautiful GUI for managing proxies and SSL
+
+**Pros:**
+- **Beautiful web GUI** - easiest to use visually
+- Point-and-click SSL certificate management
+- Great for beginners
+- Visual workflow for adding services
+- Nice dashboard
+
+**Cons:**
+- Another container to deploy and manage
+- Less automation than Traefik or CapRover
+- Manual configuration for each service (though via GUI)
+- Separate tool to learn
+
+**Best for:** Users who prefer GUI over config files, clean architecture
+
+**Why we didn't choose it:** CapRover already does this, adding NPM would be redundant
+
+---
+
+## Domain Strategy: Alternatives to Cloudflare
+
+**Decision:** Use **existing Cloudflare domain** ✅
+**Rationale:** Already owned, free DNS, reliable
+
+### Alternative 1: DuckDNS
+
+**What it is:** Free dynamic DNS service
+
+**Pros:**
+- Completely free (subdomain + DNS)
+- Simple setup
+- Good for testing/personal projects
+- No account needed (just a token)
+
+**Cons:**
+- Shared domain (yourname.duckdns.org)
+- Less professional
+- Limited to single subdomain or wildcard
+
+**Setup:**
+```
+yourname.duckdns.org → Your Oracle IP
+*.yourname.duckdns.org → Your Oracle IP
+```
+
+**Best for:** Testing, don't want to buy domain, quick setup
+
+**Why we didn't choose it:** User already has Cloudflare domain
+
+---
+
+### Alternative 2: Tailscale (Private Network)
+
+**What it is:** Zero-config VPN / mesh network
+
+**Pros:**
+- **Most secure** - no public exposure at all
+- Access services via private Tailscale network only
+- Free for personal use (up to 100 devices)
+- Works on iPad easily
+- No need for public SSL certs (can use Tailscale HTTPS)
+
+**Cons:**
+- Services only accessible via Tailscale (not public internet)
+- Need Tailscale installed on all devices
+- More complex for sharing with others
+- Not traditional "cloud hosting"
+
+**Setup:**
+```
+# Install Tailscale on Oracle VM
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+
+# Access services via Tailscale IPs
+http://100.x.x.x:3000 (CapRover)
+```
+
+**Best for:** Maximum security, private development, accessing from specific devices only
+
+**Why we didn't choose it:** User wants public access from anywhere (not just Tailscale network)
+
+---
+
+## Alternative Architectures
+
+### Multi-VM Architecture
+
+**What it is:** Split services across multiple ARM VMs (Oracle Free Tier allows up to 4 ARM cores total, divisible)
+
+**Example:**
+```
+VM1 (1 core, 6GB RAM):
+  - CapRover
+  - Nginx Proxy Manager
+  - Monitoring
+
+VM2 (3 cores, 18GB RAM):
+  - Gitea
+  - code-server
+  - Application containers
+```
+
+**Pros:**
+- Isolation between management and apps
+- Can rebuild one VM without affecting the other
+- Better resource allocation
+- Failure isolation
+
+**Cons:**
+- More complex networking setup
+- Two VMs to manage and secure
+- Network latency between VMs
+- More complex backup strategy
+- Overkill for personal use
+
+**Why we didn't choose it:** Single VM is simpler and sufficient for personal use case
+
+---
+
+### Kubernetes (K3s) on Oracle Cloud
+
+**What it is:** Lightweight Kubernetes distribution
+
+**Pros:**
+- Industry-standard orchestration
+- Scalable architecture
+- Great learning experience
+- Better for microservices
+
+**Cons:**
+- Massive overkill for this use case
+- Much more complex to set up and manage
+- Higher resource overhead
+- Steeper learning curve
+- No "one-click apps" like CapRover
+
+**Why we didn't choose it:** Far too complex for personal Git + code-server setup
+
+---
+
+## Summary: Why Our Chosen Stack Wins
+
+| Requirement | Our Choice | Why It Wins |
+|-------------|-----------|-------------|
+| **Git Server** | Gitea | CapRover one-click, 5 min setup vs 30 min manual |
+| **Code Editor** | code-server | Proven iPad PWA support, Claude Code extension works |
+| **Container Platform** | CapRover | One-click apps, built-in proxy+SSL, TrueNAS-like UX |
+| **Container Runtime** | Docker | Required by CapRover (Swarm dependency) |
+| **Reverse Proxy** | CapRover's Nginx | Automatic, zero config, integrated |
+| **SSL** | Let's Encrypt (via CapRover) | Automatic, free, renewal handled |
+| **Domain** | Existing Cloudflare | Already owned, free DNS |
+
+**Result:** Complete iPad dev environment in ~3-4 hours vs days/weeks with alternatives
+
+---
+
+**This document is for reference only. See [IMPLEMENTATION_PLAN.md](../IMPLEMENTATION_PLAN.md) for what we're actually building.**
--- a/Cloud/archive/QUICK_COMPARISON.md
+++ b/Cloud/archive/QUICK_COMPARISON.md
@@ -0,0 +1,143 @@
+# Quick Comparison Reference
+
+Quick reference for alternatives we researched. See [ALTERNATIVES_CONSIDERED.md](./ALTERNATIVES_CONSIDERED.md) for detailed analysis.
+
+---
+
+## Git Server: Gitea vs Forgejo
+
+| Factor | Gitea ✅ | Forgejo |
+|--------|---------|---------|
+| **CapRover Support** | ✅ One-click app | ❌ Manual setup required |
+| **Setup Time** | ⚡ 5 minutes | ⏱️ 15-30 minutes |
+| **Security Practices** | ⚠️ Adequate (corporate) | ✅ Excellent (community) |
+| **Development Activity** | 153 contributors, 1.2K commits | 232 contributors, 3K commits |
+| **Governance** | Corporate (Gitea Limited) | Non-profit (Codeberg e.V.) |
+| **Community Size** | Larger | Smaller |
+| **Version** | 1.21.1 | 10.0 (Jan 2025) |
+| **For Personal Use** | ✅ Perfect | ⚠️ Overkill |
+
+**Winner for our use case:** Gitea (easier setup via CapRover)
+
+**When to reconsider Forgejo:**
+- Hosting sensitive code
+- Security transparency matters
+- Don't mind manual Docker setup
+
+---
+
+## Container Management Platform
+
+| Feature | CapRover ✅ | Portainer | Dockge | Coolify |
+|---------|------------|-----------|---------|---------|
+| **One-click apps** | ✅ 200+ | ⚠️ Limited | ❌ None | ✅ Some |
+| **Built-in reverse proxy** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+| **Automatic SSL** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+| **Git deployments** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+| **Granular control** | ⚠️ Limited | ✅ Full | ✅ Good | ⚠️ Limited |
+| **Learning curve** | 🟢 Easy | 🟡 Medium | 🟢 Easy | 🟡 Medium |
+| **Resource usage** | 🟢 ~300MB | 🟡 ~100MB | 🟢 ~100MB | 🔴 ~500MB+ |
+| **Maturity** | 🟢 Stable | 🟢 Very stable | 🟡 Newer | 🟡 Active dev |
+| **TrueNAS-like experience** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+
+**Winner:** CapRover (best for "app store" experience)
+
+---
+
+## Container Runtime: Docker vs Podman
+
+| Factor | Docker ✅ | Podman |
+|--------|----------|--------|
+| **CapRover Compatible** | ✅ Yes (required) | ❌ No (missing Swarm) |
+| **Security Model** | Root daemon (can use rootless mode) | Rootless by default |
+| **GUI Support** | ✅ Excellent (CapRover, Portainer, etc.) | ⚠️ Limited |
+| **Ecosystem** | 🟢 Massive | 🟡 Growing |
+| **For This Project** | ✅ Required | ❌ Won't work |
+
+**Winner:** Docker (CapRover requires Docker Swarm)
+
+**Note:** Podman explicitly won't implement Swarm. CapRover = Docker only.
+
+---
+
+## Reverse Proxy
+
+| Feature | CapRover Built-in ✅ | Traefik | Caddy | Nginx Proxy Manager |
+|---------|---------------------|---------|-------|-------------------|
+| **Integration** | ✅ Built-in | ❌ Separate | ❌ Separate | ❌ Separate |
+| **Auto SSL** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (via GUI) |
+| **Auto Config** | ✅ Per app deploy | ⚠️ Via labels | ⚠️ Manual | ⚠️ GUI but manual |
+| **Learning Curve** | 🟢 None (automatic) | 🔴 Steep | 🟡 Medium | 🟢 Easy (GUI) |
+| **Setup Time** | ⚡ 0 min (included) | ⏱️ 30+ min | ⏱️ 15+ min | ⏱️ 20+ min |
+
+**Winner:** CapRover's built-in proxy (zero setup, automatic)
+
+---
+
+## Domain Strategy
+
+| Option | Cloudflare ✅ | DuckDNS | Tailscale |
+|--------|--------------|---------|-----------|
+| **Cost** | Free (user already has) | Free | Free (personal) |
+| **Domain Type** | Custom domain | yourname.duckdns.org | Private network IPs |
+| **Professional** | ✅ Yes | ⚠️ Subdomain only | ❌ Not public |
+| **Public Access** | ✅ Yes | ✅ Yes | ❌ VPN only |
+| **Setup** | Simple DNS records | Very simple | Install on all devices |
+
+**Winner:** Cloudflare (user already has domain)
+
+---
+
+## Architecture Patterns
+
+| Pattern | Single VM ✅ | Multi-VM | Kubernetes (K3s) |
+|---------|-------------|----------|-----------------|
+| **Complexity** | 🟢 Simple | 🟡 Medium | 🔴 High |
+| **Setup Time** | ⚡ 3-4 hours | ⏱️ 6-8 hours | ⏱️ Days |
+| **Maintenance** | 🟢 Easy | 🟡 Medium | 🔴 Complex |
+| **Resource Overhead** | 🟢 Low (~1GB) | 🟡 Medium | 🔴 High (>2GB) |
+| **For Personal Use** | ✅ Perfect | ⚠️ Overkill | ❌ Way overkill |
+
+**Winner:** Single ARM VM (simple, sufficient, efficient)
+
+---
+
+## Final Stack Summary
+
+Our chosen stack:
+
+```
+Infrastructure:  Oracle Cloud Free Tier (ARM VM: 4 cores, 24GB RAM)
+OS:             Ubuntu 22.04 LTS ARM64
+Runtime:        Docker Engine
+Platform:       CapRover (PaaS with one-click apps)
+Git Server:     Gitea (one-click deploy)
+Code Editor:    code-server (one-click deploy)
+AI Assistant:   Claude Code (VS Code extension)
+Reverse Proxy:  CapRover's built-in Nginx
+SSL:            Let's Encrypt (automatic via CapRover)
+DNS:            Cloudflare (existing domain)
+```
+
+**Total setup time:** ~3-4 hours
+**Monthly cost:** $0
+**Resource usage:** ~1GB RAM, ~10GB storage (23GB RAM and 190GB storage remaining)
+
+---
+
+## Why This Stack Wins
+
+1. **Fastest time to value:** One-click deployments vs manual Docker setup
+2. **Lowest cognitive load:** CapRover handles proxy, SSL, routing automatically
+3. **Best UX:** TrueNAS-like app store experience (what user wanted)
+4. **iPad optimized:** code-server has proven PWA support
+5. **Zero cost:** Stays within Oracle Free Tier
+6. **Adequate security:** Good enough for personal knowledge repository
+7. **Easy maintenance:** CapRover handles updates, SSL renewals
+8. **Room to grow:** 23GB RAM for additional apps via one-click marketplace
+
+**Result:** iPad development environment with Claude Code in ~3-4 hours instead of days/weeks with alternatives.
+
+---
+
+See [ALTERNATIVES_CONSIDERED.md](./ALTERNATIVES_CONSIDERED.md) for detailed analysis of each alternative.