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)
393 lines
8.2 KiB
Markdown
393 lines
8.2 KiB
Markdown
```
|
|
╔═════════════════════════════════╗
|
|
║ ┏━┓ ╻ ╻ ┏┓╻ ╺┳╸ ┏━┓ ╻ ╻ ╻ ┏━┓ ║
|
|
║ ┗━┓ ┗┳┛ ┃┗┫ ┃ ┣━┫ ┏╋┛ ┃ ┗━┓ ║
|
|
║ ┗━┛ ╹ ╹ ╹ ╹ ╹ ╹ ╹ ╹ ╹ ┗━┛ ║
|
|
║ ▲ 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:
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
bash install.sh --unattended
|
|
```
|
|
Uses all defaults without asking for confirmation.
|
|
|
|
### Custom Installation Directory
|
|
```bash
|
|
bash install.sh --prefix /opt/workspace
|
|
```
|
|
Installs to a custom location instead of `~/.local/share/core/`.
|
|
|
|
### Skip Dependency Installation
|
|
```bash
|
|
bash install.sh --skip-deps
|
|
```
|
|
Assumes Rust, NuShell, and Just are already installed. Only builds and installs workspace binaries.
|
|
|
|
### Config Only
|
|
```bash
|
|
bash install.sh --config-only
|
|
```
|
|
Only deploys configurations without building binaries. Useful for updating config files.
|
|
|
|
### Dry Run (Preview)
|
|
```bash
|
|
bash install.sh --dry-run
|
|
```
|
|
Shows what would be installed without making any actual changes.
|
|
|
|
### Keep Build Artifacts
|
|
```bash
|
|
bash install.sh --keep-build
|
|
```
|
|
By default, build artifacts are removed to save disk space. Use this flag to keep them.
|
|
|
|
### Skip Tests
|
|
```bash
|
|
bash install.sh --no-verify
|
|
```
|
|
Skips test verification (faster, not recommended for production).
|
|
|
|
### Help
|
|
```bash
|
|
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
|
|
```bash
|
|
# For bash
|
|
source ~/.bashrc
|
|
|
|
# For zsh
|
|
source ~/.zshrc
|
|
|
|
# For fish
|
|
source ~/.config/fish/config.fish
|
|
```
|
|
|
|
### 2. Verify Installation
|
|
```bash
|
|
# 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
|
|
```bash
|
|
workspace project create my-first-project
|
|
```
|
|
|
|
### 4. Launch the TUI
|
|
```bash
|
|
syntaxis-tui
|
|
```
|
|
|
|
### 5. Start the Web Dashboard
|
|
```bash
|
|
cd ~/.local/share/syntaxis
|
|
just run-dashboard
|
|
```
|
|
Dashboard runs on http://localhost:3000
|
|
|
|
## Customizing Configuration
|
|
|
|
After installation, configurations are at `~/.config/core/`:
|
|
|
|
```bash
|
|
# 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](./docs/configuration.md) for all available options.
|
|
|
|
## Troubleshooting
|
|
|
|
### Command Not Found
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Check if Rust is installed
|
|
rustc --version
|
|
|
|
# Update Rust
|
|
rustup update
|
|
|
|
# Clean and retry
|
|
cargo clean
|
|
bash install.sh
|
|
```
|
|
|
|
### Missing Dependencies
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
~/.syntaxis/install.log
|
|
```
|
|
|
|
Check this file if installation fails:
|
|
```bash
|
|
tail -100 ~/.syntaxis/install.log
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
After installation, these environment variables are set:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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](./DEVELOPMENT.md) in the root for more development details.
|
|
|
|
## Next Steps
|
|
|
|
1. **Read the Quick Start Guide**: [docs/installation-guide.md](./docs/installation-guide.md)
|
|
2. **Configure Your System**: [docs/configuration.md](./docs/configuration.md)
|
|
3. **Understand Wrappers**: [WRAPPER_DESIGN.md](./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! 🚀**
|