jesus/syntaxis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
syntaxis/docs/pack.md
Jesús Pérez 9cef9b8d57 refactor: consolidate configuration directories 
Merge _configs/ into config/ for single configuration directory.
Update all path references.

Changes:
- Move _configs/* to config/
- Update .gitignore for new patterns
- No code references to _configs/ found

Impact: -1 root directory (layout_conventions.md compliance)
2025-12-26 18:36:23 +00:00

9.4 KiB
Raw Permalink Blame History

SYNTAXIS Provisioning System

Complete reference for the SYNTAXIS provisioning and bundling system.

Overview

The provisioning system creates self-contained distribution bundles that users can extract and install without internet or external dependencies.

Key Features:

  • Multi-platform support (Linux, macOS, Windows)
  • Optional orchestration with provision script (install + config)
  • Traditional installers for each step (install.sh, setup-config.sh)
  • SHA256 checksums for integrity verification
  • Manifest metadata for bundle contents

Bundle Structure

Each bundle contains everything needed for installation:

syntaxis-v0.1.0-<target>/
├── README.md              # Bundle overview
├── QUICK_START.md         # 5-minute guide
├── docs/installation.md             # Installation reference
├── provision              # Master provisioner (recommended)
├── install.sh             # Bash installer (optional)
├── install.nu             # NuShell installer (optional)
├── setup-config.sh        # Configuration helper
├── manifest.toml          # Bundle metadata
│
├── bin/                   # Compiled binaries
│   ├── syntaxis-cli
│   ├── syntaxis-tui
│   └── syntaxis-api
│
├── configs/               # Configuration templates
│   ├── database-default.toml
│   ├── database-surrealdb.toml
│   ├── syntaxis-cli.toml
│   └── ... (more configs)
│
└── docs/                  # Additional documentation
    ├── CONFIG.md          # Configuration guide
    └── TROUBLESHOOTING.md # Common issues

Installation Flows

1. Recommended: Master Provisioner (One Command)

./provision full         # Install + configure everything
./provision install      # Just install binaries
./provision config       # Just configure
./provision              # Interactive menu

Advantages:

  • Single command for full setup
  • Interactive menu for guidance
  • Automatic shell detection
  • One-step configuration

2. Traditional: Step-by-Step

# Step 1: Install binaries
bash install.sh --interactive

# Step 2: Configure
bash setup-config.sh --interactive

Advantages:

  • Full control over each step
  • Can skip configuration if desired
  • Traditional installer experience

3. NuShell Users

nu install.nu --prefix ~/.local
nu setup-config.sh --interactive

Advantages:

  • Better compatibility with NuShell shells
  • Exact same functionality as bash

4. Manual

# Copy files manually, set permissions, update PATH
# See docs/installation.md for details

Advantages:

  • Maximum control
  • Works anywhere
  • No dependencies

Provisioning Configuration

The provisioning system is configured in configs/provisioning.toml:

Targets

Defines supported platforms and formats:

[targets.x86_64-unknown-linux-gnu]
enabled = true
os = "linux"
arch = "x86_64"
libc = "glibc"
formats = ["tar.gz", "deb"]

Artifacts

Specifies what goes into bundles:

[artifacts]
binaries = [
    { name = "syntaxis-cli", crate = "cli", description = "..." },
    ...
]

configs = [
    "configs/database-default.toml",
    ...
]

docs = [
    "docs/BUNDLE_README.md",    # Becomes README.md at root
    "docs/docs/installation.md",          # Root level
    "docs/QUICK_START.md",      # Root level
    "docs/CONFIG.md",           # In docs/
    "docs/TROUBLESHOOTING.md",  # In docs/
]

scripts = [
    "scripts/provisioning/provision.sh",     # Master provisioner
    "scripts/provisioning/install.sh",       # Bash installer
    "scripts/provisioning/install.nu",       # NuShell installer
    "scripts/provisioning/setup-config.sh",  # Configuration
]

Pack Workflow

Creating Bundles

# For current platform
nu scripts/provisioning/pack.nu

# For specific target
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu

# Different formats
nu scripts/provisioning/pack.nu --format zip

# Verify after creation
nu scripts/provisioning/pack.nu --verify

# Dry run to preview
nu scripts/provisioning/pack.nu --dry-run

Pack Process

  1. Validate Configuration - Check provisioning.toml
  2. Build Binaries - Compile for target platform
  3. Collect Artifacts - Find all files to bundle
    • Binaries from target/release/
    • Configs from configs/
    • Docs from docs/
    • Scripts from scripts/provisioning/
  4. Create Bundle
    • Create staging directory with structure
    • Copy binaries to bin/
    • Copy configs to configs/ (preserving structure)
    • Copy docs (special placement for README, QUICK_START, INSTALL)
    • Copy scripts to root level (executable)
  5. Generate Manifest - Create manifest.toml with artifact list
  6. Calculate Checksums - SHA256 for all files
  7. Create Archive - tar.gz or zip file
  8. Cleanup - Remove staging directory

Output Files

dist/
├── syntaxis-v0.1.0-aarch64-apple-darwin.tar.gz    # Bundle
├── syntaxis-v0.1.0-aarch64-apple-darwin.checksums.toml  # Checksums

Manifest Format

Each bundle includes manifest.toml with metadata:

[bundle]
version = "0.1.0"
target = "aarch64-apple-darwin"
created_at = "2025-11-17T19:31:23Z"
format = "tar.gz"

[artifacts]
binaries = ["syntaxis-cli", "syntaxis-tui", "syntaxis-api"]
configs = ["database-default.toml", ...]
docs = ["BUNDLE_README.md", "docs/installation.md", ...]
scripts = ["provision.sh", "install.sh", ...]

[checksums]
"bin/syntaxis-cli" = "sha256hash..."
"README.md" = "sha256hash..."
...

Script Descriptions

provision (Master Orchestrator)

Purpose: Coordinate complete installation + configuration

Features:

  • Detects available shells (bash/zsh or NuShell)
  • Offers interactive menu
  • Runs install → configure sequence
  • Handles PATH setup automatically

Usage:

./provision             # Interactive menu
./provision full        # Install + configure (automatic)
./provision install     # Just install
./provision config      # Just configure
./provision help        # Show help

install.sh (Bash Installer)

Purpose: Install binaries to system

Features:

  • Interactive or unattended modes
  • Backup existing binaries
  • Verify checksums
  • Dry-run mode
  • Custom installation prefix

Usage:

bash install.sh --interactive
bash install.sh --prefix ~/.local --dry-run

install.nu (NuShell Installer)

Purpose: Alternative installer for NuShell users

Equivalent to: install.sh but using NuShell

Usage:

nu install.nu --prefix ~/.local

setup-config.sh (Configuration Helper)

Purpose: Create initial TOML configurations

Features:

  • Interactive mode (choose which to configure)
  • Automatic mode (configure all)
  • Sensible defaults
  • Custom config directory

Usage:

bash setup-config.sh --interactive
bash setup-config.sh  # Auto-configure all

Building Bundles

Prerequisites

# Need Rust toolchain
rustup target add x86_64-unknown-linux-gnu aarch64-apple-darwin

# Need NuShell for pack.nu
# See: https://www.nushell.sh/book/installation.html

Build for All Targets

# Single platform (current system)
nu scripts/provisioning/pack.nu

# Linux x86_64
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu

# macOS Apple Silicon
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin

# Windows
nu scripts/provisioning/pack.nu --target x86_64-pc-windows-msvc

Build with Verification

# Include integrity check
nu scripts/provisioning/pack.nu --verify

# Show what would happen
nu scripts/provisioning/pack.nu --dry-run

Distribution

Sharing Bundles

  1. Create bundle with pack.nu
  2. Share these files: 
    syntaxis-v0.1.0-<target>.tar.gz      (Main bundle)
syntaxis-v0.1.0-<target>.checksums.toml  (Optional, for verification)
  3. User extracts and runs ./provision full

Verification

Users can verify bundle integrity:

# Verify all checksums
sha256sum -c syntaxis-v0.1.0-*.checksums.toml

Customization

Changing What's Included

Edit configs/provisioning.toml:

[artifacts]
# Add/remove files here

docs = [
    "docs/your-file.md",    # Included in bundle
]

scripts = [
    "scripts/provisioning/custom.sh",  # Added to bundle
]

Custom Installation Scripts

Replace install.sh or create new ones:

# Edit scripts/provisioning/install.sh
# Update provisioning.toml to reference it

Custom Documentation

Add to docs/ and reference in provisioning.toml.

Troubleshooting

Bundle Creation Fails

# Check config syntax
cat configs/provisioning.toml | nu -c 'open --raw - | from toml'

# Verify files exist
ls docs/BUNDLE_README.md
ls scripts/provisioning/provision.sh

# Check build
cargo build --release

Missing Files in Bundle

# Verify artifact paths in provisioning.toml
# Paths are relative to repository root

# Check pack.nu logic
nu scripts/provisioning/pack.nu --dry-run

Installation Script Fails

# Make scripts executable
chmod +x scripts/provisioning/*.sh

# Test in isolation
bash scripts/provisioning/install.sh --help

Related Documentation

  • README.md - Project overview
  • docs/installation.md - User installation guide
  • CONFIG.md - Configuration reference
  • TROUBLESHOOTING.md - Common user issues

SYNTAXIS v0.1.0 • syntaxis.dev