feat: Add dynamic participant scaling and improved UX
- Makefile: Add local-vm-test/local-vm-full targets, improve error messages - README.md: Document dynamic scaling, add troubleshooting section - flake.nix: Implement dynamic container generation based on PARTICIPANTS env var This enables running the workshop VM with 1-15 containers instead of fixed 15, making local development more accessible on resource-constrained machines.
This commit is contained in:
135
README.md
135
README.md
@@ -1,19 +1,23 @@
|
||||
# 🍪 CODE CRISPIES Workshop Infrastructure
|
||||
|
||||
This repository contains the infrastructure for the Co-op Cloud workshop, providing three distinct deployment environments.
|
||||
This repository contains the infrastructure for the Co-op Cloud workshop, providing three distinct deployment environments with dynamic scaling support.
|
||||
|
||||
---
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Start the local development virtual machine (15 containers)
|
||||
# 1. Start the local development virtual machine (default: 3 containers)
|
||||
make local-vm-run
|
||||
|
||||
# 2. Build & flash USB drives for participants
|
||||
# 2. Test with different container counts
|
||||
PARTICIPANTS=2 make local-vm-test # Lightweight testing
|
||||
PARTICIPANTS=15 make local-vm-full # Full workshop simulation
|
||||
|
||||
# 3. Build & flash USB drives for participants
|
||||
make build-usb
|
||||
make flash-usb USB_DEVICE=/dev/sdX
|
||||
|
||||
# 3. Deploy the production cloud infrastructure
|
||||
# 4. Deploy the production cloud infrastructure
|
||||
export HCLOUD_TOKEN="your_token_here"
|
||||
make deploy-cloud
|
||||
```
|
||||
@@ -23,7 +27,7 @@ make deploy-cloud
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
├── flake.nix # All Nix configurations (USB, VM)
|
||||
├── flake.nix # All Nix configurations (USB, VM, containers)
|
||||
├── terraform/ # Hetzner Cloud infrastructure
|
||||
├── scripts/deploy.sh # Cloud setup automation
|
||||
├── docs/USB_BOOT_INSTRUCTIONS.md
|
||||
@@ -48,50 +52,56 @@ make deploy-cloud
|
||||
|
||||
### 3. Local (Development)
|
||||
|
||||
- **What:** A self-contained Virtual Machine (VM) that runs on your local computer with all 15 containers.
|
||||
- **What:** A self-contained Virtual Machine (VM) that runs on your local computer with configurable container count.
|
||||
- **Purpose:** Complete local testing environment that mirrors production setup without needing cloud servers.
|
||||
- **Resources:** Creates 15 containers (heavy resource usage - ensure adequate RAM/CPU)
|
||||
- **Scalability:** Supports 1-15 containers via `PARTICIPANTS` environment variable.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Local Development Workflow
|
||||
|
||||
1. **Start the VM**
|
||||
Run the following command. A new window will open and automatically boot into a lightweight desktop.
|
||||
|
||||
1. **Choose Your Scale**
|
||||
```bash
|
||||
# Lightweight development (2 containers)
|
||||
PARTICIPANTS=2 make local-vm-run
|
||||
|
||||
# Production simulation (15 containers) - requires 8GB+ RAM
|
||||
PARTICIPANTS=15 make local-vm-run
|
||||
|
||||
# Use default (3 containers) - good balance
|
||||
make local-vm-run
|
||||
```
|
||||
|
||||
2. **Work Inside the VM**
|
||||
All testing is now done inside the VM's graphical desktop.
|
||||
|
||||
All testing is now done inside the VM's graphical desktop:
|
||||
* Open the **Terminal** to run commands.
|
||||
* Open **Firefox** to view the deployed web applications.
|
||||
|
||||
3. **Example: Deploying WordPress**
|
||||
|
||||
**In the VM's Terminal**, get a root shell and SSH into a participant's container:
|
||||
```bash
|
||||
# Become root (no password needed)
|
||||
sudo -i
|
||||
|
||||
* **In the VM's Terminal**, get a root shell and SSH into a participant's container:
|
||||
```bash
|
||||
# Become root (no password needed)
|
||||
sudo -i
|
||||
# Connect to participant 1 (hopper)
|
||||
connect hopper
|
||||
|
||||
# Connect to participant 1 (hopper)
|
||||
connect hopper
|
||||
|
||||
# Or direct SSH
|
||||
ssh root@192.168.100.11
|
||||
```
|
||||
* **Inside the container**, deploy a WordPress site with `abra`:
|
||||
```bash
|
||||
abra app new wordpress -S --domain=blog.hopper.local
|
||||
abra app deploy blog.hopper.local
|
||||
```
|
||||
* **In the VM's Firefox**, navigate to `http://blog.hopper.local`. You will see the WordPress installation screen.
|
||||
# Or direct SSH (password: root)
|
||||
ssh root@192.168.100.11
|
||||
```
|
||||
|
||||
**Inside the container**, deploy a WordPress site with `abra`:
|
||||
```bash
|
||||
abra app new wordpress -S --domain=blog.hopper.local
|
||||
abra app deploy blog.hopper.local
|
||||
```
|
||||
|
||||
**In the VM's Firefox**, navigate to `http://blog.hopper.local`. You will see the WordPress installation screen.
|
||||
|
||||
4. **Available Helper Commands**
|
||||
```bash
|
||||
sudo containers # List all 15 containers with IPs
|
||||
sudo containers # List all containers with IPs
|
||||
sudo logs # Show setup logs for all containers
|
||||
sudo recipes # Display available Co-op Cloud recipes
|
||||
sudo help # Show all available commands
|
||||
@@ -144,7 +154,25 @@ The USB environment includes:
|
||||
|
||||
---
|
||||
|
||||
## 🧹 Cleanup
|
||||
## ⚙️ Environment Variables
|
||||
|
||||
Control workshop behavior with environment variables:
|
||||
|
||||
```bash
|
||||
# Number of containers (1-15, default: 3)
|
||||
export PARTICIPANTS=5
|
||||
make local-vm-run
|
||||
|
||||
# Workshop domain for cloud deployment
|
||||
export WORKSHOP_DOMAIN=myworkshop.com
|
||||
|
||||
# USB device for flashing
|
||||
export USB_DEVICE=/dev/sdb
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧹 Cleanup & Management
|
||||
|
||||
```bash
|
||||
# Clean local build artifacts
|
||||
@@ -153,7 +181,12 @@ make clean
|
||||
# Destroy Hetzner cloud infrastructure
|
||||
make destroy-cloud
|
||||
|
||||
# To stop the local VM, simply close its window
|
||||
# Verify VM builds correctly
|
||||
make check-vm
|
||||
|
||||
# Run development tools
|
||||
make opencode # Start development environment
|
||||
make lint # Code quality checks
|
||||
```
|
||||
|
||||
---
|
||||
@@ -166,7 +199,10 @@ make destroy-cloud
|
||||
```
|
||||
- **Nix:** NixOS or Nix package manager with flakes enabled
|
||||
- **Cloud Tokens:** Hetzner Cloud API token for deployment
|
||||
- **Resources:** For local VM: 8GB+ RAM recommended (runs 15 containers)
|
||||
- **Resources:**
|
||||
- 2-3 containers: 4GB+ RAM
|
||||
- 5-10 containers: 8GB+ RAM
|
||||
- 15 containers: 16GB+ RAM
|
||||
|
||||
---
|
||||
|
||||
@@ -175,6 +211,39 @@ make destroy-cloud
|
||||
1. **Preparation:** Deploy cloud infrastructure with `make deploy-cloud`
|
||||
2. **Distribution:** Flash USB drives for participants with `make build-usb && make flash-usb`
|
||||
3. **Workshop:** Participants boot from USB and connect to their assigned cloud servers
|
||||
4. **Development:** Use local VM (`make local-vm-run`) for testing and development
|
||||
4. **Development:** Use local VM with `make local-vm-run` for testing and development
|
||||
|
||||
The architecture ensures participants get identical environments whether connecting from USB boot drives to cloud servers, or testing locally in the development VM.
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### VM Won't Start
|
||||
```bash
|
||||
# Check if build works
|
||||
make check-vm
|
||||
|
||||
# Try with fewer containers
|
||||
PARTICIPANTS=2 make local-vm-run
|
||||
```
|
||||
|
||||
### Containers Not Accessible
|
||||
```bash
|
||||
# Check container status inside VM
|
||||
sudo containers
|
||||
|
||||
# View setup logs
|
||||
sudo logs
|
||||
|
||||
# Manual SSH test
|
||||
ssh root@192.168.100.11 # Password: root
|
||||
```
|
||||
|
||||
### Abra Not Working in Container
|
||||
```bash
|
||||
# Inside container, check installation
|
||||
ls -la /root/.local/bin/abra
|
||||
export PATH="/root/.local/bin:$PATH"
|
||||
abra --version
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user