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)
367 lines
8.1 KiB
Markdown
367 lines
8.1 KiB
Markdown
# syntaxis Provisioning Quick Reference
|
|
|
|
Fast reference for provisioning, distribution, and CI/CD commands.
|
|
|
|
## Local Development
|
|
|
|
### Create Bundle (Current Platform)
|
|
```bash
|
|
nu scripts/provisioning/pack.nu
|
|
# Output: dist/syntaxis-v0.1.0-x86_64-linux.tar.gz
|
|
```
|
|
|
|
### Create Bundle (Specific Platform)
|
|
```bash
|
|
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin --output dist/
|
|
```
|
|
|
|
### List Available Targets
|
|
```bash
|
|
nu scripts/provisioning/pack.nu --list-targets
|
|
```
|
|
|
|
### Dry Run (Preview)
|
|
```bash
|
|
nu scripts/provisioning/pack.nu --dry-run
|
|
```
|
|
|
|
### Install from Bundle (Complete)
|
|
```bash
|
|
nu scripts/provisioning/provctl.nu full-install --bundle bundle.tar.gz
|
|
```
|
|
|
|
### Install Binaries Only
|
|
```bash
|
|
tar -xzf bundle.tar.gz
|
|
cd syntaxis-v0.1.0-*
|
|
nu scripts/provisioning/install.nu --source ./bin --prefix ~/.local
|
|
```
|
|
|
|
### Deploy Configs Only
|
|
```bash
|
|
nu scripts/provisioning/deploy.nu --source ./bundle/configs
|
|
```
|
|
|
|
### Check Installation Status
|
|
```bash
|
|
nu scripts/provisioning/provctl.nu status
|
|
```
|
|
|
|
### Verify Bundle Integrity
|
|
```bash
|
|
nu scripts/provisioning/provctl.nu verify-bundle --bundle bundle.tar.gz
|
|
```
|
|
|
|
## Bash Installer (Offline)
|
|
|
|
For systems without NuShell installed:
|
|
|
|
```bash
|
|
# Extract bundle
|
|
tar -xzf bundle.tar.gz
|
|
|
|
# Interactive installation
|
|
cd syntaxis-v0.1.0-*
|
|
./install.sh
|
|
|
|
# Verify before installing
|
|
./install.sh --verify
|
|
|
|
# Install to custom location
|
|
./install.sh --prefix /opt/syntaxis
|
|
|
|
# Force overwrite without prompts
|
|
./install.sh --force --no-backup
|
|
|
|
# Dry run to preview
|
|
./install.sh --dry-run
|
|
|
|
# Unattended mode
|
|
./install.sh --unattended --prefix ~/.local
|
|
```
|
|
|
|
## GitHub Releases
|
|
|
|
### Create Release (Local)
|
|
```bash
|
|
# 1. Tag your release
|
|
git tag v0.2.0
|
|
git push origin v0.2.0
|
|
|
|
# 2. GitHub Actions automatically:
|
|
# - Builds all 5 platforms
|
|
# - Creates bundles
|
|
# - Generates checksums
|
|
# - Creates GitHub Release
|
|
# - Publishes documentation
|
|
```
|
|
|
|
### Download from Release
|
|
```bash
|
|
# Get latest bundle for your platform
|
|
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/syntaxis-x86_64-linux-v0.1.0.tar.gz -o bundle.tar.gz
|
|
|
|
# Verify checksums
|
|
sha256sum -c SHA256SUMS
|
|
|
|
# Install
|
|
tar -xzf bundle.tar.gz
|
|
cd syntaxis-*
|
|
./install.sh
|
|
```
|
|
|
|
## Provisioning Configuration
|
|
|
|
All behavior is controlled by `configs/provisioning.toml`:
|
|
|
|
### Key Sections
|
|
- `[targets]` - Platforms to build (x86_64-linux, aarch64-macos, etc.)
|
|
- `[artifacts]` - What to include (binaries, configs, docs)
|
|
- `[packaging]` - Format options (tar.gz, zip, deb, rpm)
|
|
- `[build]` - Cargo build options (release, optimization)
|
|
- `[bundle]` - Bundle structure and manifest
|
|
|
|
### Modify Configuration
|
|
```bash
|
|
nano configs/provisioning.toml
|
|
```
|
|
|
|
## Workflows
|
|
|
|
### Build Workflow (On Every Commit)
|
|
- **File**: `.github/workflows/build.yml`
|
|
- **Triggers**: Push to main/develop, all PRs
|
|
- **Jobs**: Format, lint, test, check, audit, builds
|
|
- **Artifacts**: Debug/release binaries (Ubuntu, macOS, Windows)
|
|
|
|
### Release Workflow (On Version Tag)
|
|
- **File**: `.github/workflows/release.yml`
|
|
- **Triggers**: Push tags (v*)
|
|
- **Jobs**: Multi-platform builds, bundle creation, GitHub release
|
|
- **Artifacts**: bundles, checksums, documentation
|
|
|
|
## Utilities
|
|
|
|
### Detect Platform
|
|
```bash
|
|
use scripts/provisioning/common/platform.nu
|
|
|
|
current-target # Get current platform target
|
|
detect-os # Get OS: linux, macos, windows
|
|
detect-arch # Get arch: x86_64, aarch64
|
|
available-targets config # List enabled targets
|
|
```
|
|
|
|
### Manifest Operations
|
|
```bash
|
|
use scripts/provisioning/common/manifest.nu
|
|
|
|
load manifest.toml # Read manifest
|
|
create version target fmt # Create new manifest
|
|
validate manifest # Check manifest validity
|
|
info manifest.toml # Display manifest info
|
|
```
|
|
|
|
### Validation
|
|
```bash
|
|
use scripts/provisioning/common/validate.nu
|
|
|
|
sha256 file # Calculate checksum
|
|
generate-checksums dir # Batch checksums
|
|
verify-checksums file dir # Verify all checksums
|
|
validate-bundle-structure # Check bundle format
|
|
validate-config file # Check provisioning.toml
|
|
```
|
|
|
|
## Manifests
|
|
|
|
### Installation Manifest
|
|
Location: `~/.syntaxis/manifest.toml`
|
|
Created by: `install.nu`
|
|
Contains: Installed binaries, timestamps, installation prefix
|
|
|
|
### Deployment Manifest
|
|
Location: `~/.syntaxis/deployment.toml`
|
|
Created by: `deploy.nu`
|
|
Contains: Deployed configs, timestamps, config directory
|
|
|
|
### Bundle Manifest
|
|
Location: Inside bundle: `manifest.toml`
|
|
Created by: `pack.nu`
|
|
Contains: Bundle metadata, artifact list, checksums
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# Configuration directory
|
|
export SYNTAXIS_CONFIG_DIR=~/.config/syntaxis
|
|
|
|
# Data directory
|
|
export SYNTAXIS_DATA_DIR=~/.local/share/syntaxis
|
|
|
|
# Provisioning config
|
|
export PROVISIONING_CONFIG=configs/provisioning.toml
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
### Build & Test Locally
|
|
```bash
|
|
# 1. Build
|
|
cargo build --release
|
|
|
|
# 2. Create bundle
|
|
nu scripts/provisioning/pack.nu --verify
|
|
|
|
# 3. Test install
|
|
mkdir -p /tmp/test-install
|
|
nu scripts/provisioning/provctl.nu full-install \
|
|
--bundle dist/*.tar.gz \
|
|
--prefix /tmp/test-install
|
|
|
|
# 4. Verify
|
|
/tmp/test-install/bin/syntaxis-cli --version
|
|
```
|
|
|
|
### Prepare Release
|
|
```bash
|
|
# 1. Test all checks
|
|
cargo test --all
|
|
cargo clippy --all-targets
|
|
cargo fmt --all
|
|
cargo audit
|
|
|
|
# 2. Create and push tag
|
|
git tag v0.2.0
|
|
git push origin v0.2.0
|
|
|
|
# 3. Wait for CI/CD to complete
|
|
# 4. Check GitHub Releases page
|
|
```
|
|
|
|
### Install for Development
|
|
```bash
|
|
# Unattended install to ~/.local
|
|
nu scripts/provisioning/provctl.nu full-install \
|
|
--bundle dist/syntaxis-v0.1.0-*.tar.gz \
|
|
--prefix ~/.local \
|
|
--verify
|
|
|
|
# Add to PATH
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
|
|
# Verify
|
|
syntaxis-cli --version
|
|
```
|
|
|
|
### Upgrade Existing Installation
|
|
```bash
|
|
# Download new bundle
|
|
curl -O https://github.com/syntaxis/syntaxis/releases/download/v0.2.0/bundle.tar.gz
|
|
|
|
# Install with backup
|
|
nu scripts/provisioning/provctl.nu full-install --bundle bundle.tar.gz
|
|
|
|
# Verify new version
|
|
syntaxis-cli --version
|
|
```
|
|
|
|
### Deploy to Multiple Machines
|
|
```bash
|
|
#!/bin/bash
|
|
# distribute.sh
|
|
|
|
BUNDLE="$1"
|
|
SERVERS=("server1" "server2" "server3")
|
|
|
|
for server in "${SERVERS[@]}"; do
|
|
echo "Deploying to: $server"
|
|
scp "$BUNDLE" "user@$server:/tmp/"
|
|
ssh "user@$server" "
|
|
cd /tmp
|
|
tar -xzf $(basename $BUNDLE)
|
|
./syntaxis-*/install.sh --unattended
|
|
"
|
|
done
|
|
```
|
|
|
|
## Scripts Location
|
|
|
|
```
|
|
scripts/provisioning/
|
|
├── pack.nu # Create bundles
|
|
├── unpack.nu # Extract bundles
|
|
├── install.nu # Install binaries
|
|
├── deploy.nu # Deploy configs
|
|
├── provctl.nu # Orchestrator
|
|
├── install.sh # Bash offline installer
|
|
├── common/
|
|
│ ├── platform.nu # Platform detection
|
|
│ ├── manifest.nu # Manifest handling
|
|
│ └── validate.nu # Integrity checking
|
|
└── README.md # Full documentation
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Bundle creation fails
|
|
```bash
|
|
# Check if binaries are built
|
|
ls target/release/syntaxis-*
|
|
|
|
# Run build first if needed
|
|
cargo build --release
|
|
|
|
# Try with dry-run
|
|
nu scripts/provisioning/pack.nu --dry-run
|
|
```
|
|
|
|
### Installation fails
|
|
```bash
|
|
# Check permissions
|
|
ls -la ~/.local/bin
|
|
ls -la ~/.config/syntaxis
|
|
|
|
# Try with sudo (not recommended)
|
|
# Or install to different prefix
|
|
./install.sh --prefix ~/local-install
|
|
|
|
# Check manifest
|
|
cat ~/.syntaxis/manifest.toml
|
|
```
|
|
|
|
### Checksum mismatch
|
|
```bash
|
|
# Download new checksums
|
|
curl -O https://github.com/.../SHA256SUMS
|
|
|
|
# Verify again
|
|
sha256sum -c SHA256SUMS --ignore-missing
|
|
|
|
# If still fails, bundle may be corrupted
|
|
rm bundle.tar.gz && wget ... # re-download
|
|
```
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `configs/provisioning.toml` | Provisioning configuration |
|
|
| `scripts/provisioning/` | Provisioning scripts (pack, install, etc) |
|
|
| `.github/workflows/build.yml` | Continuous integration |
|
|
| `.github/workflows/release.yml` | Release automation |
|
|
| `docs/provisioning.md` | Complete provisioning guide |
|
|
| `scripts/provisioning/README.md` | Detailed provisioning docs |
|
|
|
|
## Documentation
|
|
|
|
- **Full Guide**: See `docs/provisioning.md`
|
|
- **Provisioning System**: See `scripts/provisioning/README.md`
|
|
- **Project Guide**: See `CLAUDE.md`
|
|
- **Quick Start**: See `README.md`
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-11-17
|
|
**Version**: 0.1.0
|