provisioning/bootstrap/README.md

Provisioning Platform Bootstrap

Simple, flexible bootstrap script for provisioning platform installation.

No Rust compilation required - uses pure Bash + Nushell.

Quick Start

From Git Repository

git clone https://github.com/provisioning/provisioning.git
cd provisioning

# Run bootstrap
./provisioning/bootstrap/install.sh

What it Does (7 Stages)

1. System Detection - Detects OS, CPU, RAM, architecture
2. Dependency Check - Validates Docker, Rust, Nushell installed
3. Directory Structure - Creates workspace directories
4. Configuration Validation - Validates Nickel config syntax
5. Export Configuration - Exports config.ncl → TOML for services
6. Initialize Orchestrator - Starts orchestrator service
7. Verification - Confirms all files created and services running

Usage

Standard Bootstrap (Interactive)

./provisioning/bootstrap/install.sh

Nushell Direct

nu provisioning/bootstrap/install.nu $(pwd)

Requirements

Minimum:

• Nushell 0.109.0+ (auto-installed if missing)
• Docker (for containers)
• Rust + Cargo (for building services)
• Git (for cloning)

Recommended:

• 2+ GB RAM
• 10+ GB disk
• macOS, Linux, or WSL2

What Gets Created

After bootstrap, your workspace has:

workspace_librecloud/
├── config/
│   ├── config.ncl                 ← Master config (Nickel)
│   └── generated/                 ← Auto-exported TOML
│       ├── workspace.toml
│       ├── providers/
│       │   ├── upcloud.toml
│       │   └── local.toml
│       └── platform/
│           └── orchestrator.toml
├── .orchestrator/data/queue/      ← Orchestrator data
├── .kms/                          ← KMS data
├── .providers/                    ← Provider state
├── .taskservs/                    ← Task service data
└── .clusters/                     ← Cluster data

Differences from Rust Installer

Feature	Rust Installer	Bash+Nushell Bootstrap
Requires compilation	✅ Yes (5+ min)	❌ No
Flexible	⚠️ Limited	✅ Fully scriptable
Source code	❌ Binary	✅ Clear scripts
Easy to modify	❌ Recompile	✅ Edit script
Integrates with TypeDialog	❌ Hard	✅ Easy
Deployable everywhere	✅ Binary	✅ Script
TUI Interface	✅ Ratatui	⚠️ Text menus

Troubleshooting

"Nushell not found"

# Install Nushell manually:
# macOS:
brew install nushell

# Linux (Debian):
sudo apt install nushell

# Linux (RHEL):
sudo yum install nushell

# Or: https://nushell.sh/book/installation.html

"Docker not installed"

# https://docs.docker.com/get-docker/

"Rust not installed"

# https://rustup.rs/
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

"Configuration validation failed"

# Check Nickel syntax
nickel typecheck workspace_librecloud/config/config.ncl

# Fix errors in config.ncl
vim workspace_librecloud/config/config.ncl

# Re-run bootstrap
./provisioning/bootstrap/install.sh

"Orchestrator didn't start"

# Check logs
tail -f workspace_librecloud/.orchestrator/logs/orchestrator.log

# Manual start
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

# Check health
curl http://localhost:9090/health

After Bootstrap

Once complete:

1. Verify orchestrator:

   curl http://localhost:9090/health
   

2. Update configuration (optional):

   provisioning config platform orchestrator
   

3. Start provisioning:

   provisioning server create --infra sgoyol --name web-01
   

4. Monitor progress:

   provisioning workflow monitor <workflow_id>
   

Development

Add New Bootstrap Stage

Edit install.nu and add:

# Stage N: YOUR STAGE NAME
print "🔧 Stage N: Your Stage Name"
print "─────────────────────────────────────────────────────────────────"

# Your logic here

print "  ✅ Done"
print ""

Modify Existing Stages

Direct script edits - no compilation needed. Changes take effect immediately.

Extend Bootstrap

Add new scripts in provisioning/bootstrap/ directory:

provisioning/bootstrap/
├── install.sh              # Entry point
├── install.nu              # Main orchestrator
├── validators.nu           # Validation helpers (future)
├── generators.nu           # Generator helpers (future)
└── README.md              # This file

Comparison to Old Rust Installer

Old way:

1. Run Rust installer binary
2. Need to recompile for any changes
3. Difficult to integrate with TypeDialog
4. Hard to debug

New way:

1. Run simple bash script
2. Changes take effect immediately
3. Uses existing Nushell libraries
4. Easy to extend and debug

FAQ

Q: Why not keep the Rust installer? A: Rust crate was over-engineered for bootstrap. Bash+Nushell is simpler, more flexible, and integrates better with the rest of the system.

Q: Can I customize the bootstrap? A: Yes! Edit install.nu directly. Add new stages, change logic, integrate TypeDialog - all without compilation.

Q: What about TUI interface? A: Bootstrap uses text menus. If you need a fancy TUI, you can build a separate Rust tool, but it's not required for basic installation.

Q: Is this production-ready? A: Yes. It's simpler and more robust than the old Rust installer.

---

Status: ✅ Ready for use Last Updated: 2025-01-02