syntaxis/docs/installation.md

╔═════════════════════════════════╗
║  ┏━┓ ╻ ╻ ┏┓╻ ╺┳╸ ┏━┓ ╻ ╻ ╻ ┏━┓  ║
║  ┗━┓ ┗┳┛ ┃┗┫  ┃  ┣━┫ ┏╋┛ ┃ ┗━┓  ║
║  ┗━┛  ╹  ╹ ╹  ╹  ╹ ╹ ╹ ╹ ╹ ┗━┛  ║
║   ▲ Systematic Orchestration    ║
║   ■  Perfectly Arranged         ║
║          syntaxis.dev           ║
╚═════════════════════════════════╝

Installation Guide

Complete guide for installing syntaxis on any system.

Quick Install (Recommended)

The one-liner installer handles everything:

curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash

Installation time: 15-30 minutes (first-time build takes longest)

What Gets Installed

Binaries (to ~/.cargo/bin)

• workspace - CLI tool for project management
• syntaxis-tui - Terminal user interface
• syntaxis-dashboard - Web dashboard (runs on localhost:3000)

Configurations (to ~/.config/core/)

• syntaxis-api.toml - Main configuration file
• features/*.toml - 11 feature-specific configs:
  • auth.toml (authentication)
  • cache.toml (caching settings)
  • database.toml (database configuration)
  • health.toml (health checks)
  • metrics.toml (monitoring)
  • multi_tenant.toml (multi-tenancy)
  • rate_limit.toml (rate limiting)
  • projects.toml (project management)
  • tasks.toml (task tracking)
  • phases.toml (phase lifecycle)
  • audit.toml (audit trail)

Data Directories

• ~/.local/share/core/ - Runtime data and databases
• ~/.syntaxis/ - Installation tracking manifest

Installation Methods

Method 1: Curl One-Liner (Easiest)

curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash

This is safe because:

1. You can inspect the script first: curl -sSL ... -o install.sh && cat install.sh
2. The script logs all operations to ~/.syntaxis/install.log
3. Failed installations are rolled back automatically

Method 2: Download First, Then Run

# Download the installer
curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh -o install.sh

# Inspect it
less install.sh

# Run it
bash install.sh

Method 3: Clone Repository and Install Manually

For developers or those with specific requirements:

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

# Run the installer from the repo
bash install.sh

# Or use just commands
just build
just install-cli all

Installation Options

Unattended Mode (No Prompts)

bash install.sh --unattended

Uses all defaults without asking for confirmation.

Custom Installation Directory

bash install.sh --prefix /opt/workspace

Installs to a custom location instead of ~/.local/share/core/.

Skip Dependency Installation

bash install.sh --skip-deps

Assumes Rust, NuShell, and Just are already installed. Only builds and installs workspace binaries.

Config Only

bash install.sh --config-only

Only deploys configurations without building binaries. Useful for updating config files.

Dry Run (Preview)

bash install.sh --dry-run

Shows what would be installed without making any actual changes.

Keep Build Artifacts

bash install.sh --keep-build

By default, build artifacts are removed to save disk space. Use this flag to keep them.

Skip Tests

bash install.sh --no-verify

Skips test verification (faster, not recommended for production).

Help

bash install.sh --help

Shows all available options.

Supported Platforms

Operating Systems

• ✅ macOS (Intel and Apple Silicon)
• ✅ Ubuntu/Debian Linux
• ✅ Fedora/RHEL Linux
• ✅ Arch Linux
• ✅ WSL2 (Windows Subsystem for Linux)

Architectures

• ✅ x86_64 (Intel/AMD)
• ✅ aarch64 (ARM64, Apple Silicon)

Rust Versions

• ✅ 1.75+ (Current stable recommended)

Post-Installation

1. Reload Your Shell

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

# For fish
source ~/.config/fish/config.fish

2. Verify Installation

# Test CLI
workspace --help

# Test TUI version
syntaxis-tui --version

# Find dashboard binary
which syntaxis-dashboard

# Check config location
echo $WORKSPACE_CONFIG_DIR

3. Create Your First Project

workspace project create my-first-project

4. Launch the TUI

syntaxis-tui

5. Start the Web Dashboard

cd ~/.local/share/syntaxis
just run-dashboard

Dashboard runs on http://localhost:3000

Customizing Configuration

After installation, configurations are at ~/.config/core/:

# Edit main configuration
nano ~/.config/core/syntaxis-api.toml

# Edit specific feature config
nano ~/.config/core/features/database.toml

# Environment variable overrides
export WORKSPACE_SERVER_PORT=8081
export WORKSPACE_LOG_LEVEL=debug

See docs/configuration.md for all available options.

Troubleshooting

Command Not Found

# Problem: workspace command not found
# Solution 1: Reload shell
source ~/.bashrc

# Solution 2: Check PATH
echo $PATH | grep .cargo/bin

# Solution 3: Check if binary exists
ls -la ~/.cargo/bin/workspace*

Build Failures

# Check if Rust is installed
rustc --version

# Update Rust
rustup update

# Clean and retry
cargo clean
bash install.sh

Missing Dependencies

# For macOS - install Xcode tools
xcode-select --install

# For Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libsqlite3-dev

# For Fedora/RHEL
sudo dnf install -y gcc gcc-c++ make pkg-config sqlite-devel

# For Arch
sudo pacman -S --noconfirm base-devel pkg-config sqlite

Permission Errors

# Installer should NOT require sudo for user installation
# If you see permission errors, check your home directory permissions
ls -ld ~
chmod u+w ~

# Never run installer with sudo!
bash install.sh  # Correct
sudo bash install.sh  # Wrong!

Clean Reinstall

# Remove old installation
rm -rf ~/.cargo/bin/workspace*
rm -rf ~/.config/syntaxis
rm -rf ~/.local/share/syntaxis
rm -rf ~/.syntaxis

# Reinstall
bash install.sh

Installation Log

All installation details are logged to:

~/.syntaxis/install.log

Check this file if installation fails:

tail -100 ~/.syntaxis/install.log

Environment Variables

After installation, these environment variables are set:

# Configuration directory
WORKSPACE_CONFIG_DIR="$HOME/.config/syntaxis"

# Data directory
WORKSPACE_DATA_DIR="$HOME/.local/share/syntaxis"

# Optional: Manual overrides
export WORKSPACE_SERVER_PORT=8080
export WORKSPACE_LOG_LEVEL=debug
export WORKSPACE_DATABASE_PATH="/custom/path.db"

Uninstalling

To uninstall syntaxis:

# Remove binaries
rm ~/.cargo/bin/workspace*

# Remove configurations (optional - keep for reinstall)
rm -rf ~/.config/syntaxis

# Remove data and cache
rm -rf ~/.local/share/syntaxis

# Remove installation tracking
rm -rf ~/.syntaxis

The project repository can be left as-is for future reinstalls.

Development Installation

For contributing to syntaxis:

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

# Install tools
rustup default 1.75
cargo install just

# Build everything
just build

# Run all tests
just test

# Run specific test
cargo test -p syntaxis-core

# Build and run CLI
just run-cli --help

# Build and run TUI
just run-tui

# Build and run dashboard
just run-dashboard

See DEVELOPMENT.md in the root for more development details.

Next Steps

1. Read the Quick Start Guide: docs/installation-guide.md
2. Configure Your System: docs/configuration.md
3. Understand Wrappers: WRAPPER_DESIGN.md
4. Use the CLI: workspace --help
5. Join the Community: https://github.com/core/syntaxis

Getting Help

• GitHub Issues: https://github.com/core/syntaxis/issues
• Documentation: https://github.com/core/syntaxis
• Installation Log: ~/.syntaxis/install.log

---

Happy installing! 🚀