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)
260 lines
6.4 KiB
Markdown
260 lines
6.4 KiB
Markdown
# Installation Guide
|
|
|
|
Complete guide to installing syntaxis binaries, configurations, and wrappers.
|
|
|
|
## Quick Start
|
|
|
|
Install all binaries with one command:
|
|
|
|
```bash
|
|
just scripts-install all
|
|
```
|
|
|
|
This command:
|
|
1. Compiles all binaries (workspace, syntaxis-tui, syntaxis-dashboard)
|
|
2. Installs them to `~/.cargo/bin/`
|
|
3. Deploys configuration files to `~/.config/core/`
|
|
4. Creates intelligent wrapper scripts that auto-discover configurations
|
|
5. Registers installation details in `.syntaxis/manifest.toml`
|
|
|
|
## Installation Commands
|
|
|
|
### Install All Binaries
|
|
```bash
|
|
just scripts-install all
|
|
```
|
|
Installs workspace, syntaxis-tui, and syntaxis-dashboard with configurations.
|
|
|
|
### Install Specific Binary
|
|
```bash
|
|
just scripts-install workspace # Install CLI only
|
|
just scripts-install syntaxis-tui # Install TUI only
|
|
just scripts-install syntaxis-dashboard # Install web dashboard
|
|
```
|
|
|
|
### Keep Build Artifacts
|
|
```bash
|
|
just scripts-install all --keep-target
|
|
```
|
|
By default, build artifacts are removed to save disk space. Use `--keep-target` to keep them.
|
|
|
|
### Check Installation Status
|
|
```bash
|
|
just scripts-install status
|
|
```
|
|
Shows which binaries are installed and their locations.
|
|
|
|
### List Available Binaries
|
|
```bash
|
|
just scripts-install list
|
|
```
|
|
Lists all available binaries with descriptions.
|
|
|
|
## What Gets Installed
|
|
|
|
### Binaries
|
|
| Binary | Type | Location | Purpose |
|
|
|--------|------|----------|---------|
|
|
| `workspace` | CLI | `~/.cargo/bin/workspace` | Project management command-line tool |
|
|
| `syntaxis-tui` | TUI | `~/.cargo/bin/syntaxis-tui` | Interactive terminal user interface |
|
|
| `syntaxis-dashboard` | Web | `~/.cargo/bin/syntaxis-dashboard` | Web-based dashboard (Leptos, port 3000) |
|
|
|
|
### Configuration Files
|
|
Location: `~/.config/core/`
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `syntaxis-api.toml` | Main configuration for workspace ecosystem |
|
|
| `features/auth.toml` | Authentication configuration |
|
|
| `features/cache.toml` | Caching configuration |
|
|
| `features/database.toml` | Database configuration |
|
|
| `features/health.toml` | Health check configuration |
|
|
| `features/metrics.toml` | Metrics collection configuration |
|
|
| `features/multi_tenant.toml` | Multi-tenancy configuration |
|
|
| `features/rate_limit.toml` | Rate limiting configuration |
|
|
| `features/projects.toml` | Project management settings |
|
|
| `features/tasks.toml` | Task tracking settings |
|
|
| `features/phases.toml` | Phase lifecycle settings |
|
|
| `features/audit.toml` | Audit trail configuration |
|
|
|
|
### Data Directories
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `~/.local/share/core/` | Runtime data and databases |
|
|
| `.syntaxis/` | Local installation tracking manifest |
|
|
|
|
## How Wrapper Scripts Work
|
|
|
|
After installation, wrapper scripts in `~/.cargo/bin/` automatically:
|
|
|
|
1. **Search for configuration files** in this priority order:
|
|
- `~/.config/core/{binary}.toml`
|
|
- `~/.config/core/syntaxis-api.toml`
|
|
- `.project/{binary}.toml` (project-specific)
|
|
- `.vapora/{binary}.toml` (VAPORA-specific)
|
|
|
|
2. **Set environment variables**:
|
|
- `WORKSPACE_CONFIG_PATH` - Found configuration file
|
|
- `WORKSPACE_CONFIG_DIR` - Configuration directory
|
|
- `WORKSPACE_DATA_DIR` - Runtime data directory
|
|
|
|
3. **Create data directory** if needed
|
|
4. **Execute the actual binary** with all arguments passed through
|
|
|
|
### Example: Running workspace CLI
|
|
```bash
|
|
$ workspace --help
|
|
# Wrapper script automatically:
|
|
# 1. Finds ~/.config/core/workspace.toml
|
|
# 2. Sets WORKSPACE_CONFIG_PATH
|
|
# 3. Executes ~/.cargo/bin/workspace.real --help
|
|
```
|
|
|
|
## Installation Structure
|
|
|
|
### Before Installation
|
|
```
|
|
~/.cargo/bin/
|
|
(other cargo binaries)
|
|
```
|
|
|
|
### After Installation
|
|
```
|
|
~/.cargo/bin/
|
|
workspace (wrapper script)
|
|
workspace.real (actual binary)
|
|
syntaxis-tui (wrapper script)
|
|
syntaxis-tui.real (actual binary)
|
|
syntaxis-dashboard (actual binary)
|
|
(other cargo binaries)
|
|
|
|
~/.config/core/
|
|
syntaxis-api.toml (main config)
|
|
features/
|
|
auth.toml
|
|
cache.toml
|
|
database.toml
|
|
health.toml
|
|
metrics.toml
|
|
multi_tenant.toml
|
|
rate_limit.toml
|
|
projects.toml
|
|
tasks.toml
|
|
phases.toml
|
|
audit.toml
|
|
|
|
~/.local/share/core/
|
|
(runtime data)
|
|
|
|
.syntaxis/
|
|
manifest.toml (installation tracking)
|
|
```
|
|
|
|
## Installation Manifest
|
|
|
|
After installation, `.syntaxis/manifest.toml` tracks:
|
|
|
|
```toml
|
|
[installation]
|
|
created_at = "2025-11-15 12:34:56"
|
|
last_updated = "2025-11-15 12:34:56"
|
|
installation_root = "/path/to/syntaxis"
|
|
ecosystem_version = "0.1.0"
|
|
|
|
[binaries.workspace]
|
|
installed = true
|
|
wrapper = true
|
|
path = "~/.cargo/bin/workspace"
|
|
real_binary = "~/.cargo/bin/workspace.real"
|
|
version = "0.1.0"
|
|
installed_at = "2025-11-15 12:34:56"
|
|
|
|
[configurations]
|
|
config_dir = "~/.config/syntaxis"
|
|
deployed_count = 11
|
|
|
|
[configurations.syntaxis-api]
|
|
deployed = true
|
|
path = "~/.config/core/syntaxis-api.toml"
|
|
checksum = "sha256:..."
|
|
deployed_at = "2025-11-15 12:34:56"
|
|
|
|
[verification]
|
|
all_binaries_present = true
|
|
all_configs_deployed = true
|
|
wrappers_created = true
|
|
environment_variables_set = true
|
|
```
|
|
|
|
This manifest enables:
|
|
- **Version tracking** - Know when each component was installed
|
|
- **Integrity verification** - Check config file integrity via checksums
|
|
- **Installation status** - Verify all components are properly deployed
|
|
- **Rollback capability** - Reference for reverting to previous versions
|
|
|
|
## Troubleshooting
|
|
|
|
### Binary not found
|
|
```bash
|
|
# Ensure ~/.cargo/bin is in PATH
|
|
echo $PATH | grep ".cargo/bin"
|
|
|
|
# If not found, add to shell profile:
|
|
export PATH="$HOME/.cargo/bin:$PATH"
|
|
```
|
|
|
|
### Config files not loading
|
|
```bash
|
|
# Check if wrapper script is finding config
|
|
workspace --help # Should show config path in output
|
|
|
|
# Verify config directory exists
|
|
ls -la ~/.config/core/
|
|
```
|
|
|
|
### Reinstalling
|
|
To reinstall with fresh configurations:
|
|
```bash
|
|
# Remove old installation
|
|
rm -rf ~/.config/syntaxis
|
|
rm ~/.cargo/bin/workspace*
|
|
rm ~/.cargo/bin/syntaxis-tui*
|
|
|
|
# Reinstall
|
|
just scripts-install all
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Check installation status**:
|
|
```bash
|
|
just scripts-install status
|
|
```
|
|
|
|
2. **Read configuration guide**:
|
|
```bash
|
|
cat docs/configuration.md
|
|
```
|
|
|
|
3. **Use the CLI**:
|
|
```bash
|
|
workspace --help
|
|
workspace project list
|
|
```
|
|
|
|
4. **Launch the TUI**:
|
|
```bash
|
|
syntaxis-tui
|
|
```
|
|
|
|
5. **Start the web dashboard**:
|
|
```bash
|
|
syntaxis-dashboard # Runs on http://localhost:3000
|
|
```
|
|
|
|
## Support
|
|
|
|
- **Bug reports**: See `.coder/` directory for issue tracking
|
|
- **Configuration help**: See `docs/configuration.md`
|
|
- **Technical details**: See `WRAPPER_DESIGN.md`
|