Init
This commit is contained in:
544
Personal/Projects/Servers/Oracle Cloud/IMPLEMENTATION_PLAN.md
Normal file
544
Personal/Projects/Servers/Oracle Cloud/IMPLEMENTATION_PLAN.md
Normal file
@@ -0,0 +1,544 @@
|
||||
# Oracle Cloud iPad Development Environment - Implementation Plan
|
||||
|
||||
**Last Updated:** 2025-10-25
|
||||
**Status:** Ready to Build
|
||||
|
||||
## What We're Building
|
||||
|
||||
A cloud-based development environment accessible from iPad, hosted on Oracle Cloud Free Tier:
|
||||
|
||||
- **Git Server** (Gitea) - Host your knowledge repository with web UI
|
||||
- **VS Code Server** (code-server) - Full VS Code in browser with Claude Code extension
|
||||
- **Container Management** (CapRover) - One-click deployment platform for additional apps
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Oracle Cloud Free Tier - ARM VM (4 cores, 24GB RAM)
|
||||
├── Ubuntu 22.04 LTS (ARM64)
|
||||
├── Docker Engine
|
||||
└── CapRover PaaS Platform
|
||||
├── captain.yourdomain.com → CapRover dashboard
|
||||
├── git.yourdomain.com → Gitea (Git server)
|
||||
└── code.yourdomain.com → code-server (VS Code + Claude Code)
|
||||
```
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology | Purpose | Resources |
|
||||
|-----------|-----------|---------|-----------|
|
||||
| **Infrastructure** | Oracle Cloud (ARM VM) | Free hosting | 4 cores, 24GB RAM, 200GB storage |
|
||||
| **OS** | Ubuntu 22.04 LTS ARM64 | Server operating system | ~2GB |
|
||||
| **Container Runtime** | Docker Engine | Run containers | Required by CapRover |
|
||||
| **Platform** | CapRover | PaaS + app deployment | ~300MB RAM |
|
||||
| **Git Server** | Gitea v1.21.1 | Self-hosted GitHub alternative | ~200MB RAM |
|
||||
| **Code Editor** | code-server | VS Code in browser | ~500MB RAM |
|
||||
| **AI Assistant** | Claude Code extension | AI-powered coding | VS Code extension |
|
||||
| **DNS** | Cloudflare | Domain management | Existing domain |
|
||||
| **SSL** | Let's Encrypt (via CapRover) | Automatic HTTPS | Free |
|
||||
|
||||
**Total base resource usage:** ~1GB RAM, ~10GB storage
|
||||
**Remaining available:** ~23GB RAM, ~190GB storage
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Oracle Cloud Setup (1-2 hours)
|
||||
|
||||
**Objective:** Provision and secure the ARM VM
|
||||
|
||||
- [ ] Create Oracle Cloud account (if needed)
|
||||
- [ ] Provision ARM VM instance:
|
||||
- Shape: VM.Standard.A1.Flex
|
||||
- OCPU: 4
|
||||
- RAM: 24GB
|
||||
- Boot volume: 50GB (default)
|
||||
- Image: Ubuntu 22.04 LTS (ARM64)
|
||||
- Region: Choose based on availability
|
||||
- [ ] Configure Oracle Security Lists (firewall):
|
||||
- Allow inbound: 22 (SSH), 80 (HTTP), 443 (HTTPS), 3000 (CapRover initial setup)
|
||||
- Allow inbound: 996, 7946, 4789, 2377 (CapRover/Docker Swarm)
|
||||
- [ ] Note public IP address
|
||||
- [ ] Set up SSH key authentication
|
||||
- [ ] SSH into VM and verify access
|
||||
|
||||
**Deliverable:** Accessible Ubuntu VM with public IP
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Server Foundation (30 minutes)
|
||||
|
||||
**Objective:** Install Docker and prepare for CapRover
|
||||
|
||||
```bash
|
||||
# Update system
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Install Docker Engine
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# Verify Docker installation
|
||||
docker --version
|
||||
docker run hello-world
|
||||
|
||||
# Configure firewall (UFW)
|
||||
sudo ufw allow 22/tcp
|
||||
sudo ufw allow 80/tcp
|
||||
sudo ufw allow 443/tcp
|
||||
sudo ufw allow 3000/tcp
|
||||
sudo ufw allow 996/tcp
|
||||
sudo ufw allow 7946/tcp
|
||||
sudo ufw allow 4789/tcp
|
||||
sudo ufw allow 2377/tcp
|
||||
sudo ufw enable
|
||||
|
||||
# Enable automatic security updates
|
||||
sudo apt install unattended-upgrades -y
|
||||
sudo dpkg-reconfigure -plow unattended-upgrades
|
||||
```
|
||||
|
||||
**Deliverable:** VM with Docker installed and firewall configured
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: DNS Configuration (10 minutes)
|
||||
|
||||
**Objective:** Point domain to Oracle VM
|
||||
|
||||
In Cloudflare DNS:
|
||||
|
||||
1. Add A record for wildcard subdomain:
|
||||
- Type: `A`
|
||||
- Name: `*` (wildcard) or `*.oracle` (if you want subdomain)
|
||||
- Content: `YOUR_ORACLE_VM_PUBLIC_IP`
|
||||
- Proxy status: DNS only (orange cloud OFF)
|
||||
- TTL: Auto
|
||||
|
||||
2. Verify DNS propagation:
|
||||
```bash
|
||||
# From your local machine
|
||||
nslookup captain.yourdomain.com
|
||||
nslookup git.yourdomain.com
|
||||
nslookup code.yourdomain.com
|
||||
```
|
||||
|
||||
**Deliverable:** DNS records pointing to Oracle VM
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: CapRover Installation (15 minutes)
|
||||
|
||||
**Objective:** Install and configure CapRover PaaS platform
|
||||
|
||||
```bash
|
||||
# Install CapRover
|
||||
docker run -p 80:80 -p 443:443 -p 3000:3000 \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-v /captain:/captain \
|
||||
-e ACCEPTED_TERMS=true \
|
||||
caprover/caprover
|
||||
|
||||
# Wait ~2 minutes for CapRover to initialize
|
||||
|
||||
# Access CapRover setup wizard
|
||||
# Open browser: http://YOUR_VM_IP:3000
|
||||
```
|
||||
|
||||
**CapRover Initial Setup Wizard:**
|
||||
|
||||
1. **Password:** Set a strong password (save it!)
|
||||
2. **Root Domain:** `yourdomain.com` (or `oracle.yourdomain.com`)
|
||||
3. **Email:** Your email for Let's Encrypt SSL
|
||||
4. **Enable HTTPS:** ✅ Yes
|
||||
5. **Force HTTPS:** ✅ Yes
|
||||
|
||||
**Post-setup:**
|
||||
- Access dashboard at: `https://captain.yourdomain.com`
|
||||
- Login with the password you set
|
||||
- Verify SSL certificate is working
|
||||
|
||||
**Deliverable:** Running CapRover platform with HTTPS
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Deploy Gitea (10 minutes)
|
||||
|
||||
**Objective:** Deploy Git server via CapRover one-click app
|
||||
|
||||
**In CapRover Dashboard:**
|
||||
|
||||
1. Navigate to **Apps** → **One-Click Apps/Databases**
|
||||
2. Search for **Gitea**
|
||||
3. Configure:
|
||||
- **App Name:** `git` (becomes git.yourdomain.com)
|
||||
- **Gitea Version:** `1.21.1` (default, or latest)
|
||||
- **MySQL Version:** `8.0.32` (default)
|
||||
- **MySQL Root Password:** Auto-generated (or custom)
|
||||
4. Click **Deploy**
|
||||
5. Wait ~2 minutes for deployment
|
||||
|
||||
**Initial Gitea Setup:**
|
||||
|
||||
1. Open `https://git.yourdomain.com`
|
||||
2. Complete Gitea installation wizard:
|
||||
- **Database Type:** MySQL (pre-configured by CapRover)
|
||||
- **Database Host:** Auto-configured
|
||||
- **Site Title:** "Your Name's Git Server" or similar
|
||||
- **Server Domain:** `git.yourdomain.com`
|
||||
- **SSH Port:** 22 (or custom if needed)
|
||||
- **Base URL:** `https://git.yourdomain.com/`
|
||||
- **Admin Account:**
|
||||
- Username: Your username
|
||||
- Password: Strong password
|
||||
- Email: Your email
|
||||
3. Click **Install Gitea**
|
||||
4. Login with admin account
|
||||
|
||||
**Create Your Knowledge Repository:**
|
||||
|
||||
1. Click **+** → **New Repository**
|
||||
2. Repository name: `knowledge-base` (or your preferred name)
|
||||
3. Make it private
|
||||
4. Initialize with README
|
||||
5. Create repository
|
||||
|
||||
**Deliverable:** Working Gitea instance with your repository
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Deploy code-server (10 minutes)
|
||||
|
||||
**Objective:** Deploy VS Code Server via CapRover one-click app
|
||||
|
||||
**In CapRover Dashboard:**
|
||||
|
||||
1. Navigate to **Apps** → **One-Click Apps/Databases**
|
||||
2. Search for **code-server**
|
||||
3. Configure:
|
||||
- **App Name:** `code` (becomes code.yourdomain.com)
|
||||
- **Password:** Set a strong password for code-server access
|
||||
- **Sudo Password:** (Optional) For terminal sudo access
|
||||
4. Click **Deploy**
|
||||
5. Wait ~2 minutes for deployment
|
||||
|
||||
**Access code-server:**
|
||||
|
||||
1. Open `https://code.yourdomain.com`
|
||||
2. Enter the password you set
|
||||
3. You should see VS Code interface in browser!
|
||||
|
||||
**Deliverable:** Working code-server accessible via browser
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Configure Development Environment (30 minutes)
|
||||
|
||||
**Objective:** Set up code-server with Claude Code and clone your repo
|
||||
|
||||
**7.1 Configure Git in code-server:**
|
||||
|
||||
Open terminal in code-server (`` Ctrl+` `` or Terminal menu):
|
||||
|
||||
```bash
|
||||
# Set up git identity
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your@email.com"
|
||||
|
||||
# Generate SSH key for Gitea
|
||||
ssh-keygen -t ed25519 -C "your@email.com"
|
||||
# Press Enter for default location, set passphrase (optional)
|
||||
|
||||
# Copy public key
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
**Add SSH key to Gitea:**
|
||||
1. Copy the public key output
|
||||
2. Go to Gitea (`git.yourdomain.com`)
|
||||
3. Click your profile → **Settings** → **SSH / GPG Keys**
|
||||
4. Click **Add Key**
|
||||
5. Paste the public key
|
||||
6. Give it a title (e.g., "code-server")
|
||||
7. Click **Add Key**
|
||||
|
||||
**7.2 Clone your repository:**
|
||||
|
||||
In code-server terminal:
|
||||
|
||||
```bash
|
||||
# Clone your knowledge repo
|
||||
cd ~
|
||||
git clone git@git.yourdomain.com:YOUR_USERNAME/knowledge-base.git
|
||||
|
||||
# Open the repository in code-server
|
||||
code knowledge-base
|
||||
```
|
||||
|
||||
**7.3 Install Claude Code extension:**
|
||||
|
||||
1. Click **Extensions** icon (left sidebar) or `Ctrl+Shift+X`
|
||||
2. Search: "Claude Code" or "Anthropic"
|
||||
3. Click **Install** on the Claude Code extension
|
||||
4. After installation, you'll be prompted to authenticate
|
||||
5. Enter your Anthropic API key or login to Claude Pro
|
||||
|
||||
**Verify Claude Code is working:**
|
||||
- Open a file in your repository
|
||||
- Try asking Claude a question about your code
|
||||
- Test code completion features
|
||||
|
||||
**7.4 Optional: Install additional extensions:**
|
||||
- Markdown Preview Enhanced
|
||||
- GitLens
|
||||
- Any other extensions you use
|
||||
|
||||
**Deliverable:** Fully configured development environment with Claude Code
|
||||
|
||||
---
|
||||
|
||||
### Phase 8: iPad Setup (5 minutes)
|
||||
|
||||
**Objective:** Install code-server as PWA on iPad for native-like experience
|
||||
|
||||
**On your iPad:**
|
||||
|
||||
1. Open Safari
|
||||
2. Navigate to `https://code.yourdomain.com`
|
||||
3. Login with your password
|
||||
4. Tap the **Share** button (square with arrow)
|
||||
5. Scroll down and tap **Add to Home Screen**
|
||||
6. Name it "Cloud Code" or "Code Server"
|
||||
7. Tap **Add**
|
||||
8. Find the app icon on your home screen
|
||||
9. Tap to open (full-screen experience!)
|
||||
|
||||
**Benefits of PWA mode:**
|
||||
- No Safari UI bars (more screen space)
|
||||
- Runs like a native app
|
||||
- Better keyboard integration
|
||||
- Quick access from home screen/dock
|
||||
|
||||
**Deliverable:** Code-server installed as PWA on iPad
|
||||
|
||||
---
|
||||
|
||||
### Phase 9: Backup & Security (1 hour)
|
||||
|
||||
**Objective:** Secure the environment and set up backups
|
||||
|
||||
**9.1 SSH Hardening:**
|
||||
|
||||
```bash
|
||||
# Change SSH port (optional but recommended)
|
||||
sudo nano /etc/ssh/sshd_config
|
||||
# Change: Port 22 → Port 2222
|
||||
# Set: PasswordAuthentication no
|
||||
# Set: PermitRootLogin no
|
||||
|
||||
sudo systemctl restart sshd
|
||||
|
||||
# Update Oracle Security Lists to allow port 2222 instead of 22
|
||||
# Update UFW: sudo ufw allow 2222/tcp && sudo ufw delete allow 22/tcp
|
||||
```
|
||||
|
||||
**9.2 Configure Backups:**
|
||||
|
||||
Create backup script:
|
||||
|
||||
```bash
|
||||
# Create backup directory
|
||||
mkdir -p /home/ubuntu/backups
|
||||
|
||||
# Create backup script
|
||||
cat > /home/ubuntu/backup.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
BACKUP_DIR="/home/ubuntu/backups"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
# Backup Gitea data
|
||||
docker exec srv-captain--git tar czf /tmp/gitea-backup-${DATE}.tar.gz /data
|
||||
docker cp srv-captain--git:/tmp/gitea-backup-${DATE}.tar.gz ${BACKUP_DIR}/
|
||||
|
||||
# Backup code-server data
|
||||
docker exec srv-captain--code tar czf /tmp/code-backup-${DATE}.tar.gz /home/coder
|
||||
docker cp srv-captain--code:/tmp/code-backup-${DATE}.tar.gz ${BACKUP_DIR}/
|
||||
|
||||
# Keep only last 7 days of backups
|
||||
find ${BACKUP_DIR} -name "*.tar.gz" -mtime +7 -delete
|
||||
|
||||
echo "Backup completed: ${DATE}"
|
||||
EOF
|
||||
|
||||
chmod +x /home/ubuntu/backup.sh
|
||||
|
||||
# Set up cron job (daily at 2 AM)
|
||||
(crontab -l 2>/dev/null; echo "0 2 * * * /home/ubuntu/backup.sh >> /home/ubuntu/backup.log 2>&1") | crontab -
|
||||
```
|
||||
|
||||
**9.3 Oracle Block Volume Setup (Optional):**
|
||||
|
||||
If you want persistent storage separate from boot volume:
|
||||
|
||||
1. Create 100GB block volume in Oracle Cloud console
|
||||
2. Attach to VM instance
|
||||
3. Format and mount:
|
||||
```bash
|
||||
sudo mkfs.ext4 /dev/sdb
|
||||
sudo mkdir /mnt/data
|
||||
sudo mount /dev/sdb /mnt/data
|
||||
sudo chown ubuntu:ubuntu /mnt/data
|
||||
|
||||
# Add to fstab for persistence
|
||||
echo "/dev/sdb /mnt/data ext4 defaults 0 0" | sudo tee -a /etc/fstab
|
||||
```
|
||||
4. Move Docker volumes to block storage:
|
||||
```bash
|
||||
sudo systemctl stop docker
|
||||
sudo mv /var/lib/docker /mnt/data/docker
|
||||
sudo ln -s /mnt/data/docker /var/lib/docker
|
||||
sudo systemctl start docker
|
||||
```
|
||||
|
||||
**Deliverable:** Secured and backed-up environment
|
||||
|
||||
---
|
||||
|
||||
### Phase 10: Deploy Monitoring (Optional, 15 minutes)
|
||||
|
||||
**Objective:** Monitor your services with Uptime Kuma
|
||||
|
||||
**In CapRover Dashboard:**
|
||||
|
||||
1. **Apps** → **One-Click Apps/Databases**
|
||||
2. Search: **Uptime Kuma**
|
||||
3. Configure:
|
||||
- App Name: `uptime`
|
||||
4. Deploy
|
||||
5. Access: `https://uptime.yourdomain.com`
|
||||
6. Create admin account
|
||||
7. Add monitors for:
|
||||
- Gitea (`https://git.yourdomain.com`)
|
||||
- code-server (`https://code.yourdomain.com`)
|
||||
- CapRover (`https://captain.yourdomain.com`)
|
||||
|
||||
**Deliverable:** Monitoring dashboard for all services
|
||||
|
||||
---
|
||||
|
||||
## Final Verification Checklist
|
||||
|
||||
- [ ] CapRover dashboard accessible at `https://captain.yourdomain.com`
|
||||
- [ ] Gitea accessible at `https://git.yourdomain.com` with your repository
|
||||
- [ ] code-server accessible at `https://code.yourdomain.com`
|
||||
- [ ] code-server has Claude Code extension installed and working
|
||||
- [ ] Repository cloned in code-server
|
||||
- [ ] Can commit and push from code-server to Gitea
|
||||
- [ ] code-server installed as PWA on iPad
|
||||
- [ ] All services have valid SSL certificates
|
||||
- [ ] SSH hardened (port changed, password auth disabled)
|
||||
- [ ] Backups configured and tested
|
||||
- [ ] (Optional) Monitoring set up
|
||||
|
||||
## Workflow: Using Your iPad Dev Environment
|
||||
|
||||
**Daily workflow:**
|
||||
|
||||
1. **On iPad:** Open "Cloud Code" PWA from home screen
|
||||
2. **Edit files:** Make changes to your knowledge base
|
||||
3. **Use Claude Code:** Get AI assistance while coding
|
||||
4. **Commit changes:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Update notes on X"
|
||||
git push
|
||||
```
|
||||
5. **View in Gitea:** Check `https://git.yourdomain.com` to see changes
|
||||
|
||||
**From any device:**
|
||||
- Access code-server: `https://code.yourdomain.com`
|
||||
- Browse repo in web: `https://git.yourdomain.com`
|
||||
- Manage apps: `https://captain.yourdomain.com`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**CapRover not accessible:**
|
||||
- Check Oracle Security Lists (firewall rules)
|
||||
- Check UFW: `sudo ufw status`
|
||||
- Check CapRover status: `docker ps`
|
||||
|
||||
**SSL certificate issues:**
|
||||
- Ensure DNS is propagated: `nslookup captain.yourdomain.com`
|
||||
- Check Cloudflare proxy is OFF (DNS only)
|
||||
- Wait 5-10 minutes for Let's Encrypt
|
||||
|
||||
**code-server can't clone from Gitea:**
|
||||
- Verify SSH key added to Gitea
|
||||
- Test SSH: `ssh -T git@git.yourdomain.com`
|
||||
- Check git config: `git config --list`
|
||||
|
||||
**Claude Code extension not working:**
|
||||
- Verify API key is valid
|
||||
- Check extension logs in code-server
|
||||
- Try reinstalling extension
|
||||
|
||||
## Cost Breakdown
|
||||
|
||||
| Item | Cost |
|
||||
|------|------|
|
||||
| Oracle Cloud ARM VM | $0 (Free Tier) |
|
||||
| Oracle Block Storage (200GB) | $0 (Free Tier) |
|
||||
| Cloudflare DNS | $0 (Free Plan) |
|
||||
| Domain (if you don't have one) | ~$10-15/year |
|
||||
| Let's Encrypt SSL | $0 (Free) |
|
||||
| **Total Monthly Cost** | **$0** |
|
||||
|
||||
## Maintenance
|
||||
|
||||
**Weekly:**
|
||||
- Check backups are running: `ls -lh /home/ubuntu/backups`
|
||||
- Review service health in Uptime Kuma (if installed)
|
||||
|
||||
**Monthly:**
|
||||
- Update Docker containers via CapRover
|
||||
- Review disk space: `df -h`
|
||||
- Test backup restoration
|
||||
|
||||
**As needed:**
|
||||
- Update CapRover: Follow official upgrade guide
|
||||
- Add new apps via CapRover one-click marketplace
|
||||
|
||||
## Next Steps After Setup
|
||||
|
||||
**Additional apps you might want to deploy (all one-click in CapRover):**
|
||||
|
||||
- **Vaultwarden** - Self-hosted password manager
|
||||
- **FreshRSS** - RSS feed reader
|
||||
- **Nextcloud** - File storage and sync
|
||||
- **Bookstack** - Documentation wiki
|
||||
- **Plausible** - Privacy-friendly analytics
|
||||
- **Miniflux** - Minimal RSS reader
|
||||
- **Dokuwiki** - Simple wiki
|
||||
- **Jellyfin** - Media server
|
||||
|
||||
All available via CapRover's one-click apps marketplace!
|
||||
|
||||
## Success Criteria
|
||||
|
||||
You'll know the setup is successful when you can:
|
||||
|
||||
1. ✅ Open code-server on your iPad (as PWA)
|
||||
2. ✅ Clone and edit your knowledge repository
|
||||
3. ✅ Use Claude Code extension to get AI assistance
|
||||
4. ✅ Commit and push changes back to Gitea
|
||||
5. ✅ Access everything via HTTPS from anywhere
|
||||
6. ✅ Deploy new apps with one click in CapRover
|
||||
|
||||
**Estimated total setup time:** 3-4 hours (including wait times)
|
||||
|
||||
---
|
||||
|
||||
**Ready to start building?** Begin with Phase 1!
|
||||
280
Personal/Projects/Servers/Oracle Cloud/README.md
Normal file
280
Personal/Projects/Servers/Oracle Cloud/README.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Oracle Cloud iPad Development Environment
|
||||
|
||||
**Status:** Ready to Build ✅
|
||||
**Last Updated:** 2025-10-25
|
||||
|
||||
A cloud-based development environment accessible from iPad, hosted on Oracle Cloud Free Tier for $0/month.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Links
|
||||
|
||||
- **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** ⭐ Start here! Complete step-by-step build guide
|
||||
- **[archive/ALTERNATIVES_CONSIDERED.md](./archive/ALTERNATIVES_CONSIDERED.md)** - Deep dive into alternatives we researched
|
||||
- **[archive/QUICK_COMPARISON.md](./archive/QUICK_COMPARISON.md)** - Quick reference comparison tables
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What We're Building
|
||||
|
||||
```
|
||||
Your iPad
|
||||
↓
|
||||
git.yourdomain.com (Gitea)
|
||||
- Browse your knowledge repository
|
||||
- Web UI like GitHub
|
||||
- Manage commits and branches
|
||||
|
||||
code.yourdomain.com (VS Code Server)
|
||||
- Full VS Code in browser
|
||||
- Claude Code AI assistant
|
||||
- Edit files and commit to Gitea
|
||||
- Installable as iPad PWA app
|
||||
|
||||
captain.yourdomain.com (CapRover)
|
||||
- Manage all your apps
|
||||
- One-click deploy new services
|
||||
```
|
||||
|
||||
**Monthly cost:** $0 (Oracle Cloud Free Tier)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Tech Stack (Final Decisions)
|
||||
|
||||
| Component | Choice | Why |
|
||||
|-----------|--------|-----|
|
||||
| **Infrastructure** | Oracle Cloud ARM VM (4 cores, 24GB RAM) | Free forever |
|
||||
| **Platform** | CapRover | One-click apps, built-in proxy+SSL |
|
||||
| **Git Server** | Gitea v1.21.1 | CapRover one-click, 5 min setup |
|
||||
| **Code Editor** | code-server | VS Code in browser, iPad PWA support |
|
||||
| **AI Assistant** | Claude Code extension | Integrates with code-server |
|
||||
| **Container Runtime** | Docker Engine | Required by CapRover |
|
||||
| **DNS** | Cloudflare | Your existing domain |
|
||||
| **SSL** | Let's Encrypt (via CapRover) | Automatic, free, renewal handled |
|
||||
|
||||
**Setup time:** ~3-4 hours
|
||||
**Resource usage:** ~1GB RAM (23GB remaining for apps)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
- ✅ **Git Server** - Gitea with GitHub-like web UI
|
||||
- ✅ **VS Code in Browser** - code-server with Claude Code extension
|
||||
- ✅ **iPad PWA** - Install code-server as native-like app on iPad
|
||||
- ✅ **Automatic HTTPS** - Let's Encrypt SSL for all services
|
||||
- ✅ **One-click Apps** - 200+ apps in CapRover marketplace
|
||||
- ✅ **Free Forever** - Oracle Cloud Free Tier ($0/month)
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Oracle Cloud - ARM VM (4 cores, 24GB RAM) │
|
||||
│ Ubuntu 22.04 LTS ARM64 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ CapRover PaaS Platform (~300MB RAM) │
|
||||
│ ├── captain.yourdomain.com │
|
||||
│ │ └── CapRover dashboard │
|
||||
│ │ │
|
||||
│ ├── git.yourdomain.com │
|
||||
│ │ └── Gitea (~200MB RAM) │
|
||||
│ │ └── Your knowledge repository │
|
||||
│ │ │
|
||||
│ ├── code.yourdomain.com │
|
||||
│ │ └── code-server (~500MB RAM) │
|
||||
│ │ ├── Claude Code extension │
|
||||
│ │ ├── VS Code in browser │
|
||||
│ │ └── Clone repos from Gitea │
|
||||
│ │ │
|
||||
│ └── [Additional apps as needed] │
|
||||
│ └── 200+ one-click apps available │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ HTTPS (Let's Encrypt SSL - automatic)
|
||||
│
|
||||
Internet / iPad
|
||||
```
|
||||
|
||||
**Resources:**
|
||||
- Base stack: ~1GB RAM, ~10GB storage
|
||||
- Remaining: ~23GB RAM, ~190GB storage for apps
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
1. **Read the implementation plan:** [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)
|
||||
2. **Follow Phase 1-10** for complete setup
|
||||
3. **Estimated time:** 3-4 hours (including wait times)
|
||||
|
||||
### Quick Phase Overview
|
||||
|
||||
1. **Phase 1:** Oracle Cloud VM setup (1-2 hours)
|
||||
2. **Phase 2:** Install Docker (30 min)
|
||||
3. **Phase 3:** Configure DNS (10 min)
|
||||
4. **Phase 4:** Install CapRover (15 min)
|
||||
5. **Phase 5:** Deploy Gitea (10 min)
|
||||
6. **Phase 6:** Deploy code-server (10 min)
|
||||
7. **Phase 7:** Configure dev environment (30 min)
|
||||
8. **Phase 8:** iPad PWA setup (5 min)
|
||||
9. **Phase 9:** Backup & security (1 hour)
|
||||
10. **Phase 10:** Monitoring (15 min, optional)
|
||||
|
||||
---
|
||||
|
||||
## 💡 Use Case
|
||||
|
||||
**Problem:** Need to edit your knowledge repository from iPad with AI assistance
|
||||
|
||||
**Solution:** Cloud-hosted VS Code with Claude Code, pushing to self-hosted Git server
|
||||
|
||||
**Your Workflow:**
|
||||
1. Open code-server PWA on iPad
|
||||
2. Edit files with full VS Code interface
|
||||
3. Use Claude Code extension for AI assistance
|
||||
4. Commit and push to Gitea
|
||||
5. View changes in Gitea web UI
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Oracle Cloud Free Tier Details
|
||||
|
||||
**Compute (Always Free):**
|
||||
- 4 ARM Ampere A1 cores + 24GB RAM (we use 1 VM with all resources)
|
||||
- Alternative: 2x AMD VM.Standard.E2.1.Micro (1 OCPU + 1GB RAM each) - not recommended
|
||||
|
||||
**Storage (Always Free):**
|
||||
- 200 GB block volume storage
|
||||
- 10 GB object storage (backups)
|
||||
|
||||
**Networking (Always Free):**
|
||||
- 1 public IPv4 per instance
|
||||
- 10 TB outbound data transfer/month
|
||||
- VCN (Virtual Cloud Network) - unlimited
|
||||
|
||||
**Limitations:**
|
||||
- No root volume encryption on Free Tier
|
||||
- Subject to capacity constraints (ARM availability varies by region)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Resource Estimates
|
||||
|
||||
**Base Stack:**
|
||||
- CapRover: ~300MB RAM
|
||||
- Gitea: ~200MB RAM
|
||||
- code-server: ~500MB RAM
|
||||
- **Total: ~1GB RAM**
|
||||
|
||||
**Your Remaining Resources:**
|
||||
- ~23GB RAM for additional apps
|
||||
- ~190GB storage available
|
||||
|
||||
**Can easily run:**
|
||||
- 15-25 lightweight apps, or
|
||||
- 5-10 heavier apps (Nextcloud, Jellyfin, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Additional Apps (Optional)
|
||||
|
||||
All available via CapRover one-click deploy:
|
||||
|
||||
- **Vaultwarden** - Password manager
|
||||
- **FreshRSS** - RSS reader
|
||||
- **Uptime Kuma** - Monitoring
|
||||
- **Nextcloud** - File storage
|
||||
- **Bookstack** - Wiki/docs
|
||||
- **Jellyfin** - Media server
|
||||
- **Plausible** - Analytics
|
||||
- **And 190+ more!**
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Why These Choices?
|
||||
|
||||
See detailed analysis in archive:
|
||||
|
||||
**Gitea vs Forgejo:**
|
||||
- Gitea: CapRover one-click (5 min) ✅
|
||||
- Forgejo: Manual Docker setup (30 min), better security
|
||||
- **Decision:** Gitea for ease, adequate security for personal use
|
||||
- See: [archive/ALTERNATIVES_CONSIDERED.md](./archive/ALTERNATIVES_CONSIDERED.md#git-server-forgejo-vs-gitea)
|
||||
|
||||
**CapRover vs Alternatives:**
|
||||
- CapRover: One-click apps, built-in proxy+SSL ✅
|
||||
- Portainer: More control, manual setup per app
|
||||
- Dockge: Modern but no app marketplace
|
||||
- **Decision:** CapRover for TrueNAS-like experience
|
||||
- See: [archive/QUICK_COMPARISON.md](./archive/QUICK_COMPARISON.md#container-management-platform)
|
||||
|
||||
**Docker vs Podman:**
|
||||
- CapRover requires Docker Swarm
|
||||
- Podman doesn't support Swarm
|
||||
- **Decision:** Docker (only option)
|
||||
- See: [archive/ALTERNATIVES_CONSIDERED.md](./archive/ALTERNATIVES_CONSIDERED.md#container-runtime-docker-vs-podman)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Success Criteria
|
||||
|
||||
You'll know it's working when:
|
||||
|
||||
1. ✅ CapRover dashboard accessible at `https://captain.yourdomain.com`
|
||||
2. ✅ Gitea accessible at `https://git.yourdomain.com`
|
||||
3. ✅ code-server accessible at `https://code.yourdomain.com`
|
||||
4. ✅ Claude Code extension installed and working in code-server
|
||||
5. ✅ Can clone, edit, commit, and push from code-server to Gitea
|
||||
6. ✅ code-server installed as PWA on iPad
|
||||
7. ✅ All services have valid SSL certificates
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
See detailed troubleshooting in [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md#troubleshooting)
|
||||
|
||||
**Common issues:**
|
||||
- CapRover not accessible → Check Oracle Security Lists and UFW firewall
|
||||
- SSL not working → Verify DNS propagated, Cloudflare proxy OFF
|
||||
- code-server can't clone → Check SSH key added to Gitea
|
||||
- Claude Code not working → Verify API key, check extension logs
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Structure
|
||||
|
||||
```
|
||||
Oracle Cloud/
|
||||
├── README.md (this file) ← Overview and quick reference
|
||||
├── IMPLEMENTATION_PLAN.md ← Step-by-step build guide ⭐
|
||||
└── archive/
|
||||
├── ALTERNATIVES_CONSIDERED.md ← Deep dive into alternatives
|
||||
└── QUICK_COMPARISON.md ← Comparison tables
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
**Ready to build?**
|
||||
|
||||
1. Open [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)
|
||||
2. Start with Phase 1 (Oracle Cloud VM setup)
|
||||
3. Follow each phase sequentially
|
||||
4. Come back here for quick reference
|
||||
|
||||
**Have questions about choices?**
|
||||
|
||||
- See [archive/ALTERNATIVES_CONSIDERED.md](./archive/ALTERNATIVES_CONSIDERED.md) for detailed analysis
|
||||
- See [archive/QUICK_COMPARISON.md](./archive/QUICK_COMPARISON.md) for quick comparisons
|
||||
|
||||
---
|
||||
|
||||
**Let's build this! 🚀**
|
||||
@@ -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.**
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user