176 lines
4.7 KiB
Markdown
176 lines
4.7 KiB
Markdown
# 🚀 CODE CRISPIES Workshop Infrastructure
|
|
|
|
Single-participant learning environments with local practice and cloud deployment capabilities.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# 1. Start local VM for development/testing
|
|
make vm-run
|
|
|
|
# 2. Build USB drives for participants
|
|
make build-usb
|
|
make flash-usb USB_DEVICE=/dev/sdX
|
|
|
|
# 3. Deploy cloud infrastructure
|
|
export HCLOUD_TOKEN="your_token"
|
|
make deploy-cloud
|
|
```
|
|
|
|
## 🎯 Learning Flow
|
|
|
|
### Local Practice (USB/VM)
|
|
```bash
|
|
setup-traefik # REQUIRED: Setup local proxy first!
|
|
recipes # Show available apps
|
|
deploy wordpress # Deploy locally
|
|
browser wordpress # Open directly in Firefox
|
|
```
|
|
|
|
### Cloud Deployment
|
|
```bash
|
|
connect hopper # SSH to cloud server
|
|
# Same abra commands work here
|
|
abra app new wordpress -S --domain=blog.hopper.codecrispi.es
|
|
abra app deploy blog.hopper.codecrispi.es
|
|
```
|
|
|
|
## 🗃️ Architecture
|
|
|
|
**Single Participant Model**: Each environment (USB/VM) is complete and self-contained.
|
|
|
|
- **USB Boot**: Bootable NixOS with Docker + abra for hands-on learning
|
|
- **Local VM**: Identical environment for development/testing
|
|
- **Cloud Servers**: 15 production servers (hopper, curie, lovelace, etc.)
|
|
- **Wildcard DNS**: `*.workshop.local` resolves to `127.0.0.1` via dnsmasq
|
|
|
|
## 💾 USB Environment
|
|
|
|
Pre-configured with:
|
|
- Docker Swarm + abra installation
|
|
- SSH client for cloud access
|
|
- Wildcard DNS resolution (dnsmasq)
|
|
- Terminal-first interface (`desktop` command for GUI)
|
|
- Helper commands: `recipes`, `deploy`, `connect`, `browser`, `help`
|
|
- Tab completion for all commands
|
|
|
|
Build and flash:
|
|
```bash
|
|
make build-usb
|
|
make flash-usb USB_DEVICE=/dev/sdb
|
|
```
|
|
|
|
## 🌐 Cloud Deployment
|
|
|
|
Creates 15 Hetzner VMs at `{name}.codecrispi.es`:
|
|
|
|
```bash
|
|
export HCLOUD_TOKEN="your_token"
|
|
make deploy-cloud
|
|
make status-cloud # Check health
|
|
```
|
|
|
|
## 🖥️ Local Development
|
|
|
|
```bash
|
|
make vm-run # Start VM
|
|
make vm-build # Verify build
|
|
```
|
|
|
|
The VM simulates the USB experience with identical configuration and commands.
|
|
|
|
## 📚 Complete Recipe Catalog
|
|
|
|
Based on Co-op Cloud with quality scoring:
|
|
|
|
### ⭐ Tier 1 - Production Ready (Score 5)
|
|
- **gitea** - Self-hosted Git service
|
|
- **nextcloud** - Personal cloud storage & collaboration
|
|
- **mealie** - Recipe manager and meal planner
|
|
|
|
### 🔧 Tier 2 - Stable (Score 4)
|
|
- **gotosocial** - Lightweight Fediverse server
|
|
- **wordpress** - Website & blog platform
|
|
|
|
### 🧪 Tier 3 - Community (Score 3)
|
|
- **collabora** - Online office suite
|
|
- **croc** - File transfer tool
|
|
- **custom-php** - Custom PHP applications
|
|
- **dokuwiki** - Simple wiki software
|
|
- **engelsystem** - Event coordination
|
|
- **fab-manager** - FabLab management
|
|
- **ghost** - Professional publishing platform
|
|
- **karrot** - Grassroots initiatives platform
|
|
- **lauti** - Calendar software for events
|
|
- **loomio** - Collaborative decision-making
|
|
- **mattermost** / **mattermost-lts** - Team collaboration
|
|
- **mrbs** - Meeting room booking system
|
|
- **onlyoffice** - Document editing suite
|
|
- **open-inventory** - Inventory management
|
|
- **outline** - Team knowledge base
|
|
- **owncast** - Self-hosted live streaming
|
|
- **rallly** - Group meeting scheduler
|
|
|
|
### 🌐 Extended Catalog
|
|
- **Content**: hedgedoc, mediawiki, seafile
|
|
- **Communication**: jitsi-meet, matrix-synapse, rocketchat
|
|
- **Business**: prestashop, invoiceninja, kimai, pretix
|
|
- **Development**: drone, n8n, gitlab, jupyter-lab
|
|
- **Analytics**: plausible, matomo, uptime-kuma, grafana
|
|
- **Media & Social**: peertube, funkwhale, mastodon, pixelfed, jellyfin
|
|
|
|
## 📚 Enhanced Commands
|
|
|
|
**In USB/VM environments**:
|
|
- `setup-traefik` - **REQUIRED FIRST**: Setup local DNS proxy
|
|
- `recipes` - Show complete Co-op Cloud catalog
|
|
- `deploy <app>` - Deploy locally with tab completion
|
|
- `browser [app]` - Launch Firefox [to specific app]
|
|
- `connect <server>` - SSH to cloud server with tab completion
|
|
- `desktop` - Start GUI session
|
|
- `help` - Show all commands and debug info
|
|
|
|
**Examples**:
|
|
```bash
|
|
# Deploy and open WordPress
|
|
deploy wordpress
|
|
browser wordpress # Opens http://wordpress.workshop.local
|
|
|
|
# Just open browser
|
|
browser # Opens blank page
|
|
|
|
# Use tab completion
|
|
deploy <TAB> # Shows all available recipes
|
|
connect <TAB> # Shows all available servers
|
|
```
|
|
|
|
## 🔧 Prerequisites
|
|
|
|
- Nix with flakes enabled
|
|
- SSH key at `~/.ssh/id_ed25519.pub`
|
|
- HCLOUD_TOKEN for cloud deployment
|
|
- 2GB+ RAM for VM testing
|
|
|
|
## 🧹 Cleanup
|
|
|
|
```bash
|
|
make clean # Local artifacts
|
|
make destroy-cloud # Cloud infrastructure
|
|
```
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
```bash
|
|
# Check DNS resolution
|
|
dig @127.0.0.1 test.workshop.local
|
|
|
|
# Check running services
|
|
docker service ls
|
|
|
|
# Check DNS service
|
|
systemctl status dnsmasq
|
|
|
|
# Restart if needed
|
|
sudo systemctl restart dnsmasq
|
|
```
|