syntaxis/docs/provisioning.md

syntaxis Provisioning & Distribution Guide

Complete guide to building, packaging, and distributing syntaxis using the modular provisioning system and automated CI/CD.

Overview

The syntaxis project includes a complete distribution pipeline:

┌─────────────────┐
│  Source Code    │
└────────┬────────┘
         │
    ┌────▼────────────────────┐
    │  Local Development      │
    │  (pack.nu via scripts)  │
    └────┬──────────┬─────────┘
         │          │
    ┌────▼───┐  ┌───▼──────────┐
    │ Bundle │  │ GitHub Tags  │
    │ (local)│  │ (trigger CI) │
    └────┬───┘  └───┬──────────┘
         │          │
         │    ┌─────▼────────────────────┐
         │    │ GitHub Actions CI/CD     │
         │    │ (.github/workflows/)     │
         │    └─────┬──────────┬─────────┘
         │          │          │
         │    ┌─────▼────┐  ┌──▼────────┐
         │    │ Multi-   │  │ Auto-     │
         │    │ platform │  │ Release   │
         │    │ builds   │  │ on GitHub │
         │    └─────┬────┘  └──┬────────┘
         │          │          │
         └──────────┬──────────┘
                    │
            ┌───────▼────────┐
            │ User Downloads │
            │ & Installs     │
            └────────────────┘

Quick Start

For Developers (Build & Test Locally)

# 1. View available targets
nu scripts/provisioning/pack.nu --list-targets

# 2. Create bundle for your platform
nu scripts/provisioning/pack.nu

# 3. Bundle appears in: dist/syntaxis-v0.1.0-x86_64-linux.tar.gz

# 4. Test installation locally
nu scripts/provisioning/provctl.nu full-install --bundle dist/*.tar.gz --prefix ~/.local-test

# 5. Test the binaries
~/.local-test/bin/syntaxis-cli --version

For CI/CD (Automated Releases)

1. Make changes and commit to main or develop branch
2. Create a tag to trigger release:

   git tag v0.2.0
   git push origin v0.2.0
   

3. GitHub Actions automatically:
   • Builds binaries for all 5 platforms
   • Creates bundles with configs and docs
   • Generates checksums
   • Creates GitHub Release with downloads
   • Publishes documentation

Workflows

GitHub Actions Workflows

Two main workflows are provided:

1. build.yml - Continuous Integration

Runs on every push to main/develop and all pull requests:

• ✅ Code formatting check (cargo fmt)
• ✅ Linting (cargo clippy)
• ✅ Unit tests (cargo test)
• ✅ Build check (cargo check)
• ✅ Security audit (cargo audit)
• ✅ Debug builds on all platforms (Linux, macOS, Windows)
• ✅ Release builds on main branch

When to check build artifacts:

• Go to workflow run → Artifacts
• Download release-ubuntu-latest, release-macos-latest, or release-windows-latest

2. release.yml - Release & Distribution

Runs on git tags (when you push v* tag):

• 🔨 Builds for 5 platforms in parallel
• 📦 Creates self-contained bundles
• 📋 Generates manifests and checksums
• 🚀 Creates GitHub Release
• 📄 Publishes documentation
• 🔗 Generates release notes

Platforms built:

1. Linux x86_64 (glibc) - Ubuntu latest
2. Linux ARM64 (aarch64) - Via cross-compilation
3. macOS Intel (x86_64) - macOS latest
4. macOS Apple Silicon (aarch64) - macOS latest
5. Windows x86_64 (MSVC) - Windows latest

Distribution Methods

Method 1: GitHub Releases (Recommended for End Users)

For users:

# Download latest release
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/syntaxis-x86_64-linux-v0.1.0.tar.gz -o bundle.tar.gz

# Verify integrity
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/SHA256SUMS | sha256sum -c -

# Install
tar -xzf bundle.tar.gz
cd syntaxis-v0.1.0-x86_64-linux
./install.sh

Method 2: Package Managers (Homebrew, apt, etc.)

For macOS (Homebrew) - Future implementation:

brew install syntaxis/syntaxis/syntaxis

For Linux (Debian/Ubuntu) - Future implementation:

sudo apt-get install syntaxis

Method 3: Container/Docker

For containerized deployments - Future implementation:

docker pull syntaxis:latest
docker run -p 3000:3000 syntaxis:latest

Method 4: Manual Build from Source

For developers and advanced users:

# Clone repository
git clone https://github.com/syntaxis/syntaxis.git
cd syntaxis

# Build locally
cargo build --release

# Create bundle
nu scripts/provisioning/pack.nu --output dist/

# Install from bundle
nu scripts/provisioning/provctl.nu full-install --bundle dist/*.tar.gz

Creating a Release

Step-by-Step Guide

1. Ensure everything is committed:

   git status  # Should be clean
   

2. Run full test suite:

   cargo test --all
   cargo clippy --all-targets
   cargo fmt --all
   cargo audit
   

3. Update version numbers (if needed):

   • Cargo.toml (workspace)
   • configs/provisioning.toml
   • Documentation if applicable

4. Create and push tag:

   # Semantic versioning: MAJOR.MINOR.PATCH
   git tag v0.2.0
   
   # Push to GitHub (triggers release workflow)
   git push origin v0.2.0
   

5. Wait for GitHub Actions:

   • Go to https://github.com/syntaxis/syntaxis/actions
   • Watch release.yml workflow
   • Builds will run in parallel for all 5 platforms (~10-15 minutes)

6. Check Release:

   • Go to Releases: https://github.com/syntaxis/syntaxis/releases
   • New release v0.2.0 should appear
   • Contains bundles, checksums, and release notes

Installing from Different Sources

From GitHub Release (Online)

# Detect your platform automatically
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/aarch64/aarch64/;s/x86_64/x86_64/')

# Download
VERSION="0.1.0"
BUNDLE="syntaxis-${ARCH}-${OS}-v${VERSION}.tar.gz"
curl -L "https://github.com/syntaxis/syntaxis/releases/download/v${VERSION}/${BUNDLE}" -o /tmp/bundle.tar.gz

# Install
tar -xzf /tmp/bundle.tar.gz -C /tmp
/tmp/syntaxis-*/install.sh --prefix ~/.local

From Local Bundle (Offline)

# Unpack bundle
tar -xzf bundle.tar.gz

# Install with verification
cd syntaxis-v0.1.0-*
./install.sh --verify --prefix ~/.local

# Or use NuShell provisioning commands
provctl full-install --bundle ../../bundle.tar.gz

From Source with Custom Build

# Build for specific target
cargo build --release --target aarch64-apple-darwin

# Create bundle for that target
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin --output dist/

# Share bundle with others
scp dist/syntaxis-v0.1.0-aarch64-darwin.tar.gz user@remote:/tmp/

Bundle Verification

Verify Download Integrity

# Download checksums file
curl -O https://github.com/syntaxis/syntaxis/releases/download/v0.1.0/SHA256SUMS

# Verify bundle
sha256sum -c SHA256SUMS --ignore-missing

# Or with individual checksum
EXPECTED=$(grep 'syntaxis-x86_64-linux' SHA256SUMS | awk '{print $1}')
ACTUAL=$(sha256sum syntaxis-x86_64-linux-v0.1.0.tar.gz | awk '{print $1}')

if [[ "$EXPECTED" == "$ACTUAL" ]]; then
    echo "✅ Integrity verified"
else
    echo "❌ Checksum mismatch - bundle may be corrupted"
fi

Verify Bundle Contents

# Extract and inspect
tar -tzf bundle.tar.gz | head -20

# Check manifest
tar -xzOf bundle.tar.gz syntaxis-v0.1.0-x86_64-linux/manifest.toml

# Dry run installation to see what would be installed
./bundle/install.sh --dry-run

Provisioning Configuration

All provisioning behavior is controlled by configs/provisioning.toml:

Key Sections

[targets]
# Define which platforms to build for
# Example: x86_64-unknown-linux-gnu, aarch64-apple-darwin, etc.

[artifacts]
# What gets included in bundles
binaries = [...]
configs = [...]
docs = [...]

[packaging]
# How to package for each format
tar_gz, zip, deb, rpm

[build]
# Cargo build options
release = true
opt_level = 3
lto = "thin"

Troubleshooting

Release workflow fails

1. Check GitHub Actions logs:

   • Go to https://github.com/syntaxis/syntaxis/actions/workflows/release.yml
   • Click failed run
   • Expand failed job for error details

2. Common issues:

   • "tag already exists" - Delete and recreate: git tag -d v0.1.0 && git push origin :v0.1.0
   • "build failed" - Check local build: cargo build --release
   • "permission denied" - Ensure install.sh is executable: chmod +x scripts/provisioning/install.sh

Installation fails

1. Check bundle integrity:

   ./install.sh --verify --dry-run
   

2. Check write permissions:

   ls -la ~/.local/bin
   ls -la ~/.config/syntaxis
   

3. Check manifest:

   cat ~/.syntaxis/manifest.toml
   

Bundle structure invalid

# Verify bundle structure
tar -tzf bundle.tar.gz | grep -E '(bin|configs|docs|manifest)'

# Should see:
# syntaxis-v0.1.0-x86_64-linux/manifest.toml
# syntaxis-v0.1.0-x86_64-linux/bin/syntaxis-cli
# syntaxis-v0.1.0-x86_64-linux/configs/...
# syntaxis-v0.1.0-x86_64-linux/docs/...

Automation Examples

Example 1: Build Bundle for Distribution

#!/bin/bash
# build-release.sh - Create distribution bundles locally

set -e

VERSION="0.1.0"
OUTPUT_DIR="dist/v${VERSION}"
mkdir -p "$OUTPUT_DIR"

echo "📦 Building distribution bundles..."

# Build for all targets
for target in x86_64-unknown-linux-gnu aarch64-apple-darwin x86_64-apple-darwin x86_64-pc-windows-msvc; do
    echo "  Building: $target"
    nu scripts/provisioning/pack.nu --target "$target" --output "$OUTPUT_DIR" --verify
done

echo ""
echo "✅ Bundles created in: $OUTPUT_DIR"
ls -lh "$OUTPUT_DIR"

Example 2: Distribute to Team

#!/bin/bash
# distribute-to-team.sh - Deploy bundles to team infrastructure

BUNDLE="$1"
SERVERS=("dev-server-1" "dev-server-2" "staging-server")

for server in "${SERVERS[@]}"; do
    echo "🚀 Deploying to: $server"
    scp "$BUNDLE" "deploy@$server:/tmp/"
    ssh "deploy@$server" "
        cd /tmp
        tar -xzf $(basename $BUNDLE)
        ./syntaxis-*/install.sh --force --prefix /opt/syntaxis
    "
done

echo "✅ Deployment complete"

Example 3: Test Installation Locally

#!/bin/bash
# test-install.sh - Test installation in clean environment

BUNDLE="$1"
TEST_DIR="/tmp/syntaxis-test-$$"

mkdir -p "$TEST_DIR"
cd "$TEST_DIR"

echo "🧪 Testing installation: $BUNDLE"
tar -xzf "$BUNDLE"
cd syntaxis-v*

# Test 1: Dry run
echo "  Test 1: Dry run..."
./install.sh --dry-run

# Test 2: Verify checksums
echo "  Test 2: Verify checksums..."
./install.sh --verify --dry-run

# Test 3: Install to test directory
echo "  Test 3: Install to test prefix..."
./install.sh --prefix "$TEST_DIR/install" --unattended --force

# Test 4: Run binaries
echo "  Test 4: Run binaries..."
$TEST_DIR/install/bin/syntaxis-cli --version
$TEST_DIR/install/bin/syntaxis-tui --help || true

echo "✅ All tests passed"
cleanup() { rm -rf "$TEST_DIR"; }
trap cleanup EXIT

Next Steps

Enhance Distribution

• Create Homebrew formula for macOS distribution
• Generate deb/rpm packages for Linux distributions
• Create Docker images for containerized deployment
• Set up artifact repository (artifactory, nexus, etc.)
• Implement auto-update mechanism in binaries
• Create installation wizard (TUI for first-time setup)

Improve CI/CD

• Add code coverage reporting
• Implement semantic versioning auto-bumping
• Add automatic changelog generation
• Set up automated deployments to staging
• Add performance benchmarking
• Implement canary deployments

Expand Documentation

• Create installation video tutorials
• Add troubleshooting guide
• Document configuration examples
• Create case studies
• Build quick-start templates

References

• Provisioning System: See scripts/provisioning/README.md
• Configuration: See configs/provisioning.toml
• Installation Script: See scripts/provisioning/install.sh
• Workflows: See .github/workflows/
• Project Guide: See CLAUDE.md

Support

• 📖 Documentation: https://github.com/syntaxis/syntaxis
• 🐛 Issues: https://github.com/syntaxis/syntaxis/issues
• 💬 Discussions: https://github.com/syntaxis/syntaxis/discussions
• 📧 Email: support@syntaxis.dev

---

Last Updated: 2025-11-17 Status: Complete - Ready for distribution Version: 0.1.0