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
```plaintext

### 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)

```bash
./provisioning/bootstrap/install.sh
```plaintext

### Nushell Direct

```bash
nu provisioning/bootstrap/install.nu $(pwd)
```plaintext

## 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:

```plaintext
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
```plaintext

## 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"

```bash
# 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
```plaintext

### "Docker not installed"

```bash
# https://docs.docker.com/get-docker/
```plaintext

### "Rust not installed"

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

### "Configuration validation failed"

```bash
# 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
```plaintext

### "Orchestrator didn't start"

```bash
# 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
```plaintext

## After Bootstrap

Once complete:

1. **Verify orchestrator**:

   ```bash
   curl http://localhost:9090/health

1. Update configuration (optional):

   provisioning config platform orchestrator
   

2. Start provisioning:

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

3. 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 ""
```plaintext

### Modify Existing Stages

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

### Extend Bootstrap

Add new scripts in `provisioning/bootstrap/` directory:

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

## 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