syntaxis/docs/installation-contexts.md

# Installation Contexts Guide

This guide explains the different installation contexts (presets) available for syntaxis and how to choose the right one for your use case.

**Table of Contents:**
- [Quick Reference](#quick-reference)
- [Installation Presets](#installation-presets)
  - [Local (default)](#local-development)
  - [Dev](#development-with-services)
  - [Staging](#staging--cicd)
  - [Production](#production)
- [Choosing a Preset](#choosing-a-preset)
- [Advanced Usage](#advanced-usage)
- [Troubleshooting](#troubleshooting)

---

## Quick Reference

```bash
# Simple dev on laptop (SQLite, no services)
nu scripts/install-syntaxis.nu --preset local

# Dev with services (SurrealDB server, NATS)
nu scripts/install-syntaxis.nu --preset dev

# Staging/CI-CD (Docker services, monitoring)
nu scripts/install-syntaxis.nu --preset staging

# Production (Kubernetes)
nu scripts/install-syntaxis.nu --preset production

# Interactive mode (will ask questions)
nu scripts/install-syntaxis.nu --interactive

# Generate config without installing
nu scripts/install-syntaxis.nu --preset dev --generate-config > my-install.toml

# Install from config file
nu scripts/install-syntaxis.nu --config my-install.toml
```

---

## Installation Presets

### Local Development

**Best for:** Single developer on a laptop, offline work, minimal setup

```bash
nu scripts/install-syntaxis.nu --preset local
```

**Configuration:**
- **Database:** SQLite (file-based)
- **Services:** None (binaries only)
- **provctl:** Not needed
- **Startup Time:** ~5 minutes
- **Dependencies:** Rust toolchain (for building)

**What gets installed:**
- ✅ `syntaxis-cli` - Command-line interface
- ✅ `syntaxis-tui` - Terminal user interface
- ❌ `syntaxis-api` - Disabled
- ❌ `dashboard` - Disabled
- ✅ Wrapper scripts for auto-config discovery

**Database Configuration:**
```toml
[database]
backend = "sqlite"
path = "~/.local/share/core/workspace.db"
```

**Next Steps:**
```bash
# Use the CLI
syntaxis-cli init my-project
syntaxis-cli list

# Or use the TUI
syntaxis-tui

# To upgrade to dev preset later:
nu scripts/install-syntaxis.nu --preset dev
```

**Pros:**
- ✅ Minimal installation time
- ✅ No external dependencies
- ✅ Works offline
- ✅ Lightweight (SQLite)
- ✅ Good for learning

**Cons:**
- ❌ No API/Dashboard
- ❌ No real-time messaging (NATS)
- ❌ Limited scaling
- ❌ SQLite has concurrency limits

---

### Development with Services

**Best for:** Full-stack development, testing API, dashboard work, local experimentation

```bash
nu scripts/install-syntaxis.nu --preset dev
```

**Configuration:**
- **Database:** SurrealDB (server mode)
- **Services:** SurrealDB, NATS, syntaxis-api, Dashboard
- **provctl:** Recommended (handles service startup)
- **Startup Time:** ~10-15 minutes
- **Dependencies:** Docker (optional), SurrealDB CLI, NuShell

**What gets installed:**
- ✅ All binaries (CLI, TUI, API)
- ✅ `syntaxis-api` - REST API server (port 3000)
- ✅ `dashboard` - Web UI (port 8080)
- ✅ SurrealDB configuration
- ✅ NATS configuration (optional)
- ✅ Service startup scripts

**Database Configuration:**
```toml
[database.surrealdb.server]
mode = "server"
url = "ws://127.0.0.1:8000"
namespace = "syntaxis"
database = "projects"
```

**Services:**
```
SurrealDB (Port 8000)
  ↓
syntaxis-api (Port 3000)
  ↓
Dashboard (Port 8080)
```

**Startup with provctl:**
```bash
# Auto-start services
nu scripts/install-syntaxis.nu --preset dev

# Or manually with provctl
provctl start surrealdb
provctl start nats
provctl start syntaxis-api

# Check status
provctl status
```

**Startup without provctl (manual):**
```bash
# Terminal 1: Start SurrealDB
surreal start --bind 127.0.0.1:8000 memory

# Terminal 2: Start NATS
nats-server

# Terminal 3: Start API
syntaxis-api

# Terminal 4: Use API/Dashboard
open http://localhost:3000
open http://localhost:8080
```

**Next Steps:**
```bash
# Test the API
curl http://localhost:3000/health

# Use the CLI
syntaxis-cli list-projects

# Open dashboard in browser
open http://localhost:3000
```

**Pros:**
- ✅ Full feature set
- ✅ Can test API integration
- ✅ Dashboard available
- ✅ NATS for async messaging
- ✅ SurrealDB supports scaling
- ✅ provctl automates startup

**Cons:**
- ❌ More startup time
- ❌ Requires SurrealDB CLI
- ❌ More resource usage
- ❌ Need to manage services

---

### Staging / CI-CD

**Best for:** Integration testing, CI/CD pipelines, team environments, pre-production validation

```bash
nu scripts/install-syntaxis.nu --preset staging
```

**Configuration:**
- **Database:** SurrealDB (Docker mode)
- **Services:** SurrealDB (Docker), NATS (Docker), API, Dashboard, Prometheus
- **provctl:** Recommended (manages Docker containers)
- **Startup Time:** ~20 minutes
- **Dependencies:** Docker, Docker Compose

**What gets installed:**
- ✅ All binaries
- ✅ Docker Compose configuration
- ✅ Service health checks
- ✅ Prometheus monitoring
- ✅ Automated startup scripts

**Docker Services:**
```yaml
services:
  surrealdb:      # SurrealDB in Docker
  nats:           # NATS message broker
  syntaxis-api:   # API server
  dashboard:      # Web UI
  prometheus:     # Metrics collection
```

**Database Configuration:**
```toml
[database.surrealdb.docker]
mode = "docker"
url = "ws://surrealdb:8000"
docker_image = "surrealdb/surrealdb:latest"
```

**Startup with Docker Compose:**
```bash
# Start all services
docker-compose -f docker/docker-compose.yml up

# Or with provctl
provctl deploy --config configs/provisioning/services/surrealdb.toml
```

**Health Checks:**
```bash
# Verify services are healthy
curl http://localhost:3000/health
curl http://localhost:9090/metrics  # Prometheus

# Check service status
provctl status
```

**Ports:**
```
SurrealDB:   8000/tcp
NATS:        4222/tcp
API:         3000/tcp
Dashboard:   8080/tcp
Prometheus:  9090/tcp
```

**CI/CD Integration:**
```yaml
# Example GitHub Actions
- name: Start services
  run: docker-compose -f docker/docker-compose.yml up -d

- name: Wait for API
  run: curl --retry 10 http://localhost:3000/health

- name: Run tests
  run: cargo test --all
```

**Pros:**
- ✅ Container-based (reproducible)
- ✅ Easy scaling
- ✅ Monitoring included
- ✅ Great for CI/CD
- ✅ Team-friendly

**Cons:**
- ❌ Requires Docker
- ❌ More complex setup
- ❌ Higher resource usage
- ❌ Network overhead

---

### Production

**Best for:** Enterprise deployments, high availability, Kubernetes clusters, managed infrastructure

```bash
nu scripts/install-syntaxis.nu --preset production
```

**Configuration:**
- **Database:** SurrealDB (Kubernetes cluster)
- **Services:** All services in Kubernetes with replicas
- **provctl:** Optional (K8s manages services)
- **Startup Time:** ~30-60 minutes
- **Dependencies:** Kubernetes cluster, kubectl, TLS certificates

**What gets installed:**
- ✅ All binaries
- ✅ Kubernetes manifests
- ✅ Service definitions (Deployments, StatefulSets)
- ✅ Ingress configuration
- ✅ TLS certificates
- ✅ RBAC policies
- ✅ Resource limits
- ✅ Monitoring (Prometheus + Grafana)

**Kubernetes Services:**
```yaml
# High-availability setup
- SurrealDB:     3 replicas (StatefulSet)
- NATS:          3 replicas (StatefulSet)
- syntaxis-api:  3 replicas (Deployment)
- Dashboard:     2 replicas (Deployment)
- Prometheus:    1 replica (Deployment)
- Grafana:       1 replica (Deployment)
```

**Database Configuration:**
```toml
[database.surrealdb.kubernetes]
mode = "kubernetes"
url = "ws://surrealdb.syntaxis.svc.cluster.local:8000"
replicas = 3
```

**Deployment:**
```bash
# Apply Kubernetes manifests
kubectl apply -f kubernetes/namespace.yaml
kubectl apply -f kubernetes/secrets.yaml
kubectl apply -f kubernetes/configmaps.yaml
kubectl apply -f kubernetes/surrealdb/
kubectl apply -f kubernetes/nats/
kubectl apply -f kubernetes/syntaxis-api/
kubectl apply -f kubernetes/dashboard/

# Check deployment
kubectl get pods -n syntaxis
kubectl get svc -n syntaxis

# Monitor
kubectl logs -n syntaxis deployment/syntaxis-api
kubectl port-forward svc/syntaxis-api 3000:3000
```

**Health Checks:**
```bash
# Via kubectl
kubectl exec -it svc/surrealdb -- surreal config

# Via port-forward
kubectl port-forward svc/syntaxis-api 3000:3000
curl http://localhost:3000/health
```

**Monitoring:**
```bash
# Prometheus metrics
kubectl port-forward svc/prometheus 9090:9090
# Visit http://localhost:9090

# Grafana dashboards
kubectl port-forward svc/grafana 3001:3000
# Visit http://localhost:3001
```

**Ingress (External Access):**
```yaml
# Example ingress configuration
ingress.syntaxis.your-domain.com → API (3000)
dashboard.your-domain.com         → Dashboard (8080)
```

**Security:**
- ✅ TLS encryption (HTTPS)
- ✅ RBAC policies
- ✅ Network policies
- ✅ Secret management
- ✅ Container security scanning

**Pros:**
- ✅ High availability
- ✅ Auto-scaling
- ✅ Load balancing
- ✅ Enterprise-grade monitoring
- ✅ Self-healing
- ✅ Rolling updates

**Cons:**
- ❌ Complex setup
- ❌ Kubernetes knowledge required
- ❌ Expensive infrastructure
- ❌ Operational overhead
- ❌ Steeper learning curve

---

## Choosing a Preset

### Decision Tree

```
Are you developing locally?
├─ YES → Do you want to test the API/Dashboard?
│   ├─ NO  → Use: local
│   └─ YES → Use: dev
└─ NO → Is this for a team/CI-CD?
    ├─ YES → Use: staging
    └─ NO → Is this for production?
        ├─ YES → Use: production
        └─ NOT_SURE → Use: dev (can upgrade later)
```

### Quick Comparison Table

| Aspect | Local | Dev | Staging | Production |
|--------|-------|-----|---------|------------|
| **Best for** | Solo dev | API testing | CI/CD, teams | Enterprise |
| **Database** | SQLite | SurrealDB server | SurrealDB Docker | SurrealDB K8s |
| **Services** | None | 4 | 5+ | 6+ |
| **provctl needed** | ❌ | ✅ (recommended) | ✅ (recommended) | ❌ (K8s manages) |
| **Setup time** | 5 min | 15 min | 20 min | 60 min |
| **Resource usage** | Low | Medium | Medium-High | High |
| **Scaling** | ❌ | ❌ | Limited | ✅ |
| **HA/Replicas** | ❌ | ❌ | ❌ | ✅ |
| **Monitoring** | ❌ | ❌ | ✅ | ✅ |
| **TLS/Security** | ❌ | ❌ | Partial | ✅ |

---

## Advanced Usage

### Custom Preset

Create your own preset by extending `configs/installation.toml`:

```toml
[preset.custom]
name = "My Custom Setup"
description = "Custom configuration"
database_backend = "surrealdb"
surrealdb_mode = "server"
auto_start_services = true

[preset.custom.services]
syntaxis_api = { enabled = true, auto_start = true, port = 3001 }
surrealdb = { enabled = true, auto_start = true }
nats = { enabled = false }
```

Then use:
```bash
nu scripts/install-syntaxis.nu --preset custom
```

### Declarative Installation

Generate a config file and commit it:

```bash
# Generate config for your team
nu scripts/install-syntaxis.nu --preset dev --generate-config > team-install.toml

# Everyone uses the same config
nu scripts/install-syntaxis.nu --config team-install.toml
```

### Migration Between Presets

```bash
# Start with local
nu scripts/install-syntaxis.nu --preset local

# Later, upgrade to dev
nu scripts/install-syntaxis.nu --preset dev

# Then move to staging
nu scripts/install-syntaxis.nu --preset staging
```

---

## Troubleshooting

### "provctl not found"

**Problem:** Installer says provctl is not available

**Solution:**
```bash
# Install provctl from source
git clone https://github.com/Akasha/provctl
cd provctl
cargo install --path .

# Or use without provctl (manual setup)
nu scripts/install-syntaxis.nu --preset dev --provctl disabled
```

### Services won't start

**Problem:** SurrealDB or NATS won't start after installation

**Solution:**
```bash
# Check if services are already running
provctl status

# Try manual startup
surreal start --bind 127.0.0.1:8000 memory
nats-server

# Check logs
provctl logs surrealdb
provctl logs nats
```

### Database connection error

**Problem:** API can't connect to database

**Check database mode:**
```bash
# For dev preset, make sure SurrealDB is running
surreal start --bind 127.0.0.1:8000 memory

# Verify connection
curl ws://127.0.0.1:8000
```

### Port already in use

**Problem:** Port 3000 or 8000 is already in use

**Solution:**
```bash
# Use different port in installation.toml
[preset.custom.services]
syntaxis_api = { port = 3001 }
surrealdb = { port = 8001 }

# Or kill existing process
lsof -i :3000
kill -9 <PID>
```

### Rollback to previous preset

```bash
# Installation creates backups
ls ~/.config/syntaxis/archives/

# Restore from backup
cp -r ~/.config/syntaxis/archives/YYYY-MM-DD-HH-MM/* ~/.config/syntaxis/
```

---

## Next Steps

- Read [docs/provisioning.md](docs/provisioning.md) for detailed provisioning information
- Read [SURREALDB_SETUP_GUIDE.md](SURREALDB_SETUP_GUIDE.md) for database administration
- Check [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for system architecture
- See [docker/README.md](docker/README.md) for Docker-specific guidance
- See [kubernetes/README.md](kubernetes/README.md) for Kubernetes deployment

---

**Last Updated:** 2025-11-19
**Related Files:** `configs/installation.toml`, `scripts/install-syntaxis.nu`, `scripts/provisioning/detect-provctl.nu`