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)
546 lines
14 KiB
Markdown
546 lines
14 KiB
Markdown
# Installation System Overview & Summary
|
||
|
||
**Quick Answer to:** "How we install targets with configs and wrappers?"
|
||
|
||
---
|
||
|
||
## TL;DR (Too Long; Didn't Read)
|
||
|
||
**Your Question:** "How we install targets with configs and wrappers?"
|
||
|
||
**Answer:**
|
||
Currently, syntaxis binaries install without their configurations. We need to:
|
||
1. Deploy configuration templates during installation
|
||
2. Create wrapper scripts to manage environment setup
|
||
3. Track installations in a manifest
|
||
|
||
This enables a seamless experience: **One command to install, binaries just work.**
|
||
|
||
---
|
||
|
||
## What This Is About
|
||
|
||
### Problem
|
||
```
|
||
Current state:
|
||
$ just scripts-install
|
||
✅ Binaries installed
|
||
|
||
$ syntaxis-api
|
||
❌ Error: Config not found
|
||
|
||
User must manually:
|
||
1. Find config templates
|
||
2. Copy them to correct location
|
||
3. Edit configurations
|
||
4. Set environment variables
|
||
5. Run binary
|
||
```
|
||
|
||
### Solution
|
||
```
|
||
After implementation:
|
||
$ just scripts-install
|
||
✅ Binaries installed
|
||
✅ Configs deployed
|
||
✅ Wrappers created
|
||
✅ Manifest tracked
|
||
|
||
$ syntaxis-api
|
||
✅ Config found automatically
|
||
✅ Environment setup automatically
|
||
✅ Server running
|
||
|
||
Result: One command. Everything works.
|
||
```
|
||
|
||
---
|
||
|
||
## What We're Delivering
|
||
|
||
### 4 Phases (6-8 weeks total)
|
||
|
||
#### Phase 1: Configuration Deployment (1-2 weeks) ⭐ START HERE
|
||
- Rename config templates (syntaxis-api → syntaxis-api)
|
||
- Create workspace-specific feature templates (projects, tasks, phases, audit)
|
||
- Deploy configs during installation
|
||
- Create installation guide
|
||
|
||
**Status:** Ready to implement - see PHASE_1_IMPLEMENTATION.md
|
||
|
||
#### Phase 2: Wrapper Scripts (1-2 weeks)
|
||
- Create wrapper scripts that find configs
|
||
- Setup environment variables automatically
|
||
- Validate configurations
|
||
|
||
#### Phase 3: Manifest Enhancement (1 week)
|
||
- Track installed configurations
|
||
- Version management
|
||
- Rollback capability
|
||
|
||
#### Phase 4: Documentation & Testing (1 week)
|
||
- Complete guides
|
||
- Integration tests
|
||
- Troubleshooting
|
||
|
||
---
|
||
|
||
## Key Components
|
||
|
||
### 1. Configuration Templates
|
||
```
|
||
syntaxis/
|
||
├── syntaxis-api-config.template.toml ✅ Main config
|
||
└── configs/features/
|
||
├── auth.toml.template ✅ Existing
|
||
├── database.toml.template ✅ Existing
|
||
├── cache.toml.template ✅ Existing
|
||
├── health.toml.template ✅ Existing
|
||
├── metrics.toml.template ✅ Existing
|
||
├── multi_tenant.toml.template ✅ Existing
|
||
├── rate_limit.toml.template ✅ Existing
|
||
├── projects.toml.template ✨ NEW (Phase 1)
|
||
├── tasks.toml.template ✨ NEW (Phase 1)
|
||
├── phases.toml.template ✨ NEW (Phase 1)
|
||
└── audit.toml.template ✨ NEW (Phase 1)
|
||
```
|
||
|
||
### 2. Installation Infrastructure
|
||
```
|
||
scripts/
|
||
├── install-cli.nu ✅ Existing (needs config deployment)
|
||
├── manifest.nu ✅ Existing (tracks installations)
|
||
└── common/find-config.nu ✅ Existing (discovers configs)
|
||
```
|
||
|
||
### 3. Configuration Locations
|
||
```
|
||
~/.config/core/ ← Where configs end up after install
|
||
├── syntaxis-api.toml
|
||
└── features/
|
||
├── auth.toml
|
||
├── database.toml
|
||
├── projects.toml ← NEW
|
||
├── tasks.toml ← NEW
|
||
├── phases.toml ← NEW
|
||
└── audit.toml ← NEW
|
||
|
||
.syntaxis/ ← Where manifest lives
|
||
└── manifest.toml ← Tracks what's installed
|
||
```
|
||
|
||
### 4. Wrapper Scripts (Phase 2+)
|
||
```
|
||
~/.cargo/bin/
|
||
├── workspace ← Wrapper script (finds config, sets env)
|
||
├── workspace.real ← Actual binary
|
||
├── syntaxis-tui ← Wrapper script
|
||
├── syntaxis-tui.real ← Actual binary
|
||
├── syntaxis-api ← Wrapper script
|
||
└── syntaxis-api.real ← Actual binary
|
||
```
|
||
|
||
---
|
||
|
||
## Installation Flow
|
||
|
||
### Before (Current)
|
||
```
|
||
User: just scripts-install
|
||
→ Compiles workspace
|
||
→ Installs binaries to ~/.cargo/bin/
|
||
→ That's it!
|
||
|
||
Result: Binaries installed, configs nowhere, doesn't work
|
||
```
|
||
|
||
### After Phase 1 (Configuration Deployment)
|
||
```
|
||
User: just scripts-install
|
||
→ Compiles workspace
|
||
→ Installs binaries to ~/.cargo/bin/
|
||
→ Copies config templates to ~/.config/core/
|
||
→ Creates manifest tracking
|
||
|
||
Result: Binaries + configs installed, still doesn't run (needs wrapper)
|
||
```
|
||
|
||
### After Phase 2 (Wrapper Scripts)
|
||
```
|
||
User: just scripts-install
|
||
→ Compiles workspace
|
||
→ Installs binaries to ~/.cargo/bin/
|
||
→ Copies config templates to ~/.config/core/
|
||
→ Creates wrapper scripts
|
||
→ Creates manifest tracking
|
||
|
||
Result: One command. Binaries work. Configs found automatically.
|
||
```
|
||
|
||
---
|
||
|
||
## Documentation Provided
|
||
|
||
### For Understanding the System
|
||
1. **INSTALLATION_ARCHITECTURE.md** (11 sections)
|
||
- Full technical design
|
||
- All 4 phases documented
|
||
- Design decisions explained
|
||
- Security considerations
|
||
|
||
2. **INSTALLATION_COMPARISON.md** (Quick reference)
|
||
- Current vs Proposed side-by-side
|
||
- Before/after screenshots
|
||
- User experience comparison
|
||
- Benefits summary
|
||
|
||
### For Implementation
|
||
3. **PHASE_1_IMPLEMENTATION.md** (Ready to code)
|
||
- 6 detailed tasks
|
||
- Code examples
|
||
- Testing strategy
|
||
- Success criteria
|
||
- 4-5 hour estimate
|
||
|
||
### This Document
|
||
4. **INSTALLATION_SUMMARY.md** (This file)
|
||
- Executive overview
|
||
- Quick reference
|
||
- Links to detailed docs
|
||
|
||
---
|
||
|
||
## What Changes in Phase 1
|
||
|
||
### Configuration Files
|
||
```
|
||
BEFORE:
|
||
syntaxis/syntaxis-api-config.template.toml ❌
|
||
|
||
AFTER:
|
||
syntaxis/syntaxis-api-config.template.toml ✅
|
||
syntaxis/configs/features/projects.toml.template ✨
|
||
syntaxis/configs/features/tasks.toml.template ✨
|
||
syntaxis/configs/features/phases.toml.template ✨
|
||
syntaxis/configs/features/audit.toml.template ✨
|
||
```
|
||
|
||
### Installation Process
|
||
```
|
||
BEFORE:
|
||
1. Compile binaries
|
||
2. Install binaries
|
||
3. Done (user must do everything else)
|
||
|
||
AFTER:
|
||
1. Compile binaries
|
||
2. Install binaries
|
||
3. Deploy configurations
|
||
4. Register in manifest
|
||
5. Print summary
|
||
6. Done (user can run binaries)
|
||
```
|
||
|
||
### Installation Script
|
||
```
|
||
BEFORE:
|
||
install_binary() {
|
||
cargo install --path $path
|
||
}
|
||
|
||
AFTER:
|
||
install_binary() {
|
||
cargo install --path $path
|
||
deploy_configurations()
|
||
register_installations()
|
||
}
|
||
```
|
||
|
||
### User Guide
|
||
```
|
||
BEFORE:
|
||
No documentation on installation with configs
|
||
|
||
AFTER:
|
||
docs/installation-guide.md - Complete setup instructions
|
||
docs/configuration.md - Config options explained
|
||
Updated README.md - Quick start guide
|
||
```
|
||
|
||
---
|
||
|
||
## Impact Assessment
|
||
|
||
### For Users
|
||
| Metric | Before | After Phase 1 | After Phase 2 | Impact |
|
||
|--------|--------|---------------|---------------|--------|
|
||
| **Setup Time** | 30+ mins | 10 mins | 2 mins | ⬇️ 93% faster |
|
||
| **Config Location** | Scattered | Standard | Standard | ⬆️ Clear |
|
||
| **Manual Steps** | 8+ | 3-4 | 1 | ⬇️ Simpler |
|
||
| **Failure Rate** | 50% | 20% | <5% | ⬇️ Reliable |
|
||
| **Getting Help** | Hard | Medium | Easy | ⬇️ Better docs |
|
||
|
||
### For Developers
|
||
| Task | Before | After | Benefit |
|
||
|------|--------|-------|---------|
|
||
| **Adding new feature config** | Manual template | Template system | Consistent |
|
||
| **Debugging install issues** | Scattered logs | Manifest tracking | Clear audit trail |
|
||
| **Supporting users** | Complex setup | Standard location | Easy to debug |
|
||
| **Testing install** | Manual steps | Automated | Reliable |
|
||
|
||
---
|
||
|
||
## Implementation Path
|
||
|
||
### This Week
|
||
- [ ] Review INSTALLATION_ARCHITECTURE.md
|
||
- [ ] Confirm Phase 1 approach
|
||
- [ ] Create feature branch
|
||
|
||
### Next 1-2 Weeks (Phase 1)
|
||
- [ ] Rename config templates
|
||
- [ ] Create 4 new feature templates
|
||
- [ ] Update installation script
|
||
- [ ] Write documentation
|
||
- [ ] Test thoroughly
|
||
- [ ] Merge to main
|
||
|
||
### Following Weeks
|
||
- [ ] Phase 2: Wrapper scripts
|
||
- [ ] Phase 3: Manifest enhancement
|
||
- [ ] Phase 4: Documentation & testing
|
||
|
||
---
|
||
|
||
## How to Use These Documents
|
||
|
||
### 1. Quick Understanding (15 minutes)
|
||
Read in this order:
|
||
1. This document (INSTALLATION_SUMMARY.md)
|
||
2. INSTALLATION_COMPARISON.md (visual comparison)
|
||
|
||
### 2. Full Design Review (1 hour)
|
||
Read in this order:
|
||
1. INSTALLATION_ARCHITECTURE.md (full design)
|
||
2. INSTALLATION_COMPARISON.md (reference)
|
||
3. This document (summary)
|
||
|
||
### 3. Ready to Implement Phase 1 (30 minutes prep + 4 hours coding)
|
||
Read in this order:
|
||
1. This document (overview)
|
||
2. PHASE_1_IMPLEMENTATION.md (detailed tasks)
|
||
3. INSTALLATION_ARCHITECTURE.md section 4 (config strategy)
|
||
|
||
### 4. Questions About Specific Topics
|
||
|
||
**How does config discovery work?**
|
||
→ See INSTALLATION_ARCHITECTURE.md section 5
|
||
|
||
**What wrappers do?**
|
||
→ See INSTALLATION_ARCHITECTURE.md section 5
|
||
|
||
**Design decisions?**
|
||
→ See INSTALLATION_ARCHITECTURE.md section 8
|
||
|
||
**Implementation checklist?**
|
||
→ See PHASE_1_IMPLEMENTATION.md section 2
|
||
|
||
**Current vs proposed?**
|
||
→ See INSTALLATION_COMPARISON.md
|
||
|
||
---
|
||
|
||
## Quick Reference: Terminal Commands
|
||
|
||
### After Phase 1 Implementation
|
||
|
||
```bash
|
||
# Install everything (compiles + deploys configs)
|
||
just scripts-install
|
||
|
||
# Check what's installed
|
||
just scripts-status
|
||
|
||
# View deployed configs
|
||
cat ~/.config/core/syntaxis-api.toml
|
||
|
||
# Edit configuration
|
||
nano ~/.config/core/syntaxis-api.toml
|
||
|
||
# Run CLI tool
|
||
workspace --version
|
||
|
||
# Run Terminal UI
|
||
syntaxis-tui
|
||
|
||
# Run REST API (after Phase 2, with wrapper)
|
||
syntaxis-api
|
||
|
||
# View installation manifest
|
||
cat .syntaxis/manifest.toml
|
||
```
|
||
|
||
---
|
||
|
||
## Key Decisions Made
|
||
|
||
### ✅ Configuration Location: `~/.config/core/`
|
||
- Follows XDG Base Directory Specification
|
||
- Per-user configuration
|
||
- Separates code from config
|
||
- Works on all platforms (Linux, macOS, Windows)
|
||
|
||
### ✅ Configuration Format: TOML
|
||
- Already used in workspace
|
||
- Human-readable
|
||
- Serde validation support
|
||
- Feature-specific configs easy to compose
|
||
|
||
### ✅ Manifest Location: `.syntaxis/manifest.toml`
|
||
- Version-controlled
|
||
- Central installation tracking
|
||
- Clear audit trail
|
||
- Easy to query
|
||
|
||
### ✅ Phased Approach: 4 phases
|
||
- Phase 1: Deployments
|
||
- Phase 2: Wrappers
|
||
- Phase 3: Manifest enhancement
|
||
- Phase 4: Documentation
|
||
- Risk reduction, incremental value
|
||
|
||
### ✅ Wrapper Language: NuShell
|
||
- Consistent with workspace scripts
|
||
- Cross-platform
|
||
- Rich scripting capabilities
|
||
- Team standard
|
||
|
||
---
|
||
|
||
## Risks & Mitigation
|
||
|
||
| Risk | Mitigation |
|
||
|------|-----------|
|
||
| **Config format changes break existing setups** | Version tracking in manifest, migration guide |
|
||
| **Users confused about config location** | Clear documentation, installation guide |
|
||
| **Wrappers don't work on all platforms** | Test on Linux, macOS, Windows |
|
||
| **Performance impact from wrapper overhead** | Negligible (only on startup) |
|
||
| **Breaking existing installations** | Wrapper falls back to old behavior if needed |
|
||
|
||
---
|
||
|
||
## Success Metrics
|
||
|
||
After Phase 1:
|
||
- ✅ Config templates deployed automatically
|
||
- ✅ All 11 config templates available
|
||
- ✅ Manifest tracks installations
|
||
- ✅ Documentation complete
|
||
- ✅ Zero regressions in tests
|
||
|
||
After Phase 2:
|
||
- ✅ Wrapper scripts work on all platforms
|
||
- ✅ Environment setup automatic
|
||
- ✅ Config discovery works
|
||
- ✅ Integration tests passing
|
||
|
||
After Phase 4:
|
||
- ✅ Complete documentation
|
||
- ✅ User can install in < 2 minutes
|
||
- ✅ Setup works for 95%+ of users
|
||
- ✅ Troubleshooting guide covers common issues
|
||
|
||
---
|
||
|
||
## Questions Answered
|
||
|
||
### Q: Why is this needed?
|
||
**A:** Current users must manually copy and configure templates. This creates friction, errors, and confusion.
|
||
|
||
### Q: How long will it take?
|
||
**A:** Phase 1 is 4-5 hours. Full implementation (Phases 1-4) is 6-8 weeks.
|
||
|
||
### Q: Do we have to do all 4 phases?
|
||
**A:** Phase 1 alone provides significant value. Later phases enhance the experience.
|
||
|
||
### Q: Will this break existing installations?
|
||
**A:** No. This is purely additive. New installations get configs, old ones still work.
|
||
|
||
### Q: Can we do Phase 2 before Phase 1?
|
||
**A:** No, Phase 1 must come first. Wrappers need configs to find.
|
||
|
||
### Q: What about Windows users?
|
||
**A:** NuShell works on Windows. Config location uses standard Windows paths.
|
||
|
||
---
|
||
|
||
## Next Steps
|
||
|
||
1. **Review Documents** (1 hour)
|
||
- Read INSTALLATION_ARCHITECTURE.md
|
||
- Understand the design
|
||
|
||
2. **Confirm Approach** (30 minutes)
|
||
- Discuss with team
|
||
- Confirm Phase 1 tasks
|
||
- Agree on timeline
|
||
|
||
3. **Start Phase 1** (4-5 hours)
|
||
- Follow PHASE_1_IMPLEMENTATION.md
|
||
- Complete all 6 tasks
|
||
- Testing & verification
|
||
|
||
4. **Merge & Deploy**
|
||
- Create PR
|
||
- Code review
|
||
- Merge to main
|
||
- Tag release
|
||
|
||
---
|
||
|
||
## Related Documents
|
||
|
||
- **README.md** - Project overview
|
||
- **INSTALLATION_ARCHITECTURE.md** - Full technical design
|
||
- **INSTALLATION_COMPARISON.md** - Before/after comparison
|
||
- **PHASE_1_IMPLEMENTATION.md** - Implementation checklist
|
||
- **docs/configuration.md** - (To be created Phase 4)
|
||
- **docs/installation-guide.md** - (To be created Phase 1)
|
||
- **WRAPPER_DESIGN.md** - (To be created Phase 2)
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
**Question Asked:** "How we install targets with configs and wrappers?"
|
||
|
||
**Answer Provided:**
|
||
- **INSTALLATION_ARCHITECTURE.md** - How it works (full design)
|
||
- **PHASE_1_IMPLEMENTATION.md** - How to do Phase 1 (ready to code)
|
||
- **INSTALLATION_COMPARISON.md** - Why it matters (before/after)
|
||
- **INSTALLATION_SUMMARY.md** - This document (overview & TL;DR)
|
||
|
||
**Next Action:** Start Phase 1 when ready!
|
||
|
||
---
|
||
|
||
**Document Version:** 1.0
|
||
**Status:** Ready for Review & Implementation
|
||
**Created:** November 15, 2025
|
||
**Last Updated:** November 15, 2025
|
||
|
||
---
|
||
|
||
## Document Map
|
||
|
||
```
|
||
INSTALLATION_SUMMARY.md (this document)
|
||
├─ Quick understanding → Read this first
|
||
├─ Full design → Read INSTALLATION_ARCHITECTURE.md
|
||
├─ Ready to code → Read PHASE_1_IMPLEMENTATION.md
|
||
├─ Quick comparison → Read INSTALLATION_COMPARISON.md
|
||
└─ Specific questions → See cross-references
|
||
```
|
||
|
||
**Start here. Everything else follows.**
|