9cef9b8d57
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)
508 lines
10 KiB
Markdown
508 lines
10 KiB
Markdown
# Installation Guide
|
|
|
|
Complete reference for extracting and installing SYNTAXIS from the bundle.
|
|
|
|
## Overview
|
|
|
|
This guide covers:
|
|
1. **Quick overview** (3 steps)
|
|
2. **Prerequisites** (system requirements)
|
|
3. **Installation methods** (automatic, manual, NuShell)
|
|
4. **Verification** (checking successful installation)
|
|
5. **Troubleshooting** (common issues)
|
|
|
|
## 🚀 Quick Start (4 Steps)
|
|
|
|
```bash
|
|
# Step 1: Extract bundle
|
|
tar -xzf syntaxis-v0.1.0-*.tar.gz
|
|
cd syntaxis-v0.1.0-*
|
|
|
|
# Step 2: Install binaries
|
|
bash install.sh --interactive
|
|
|
|
# Step 3: Configure settings
|
|
bash setup-config.sh --interactive
|
|
|
|
# Step 4: Verify
|
|
syntaxis-cli --version
|
|
```
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
|
|
- **Memory**: 512 MB minimum (1 GB recommended for full stack)
|
|
- **Disk Space**: 100 MB for binaries + data
|
|
- **Network**: Optional (offline operation supported)
|
|
|
|
### Supported Platforms
|
|
|
|
| Platform | Architecture | Status |
|
|
|----------|--------------|--------|
|
|
| Linux (glibc) | x86_64, ARM64 | ✅ Tested |
|
|
| macOS | Intel (x86_64), Apple Silicon (ARM64) | ✅ Tested |
|
|
| Windows | x86_64 (MSVC) | ✅ Tested |
|
|
|
|
### Required Tools
|
|
|
|
The bundle is **self-contained**—no additional tools required!
|
|
|
|
Optional tools (for advanced setup):
|
|
- `bash` or `zsh` (for `install.sh`) - available on all systems
|
|
- `nu` (for `install.nu`) - [install NuShell](https://www.nushell.sh)
|
|
|
|
---
|
|
|
|
## Installation Methods
|
|
|
|
### Recommended: Two-Step Installation
|
|
|
|
The cleanest approach: separate install and config steps.
|
|
|
|
**Step 1: Install binaries**
|
|
```bash
|
|
# Interactive (prompts for options)
|
|
bash install.sh --interactive
|
|
|
|
# Unattended (uses defaults)
|
|
bash install.sh --prefix ~/.local
|
|
|
|
# Verify before installing
|
|
bash install.sh --prefix ~/.local --dry-run
|
|
|
|
# Custom prefix
|
|
bash install.sh --prefix /opt/syntaxis
|
|
```
|
|
|
|
**Step 2: Configure**
|
|
```bash
|
|
bash setup-config.sh --interactive
|
|
```
|
|
|
|
### Alternative: NuShell Installer
|
|
|
|
For NuShell users who prefer the alternative:
|
|
|
|
```bash
|
|
# Make sure NuShell is installed first
|
|
# See: https://www.nushell.sh/book/installation.html
|
|
|
|
# Step 1: Install using NuShell
|
|
nu install.nu --prefix ~/.local
|
|
|
|
# Step 2: Configure
|
|
bash setup-config.sh --interactive
|
|
```
|
|
|
|
### Advanced: Manual Installation
|
|
|
|
For maximum control and custom setups:
|
|
|
|
```bash
|
|
# Create installation directory
|
|
mkdir -p ~/.local/bin
|
|
|
|
# Copy binaries
|
|
cp bin/* ~/.local/bin/
|
|
|
|
# Make executable
|
|
chmod +x ~/.local/bin/syntaxis-*
|
|
|
|
# Create config directory
|
|
mkdir -p ~/.config/syntaxis
|
|
|
|
# Copy configs
|
|
cp configs/*.toml ~/.config/syntaxis/
|
|
|
|
# Create data directory
|
|
mkdir -p ~/.local/share/syntaxis
|
|
|
|
# Update PATH (one-time)
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
---
|
|
|
|
## Step-by-Step Installation
|
|
|
|
### 1. Extract Bundle
|
|
|
|
```bash
|
|
# Using tar (Linux, macOS)
|
|
tar -xzf syntaxis-v0.1.0-*.tar.gz
|
|
cd syntaxis-v0.1.0-*
|
|
|
|
# Using unzip (Windows, macOS)
|
|
unzip syntaxis-v0.1.0-*.zip
|
|
cd syntaxis-v0.1.0-*
|
|
```
|
|
|
|
### 2. Install Binaries
|
|
|
|
```bash
|
|
bash install.sh --interactive
|
|
```
|
|
|
|
This installs the binaries and updates your PATH automatically.
|
|
|
|
### 3. Configure Settings
|
|
|
|
```bash
|
|
bash setup-config.sh --interactive
|
|
```
|
|
|
|
This creates configuration files and prompts for customization.
|
|
|
|
### 4. Configure Shell
|
|
|
|
After installation, update your shell configuration to add syntaxis to PATH:
|
|
|
|
**For bash/zsh:**
|
|
```bash
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
**For fish:**
|
|
```bash
|
|
set -Ua fish_user_paths ~/.local/bin
|
|
```
|
|
|
|
**For NuShell:**
|
|
```bash
|
|
export PATH="($env.HOME)/.local/bin:($env.PATH)"
|
|
```
|
|
|
|
### 5. Verify Installation
|
|
|
|
```bash
|
|
# Check all binaries
|
|
syntaxis-cli --version
|
|
syntaxis-tui --version
|
|
syntaxis-api --version
|
|
|
|
# Should show: syntaxis-* v0.1.0
|
|
|
|
# List configuration
|
|
ls ~/.config/syntaxis/
|
|
```
|
|
|
|
---
|
|
|
|
## NuShell: Full-Featured Wrappers (Optional)
|
|
|
|
### What is NuShell?
|
|
|
|
NuShell is a modern shell that provides advanced features for SYNTAXIS wrappers:
|
|
- Better config discovery with multiple fallback paths
|
|
- Advanced environment variable handling
|
|
- Full-featured configuration injection
|
|
|
|
### Do I Need NuShell?
|
|
|
|
**Short Answer**: No, SYNTAXIS works without it.
|
|
|
|
**With NuShell** (Recommended):
|
|
- ✅ Full-featured wrappers
|
|
- ✅ Advanced config discovery
|
|
- ✅ Best user experience
|
|
|
|
**Without NuShell** (Still Works):
|
|
- ✅ Simplified auto-config (basic paths only)
|
|
- ✅ Still auto-injects config path
|
|
- ✅ Good enough for most users
|
|
|
|
### Installing NuShell
|
|
|
|
The installer will detect if NuShell is installed and prompt you with options:
|
|
|
|
```
|
|
⚠️ NuShell Not Detected
|
|
Continue with simplified wrappers? [Y/n/i]
|
|
Y = Yes, continue (recommended)
|
|
N = No, let me install NuShell first
|
|
i = Show installation guide
|
|
```
|
|
|
|
**Installation Instructions** (by OS):
|
|
|
|
**macOS (Homebrew)**:
|
|
```bash
|
|
brew install nushell
|
|
```
|
|
|
|
**macOS (Cargo)**:
|
|
```bash
|
|
cargo install nu
|
|
```
|
|
|
|
**Linux (Arch)**:
|
|
```bash
|
|
pacman -S nushell
|
|
```
|
|
|
|
**Linux (Ubuntu/Debian)**:
|
|
```bash
|
|
cargo install nu
|
|
```
|
|
|
|
**Linux (Fedora)**:
|
|
```bash
|
|
dnf install nushell
|
|
```
|
|
|
|
**Windows (WinGet)**:
|
|
```bash
|
|
winget install nushell
|
|
```
|
|
|
|
**Windows (Cargo)**:
|
|
```bash
|
|
cargo install nu
|
|
```
|
|
|
|
### Using Wrappers Without NuShell
|
|
|
|
If you choose to continue without NuShell:
|
|
- Wrappers still auto-discover and inject config paths
|
|
- Basic config discovery works (~6 paths searched)
|
|
- Command execution is normal and transparent
|
|
|
|
To upgrade later, simply install NuShell:
|
|
```bash
|
|
# Install NuShell (see above for your OS)
|
|
# Then re-run the installer
|
|
./install.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Setup
|
|
|
|
### Essential Environment Variables
|
|
|
|
Set these in your shell rc file:
|
|
|
|
```bash
|
|
# Configuration directory
|
|
export SYNTAXIS_CONFIG_DIR="$HOME/.config/syntaxis"
|
|
|
|
# Data directory
|
|
export SYNTAXIS_DATA_DIR="$HOME/.local/share/syntaxis"
|
|
|
|
# Database backend (optional)
|
|
export SYNTAXIS_DATABASE="default" # or "surrealdb"
|
|
```
|
|
|
|
### Optional Configuration
|
|
|
|
```bash
|
|
# Logging level
|
|
export RUST_LOG="info" # debug, info, warn, error
|
|
|
|
# API server settings
|
|
export SYNTAXIS_API_PORT=3000
|
|
export SYNTAXIS_API_HOST=127.0.0.1
|
|
```
|
|
|
|
---
|
|
|
|
## Post-Installation Configuration
|
|
|
|
### Interactive Configuration
|
|
|
|
```bash
|
|
# Run interactive configuration (done in step 3)
|
|
bash setup-config.sh --interactive
|
|
```
|
|
|
|
### Manual Configuration
|
|
|
|
Default configs are created automatically. Customize them:
|
|
|
|
```bash
|
|
# Edit CLI configuration
|
|
nano ~/.config/syntaxis/syntaxis-cli.toml
|
|
|
|
# Edit TUI configuration
|
|
nano ~/.config/syntaxis/syntaxis-tui.toml
|
|
|
|
# Edit API configuration
|
|
nano ~/.config/syntaxis/syntaxis-api.toml
|
|
```
|
|
|
|
See [CONFIG.md](CONFIG.md) for all configuration options.
|
|
|
|
---
|
|
|
|
## Bundle Contents Reference
|
|
|
|
```
|
|
syntaxis-v0.1.0-<target>/
|
|
├── Binaries (ready to run)
|
|
│ └── bin/
|
|
│ ├── syntaxis-cli # Command-line interface
|
|
│ ├── syntaxis-tui # Terminal user interface
|
|
│ └── syntaxis-api # REST API server
|
|
│
|
|
├── Installation Scripts
|
|
│ ├── install.sh # Bash installer (Step 1: Install binaries)
|
|
│ ├── install.nu # NuShell installer (alternative)
|
|
│ └── setup-config.sh # Configuration helper (Step 2: Configure)
|
|
│
|
|
├── Configurations
|
|
│ └── configs/
|
|
│ ├── database-default.toml # SQLite settings
|
|
│ ├── database-surrealdb.toml # SurrealDB settings
|
|
│ ├── syntaxis-cli.toml # CLI config
|
|
│ ├── syntaxis-tui.toml # TUI config
|
|
│ └── syntaxis-api.toml # API config
|
|
│
|
|
├── Documentation
|
|
│ ├── README.md # Overview (this directory)
|
|
│ ├── QUICK_START.md # 5-minute tutorial
|
|
│ ├── docs/installation.md # Installation (this file)
|
|
│ ├── CONFIG.md # Configuration reference
|
|
│ └── TROUBLESHOOTING.md # Common issues
|
|
│
|
|
└── Metadata
|
|
├── manifest.toml # Bundle inventory
|
|
└── .checksums.toml # SHA256 checksums
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### Verify Binaries
|
|
|
|
```bash
|
|
# Check all binaries are executable
|
|
which syntaxis-cli
|
|
which syntaxis-tui
|
|
which syntaxis-api
|
|
|
|
# Test basic commands
|
|
syntaxis-cli --help
|
|
syntaxis-cli --version
|
|
```
|
|
|
|
### Verify Configuration
|
|
|
|
```bash
|
|
# Check config directory
|
|
ls -la ~/.config/syntaxis/
|
|
|
|
# Validate TOML files
|
|
cat ~/.config/syntaxis/syntaxis-cli.toml | head -10
|
|
```
|
|
|
|
### Verify Data Directory
|
|
|
|
```bash
|
|
# Check data directory exists
|
|
ls -la ~/.local/share/syntaxis/
|
|
|
|
# Create sample database
|
|
syntaxis-cli project list
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting Installation
|
|
|
|
### "Command not found"
|
|
|
|
```bash
|
|
# Check if in PATH
|
|
echo $PATH | grep .local/bin
|
|
|
|
# Add to PATH
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
### "Permission denied"
|
|
|
|
```bash
|
|
# Make binaries executable
|
|
chmod +x ~/.local/bin/syntaxis-*
|
|
|
|
# Verify permissions
|
|
ls -l ~/.local/bin/syntaxis-*
|
|
```
|
|
|
|
### Installer script fails
|
|
|
|
```bash
|
|
# Run with verbose output
|
|
bash install.sh --verbose --prefix ~/.local
|
|
|
|
# Check if directories exist
|
|
mkdir -p ~/.local/bin
|
|
mkdir -p ~/.config/syntaxis
|
|
mkdir -p ~/.local/share/syntaxis
|
|
```
|
|
|
|
### Configuration not found
|
|
|
|
```bash
|
|
# Create missing directory
|
|
mkdir -p ~/.config/syntaxis
|
|
|
|
# Run setup script
|
|
bash setup-config.sh
|
|
|
|
# Copy from bundle
|
|
cp configs/*.toml ~/.config/syntaxis/
|
|
```
|
|
|
|
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for more help.
|
|
|
|
---
|
|
|
|
## Uninstallation
|
|
|
|
To remove SYNTAXIS:
|
|
|
|
```bash
|
|
# Remove binaries
|
|
rm ~/.local/bin/syntaxis-*
|
|
|
|
# Remove configuration (optional)
|
|
rm -rf ~/.config/syntaxis/
|
|
|
|
# Remove data (optional)
|
|
rm -rf ~/.local/share/syntaxis/
|
|
|
|
# Clean up PATH (edit ~/.bashrc or equivalent)
|
|
# Remove the SYNTAXIS-related export statement
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Quick Start**: Read [QUICK_START.md](QUICK_START.md) (5 minutes)
|
|
2. **Configure**: Read [CONFIG.md](CONFIG.md) for all options
|
|
3. **Create Project**: Use `syntaxis-cli` or `syntaxis-tui`
|
|
4. **Run API**: Start server with `syntaxis-api`
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
- **Local Issues**: Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
- **Configuration**: See [CONFIG.md](CONFIG.md)
|
|
- **Quick Examples**: See [QUICK_START.md](QUICK_START.md)
|
|
- **Online Help**: https://doc.syntaxis.dev
|
|
- **Report Issues**: https://github.com/syntaxis/syntaxis/issues
|
|
|
|
---
|
|
|
|
**SYNTAXIS** v0.1.0 • [syntaxis.dev](https://syntaxis.dev)
|