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
• Installation Presets
  • Local (default)
  • Dev
  • Staging
  • Production
• Choosing a Preset
• Advanced Usage
• Troubleshooting

---

Quick Reference

# 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

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:

[database]
backend = "sqlite"
path = "~/.local/share/core/workspace.db"

Next Steps:

# 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

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:

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

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

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

# 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

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:

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

Database Configuration:

[database.surrealdb.docker]
mode = "docker"
url = "ws://surrealdb:8000"
docker_image = "surrealdb/surrealdb:latest"

Startup with Docker Compose:

# Start all services
docker-compose -f docker/docker-compose.yml up

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

Health Checks:

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

# 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

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:

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

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

Deployment:

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

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

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

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

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

nu scripts/install-syntaxis.nu --preset custom

Declarative Installation

Generate a config file and commit it:

# 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

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

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

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

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

# 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

# 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 for detailed provisioning information
• Read SURREALDB_SETUP_GUIDE.md for database administration
• Check docs/ARCHITECTURE.md for system architecture
• See docker/README.md for Docker-specific guidance
• See 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