[#94] Add quick reference and deployment checklist for production
This commit is contained in:
Allegro
197
docs/DEPLOYMENT_CHECKLIST.md
Normal file
197
docs/DEPLOYMENT_CHECKLIST.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Uni-Wizard v4 — Deployment Checklist
|
||||
|
||||
## Pre-Deployment
|
||||
|
||||
- [ ] VPS provisioned (Ubuntu 22.04 LTS recommended)
|
||||
- [ ] SSH access configured
|
||||
- [ ] Firewall rules set (ports 22, 80, 443, 3000, 8643)
|
||||
- [ ] Domain/DNS configured (optional)
|
||||
- [ ] SSL certificates ready (optional)
|
||||
|
||||
## Base System
|
||||
|
||||
- [ ] Update system packages
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
```
|
||||
- [ ] Install base dependencies
|
||||
```bash
|
||||
sudo apt install -y python3 python3-pip python3-venv sqlite3 curl git
|
||||
```
|
||||
- [ ] Create timmy user
|
||||
```bash
|
||||
sudo useradd -m -s /bin/bash timmy
|
||||
```
|
||||
- [ ] Configure sudo access (if needed)
|
||||
|
||||
## Gitea Setup
|
||||
|
||||
- [ ] Gitea installed and running
|
||||
- [ ] Repository created: `Timmy_Foundation/timmy-home`
|
||||
- [ ] API token generated
|
||||
- [ ] Webhooks configured (optional)
|
||||
- [ ] Test API access
|
||||
```bash
|
||||
curl -H "Authorization: token TOKEN" http://localhost:3000/api/v1/user
|
||||
```
|
||||
|
||||
## Uni-Wizard Installation
|
||||
|
||||
- [ ] Clone repository
|
||||
```bash
|
||||
sudo -u timmy git clone http://143.198.27.163:3000/Timmy_Foundation/timmy-home.git /opt/timmy/repo
|
||||
```
|
||||
- [ ] Run setup script
|
||||
```bash
|
||||
sudo ./scripts/setup-uni-wizard.sh
|
||||
```
|
||||
- [ ] Verify installation
|
||||
```bash
|
||||
/opt/timmy/venv/bin/python -c "from uni_wizard import Harness; print('OK')"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
- [ ] Edit config file
|
||||
```bash
|
||||
sudo nano /opt/timmy/config/uni-wizard.yaml
|
||||
```
|
||||
- [ ] Set Gitea API token
|
||||
- [ ] Configure house identity
|
||||
- [ ] Set log level (INFO for production)
|
||||
- [ ] Verify config syntax
|
||||
```bash
|
||||
/opt/timmy/venv/bin/python -c "import yaml; yaml.safe_load(open('/opt/timmy/config/uni-wizard.yaml'))"
|
||||
```
|
||||
|
||||
## LLM Setup (if using local inference)
|
||||
|
||||
- [ ] llama.cpp installed
|
||||
- [ ] Model downloaded (e.g., Hermes-4 14B)
|
||||
- [ ] Model placed in `/opt/timmy/models/`
|
||||
- [ ] llama-server configured
|
||||
- [ ] Test inference
|
||||
```bash
|
||||
curl http://localhost:8080/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model": "hermes4", "messages": [{"role": "user", "content": "Hello"}]}'
|
||||
```
|
||||
|
||||
## Service Startup
|
||||
|
||||
- [ ] Start Uni-Wizard
|
||||
```bash
|
||||
sudo systemctl start uni-wizard
|
||||
```
|
||||
- [ ] Start health daemon
|
||||
```bash
|
||||
sudo systemctl start timmy-health
|
||||
```
|
||||
- [ ] Start task router
|
||||
```bash
|
||||
sudo systemctl start timmy-task-router
|
||||
```
|
||||
- [ ] Enable auto-start
|
||||
```bash
|
||||
sudo systemctl enable uni-wizard timmy-health timmy-task-router
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] Check service status
|
||||
```bash
|
||||
sudo systemctl status uni-wizard
|
||||
```
|
||||
- [ ] View logs
|
||||
```bash
|
||||
sudo journalctl -u uni-wizard -f
|
||||
```
|
||||
- [ ] Test health endpoint
|
||||
```bash
|
||||
curl http://localhost:8082/health
|
||||
```
|
||||
- [ ] Test tool execution
|
||||
```bash
|
||||
/opt/timmy/venv/bin/uni-wizard execute system_info
|
||||
```
|
||||
- [ ] Verify Gitea polling
|
||||
```bash
|
||||
tail -f /opt/timmy/logs/task-router.log | grep "Polling"
|
||||
```
|
||||
|
||||
## Syncthing Mesh (if using multiple VPS)
|
||||
|
||||
- [ ] Syncthing installed on all nodes
|
||||
- [ ] Devices paired
|
||||
- [ ] Folders shared
|
||||
- `/opt/timmy/logs/`
|
||||
- `/opt/timmy/data/`
|
||||
- [ ] Test sync
|
||||
```bash
|
||||
touch /opt/timmy/logs/test && ssh other-vps "ls /opt/timmy/logs/test"
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
- [ ] Firewall configured
|
||||
```bash
|
||||
sudo ufw status
|
||||
```
|
||||
- [ ] Fail2ban installed (optional)
|
||||
- [ ] Log rotation configured
|
||||
```bash
|
||||
sudo logrotate -d /etc/logrotate.d/uni-wizard
|
||||
```
|
||||
- [ ] Backup strategy in place
|
||||
- [ ] Secrets not in git
|
||||
```bash
|
||||
grep -r "password\|token\|secret" /opt/timmy/repo/
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
- [ ] Health checks responding
|
||||
- [ ] Metrics being collected
|
||||
- [ ] Alerts configured (optional)
|
||||
- [ ] Log aggregation setup (optional)
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
- [ ] Document any custom configuration
|
||||
- [ ] Update runbooks
|
||||
- [ ] Notify team
|
||||
- [ ] Schedule first review (1 week)
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If deployment fails:
|
||||
|
||||
```bash
|
||||
# Stop services
|
||||
sudo systemctl stop uni-wizard timmy-health timmy-task-router
|
||||
|
||||
# Disable auto-start
|
||||
sudo systemctl disable uni-wizard timmy-health timmy-task-router
|
||||
|
||||
# Restore from backup (if available)
|
||||
# ...
|
||||
|
||||
# Or reset to clean state
|
||||
sudo rm -rf /opt/timmy/
|
||||
sudo userdel timmy
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All services running (`systemctl is-active` returns "active")
|
||||
- [ ] Health endpoint returns 200
|
||||
- [ ] Can execute tools via CLI
|
||||
- [ ] Gitea integration working (issues being polled)
|
||||
- [ ] Logs being written without errors
|
||||
- [ ] No critical errors in first 24 hours
|
||||
|
||||
---
|
||||
|
||||
**Deployed by:** _______________
|
||||
**Date:** _______________
|
||||
**VPS:** _______________
|
||||
220
docs/QUICK_REFERENCE.md
Normal file
220
docs/QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# Uni-Wizard v4 — Quick Reference
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Run setup script
|
||||
sudo ./scripts/setup-uni-wizard.sh
|
||||
|
||||
# Or manual install
|
||||
cd uni-wizard/v4
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```python
|
||||
from uni_wizard import Harness, House, Mode
|
||||
|
||||
# Create harness
|
||||
harness = Harness(house=House.TIMMY, mode=Mode.INTELLIGENT)
|
||||
|
||||
# Execute tool
|
||||
result = harness.execute("git_status", repo_path="/path/to/repo")
|
||||
|
||||
# Check prediction
|
||||
print(f"Predicted success: {result.provenance.prediction:.0%}")
|
||||
|
||||
# Get result
|
||||
if result.success:
|
||||
print(result.data)
|
||||
else:
|
||||
print(f"Error: {result.error}")
|
||||
```
|
||||
|
||||
## Command Line
|
||||
|
||||
```bash
|
||||
# Simple execution
|
||||
uni-wizard execute git_status --repo-path /path
|
||||
|
||||
# With specific house
|
||||
uni-wizard execute git_status --house ezra --mode intelligent
|
||||
|
||||
# Batch execution
|
||||
uni-wizard batch tasks.json
|
||||
|
||||
# Check health
|
||||
uni-wizard health
|
||||
|
||||
# View stats
|
||||
uni-wizard stats
|
||||
```
|
||||
|
||||
## Houses
|
||||
|
||||
| House | Role | Best For |
|
||||
|-------|------|----------|
|
||||
| `House.TIMMY` | Sovereign | Final decisions, critical ops |
|
||||
| `House.EZRA` | Archivist | Reading, analysis, documentation |
|
||||
| `House.BEZALEL` | Artificer | Building, testing, implementation |
|
||||
| `House.ALLEGRO` | Dispatch | Routing, connectivity, tempo |
|
||||
|
||||
## Modes
|
||||
|
||||
| Mode | Use When | Features |
|
||||
|------|----------|----------|
|
||||
| `Mode.SIMPLE` | Scripts, quick tasks | Direct execution, no overhead |
|
||||
| `Mode.INTELLIGENT` | Production work | Predictions, learning, adaptation |
|
||||
| `Mode.SOVEREIGN` | Critical decisions | Full provenance, approval gates |
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Check System Status
|
||||
```python
|
||||
result = harness.execute("system_info")
|
||||
print(result.data)
|
||||
```
|
||||
|
||||
### Git Operations
|
||||
```python
|
||||
# Status
|
||||
result = harness.execute("git_status", repo_path="/path")
|
||||
|
||||
# Log
|
||||
result = harness.execute("git_log", repo_path="/path", max_count=10)
|
||||
|
||||
# Pull
|
||||
result = harness.execute("git_pull", repo_path="/path")
|
||||
```
|
||||
|
||||
### Health Check
|
||||
```python
|
||||
result = harness.execute("health_check")
|
||||
print(f"Status: {result.data['status']}")
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
```python
|
||||
tasks = [
|
||||
{"tool": "git_status", "params": {"repo_path": "/path1"}},
|
||||
{"tool": "git_status", "params": {"repo_path": "/path2"}},
|
||||
{"tool": "system_info", "params": {}}
|
||||
]
|
||||
results = harness.execute_batch(tasks)
|
||||
```
|
||||
|
||||
## Service Management
|
||||
|
||||
```bash
|
||||
# Start services
|
||||
sudo systemctl start uni-wizard
|
||||
sudo systemctl start timmy-health
|
||||
sudo systemctl start timmy-task-router
|
||||
|
||||
# Check status
|
||||
sudo systemctl status uni-wizard
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u uni-wizard -f
|
||||
tail -f /opt/timmy/logs/uni-wizard.log
|
||||
|
||||
# Restart
|
||||
sudo systemctl restart uni-wizard
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Won't Start
|
||||
```bash
|
||||
# Check logs
|
||||
journalctl -u uni-wizard -n 50
|
||||
|
||||
# Verify config
|
||||
cat /opt/timmy/config/uni-wizard.yaml
|
||||
|
||||
# Test manually
|
||||
python -m uni_wizard health
|
||||
```
|
||||
|
||||
### No Predictions
|
||||
- Check pattern database exists: `ls /opt/timmy/data/patterns.db`
|
||||
- Verify learning is enabled in config
|
||||
- Run a few tasks to build patterns
|
||||
|
||||
### Gitea Integration Failing
|
||||
- Verify API token in config
|
||||
- Check Gitea URL is accessible
|
||||
- Test: `curl http://143.198.27.163:3000/api/v1/version`
|
||||
|
||||
## Configuration
|
||||
|
||||
Location: `/opt/timmy/config/uni-wizard.yaml`
|
||||
|
||||
```yaml
|
||||
house: timmy
|
||||
mode: intelligent
|
||||
enable_learning: true
|
||||
|
||||
pattern_db: /opt/timmy/data/patterns.db
|
||||
log_level: INFO
|
||||
|
||||
gitea:
|
||||
url: http://143.198.27.163:3000
|
||||
token: YOUR_TOKEN_HERE
|
||||
poll_interval: 300
|
||||
|
||||
hermes:
|
||||
stream_enabled: true
|
||||
db_path: /root/.hermes/state.db
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Harness Methods
|
||||
|
||||
```python
|
||||
# Execute single tool
|
||||
harness.execute(tool_name, **params) -> ExecutionResult
|
||||
|
||||
# Execute async
|
||||
await harness.execute_async(tool_name, **params) -> ExecutionResult
|
||||
|
||||
# Execute batch
|
||||
harness.execute_batch(tasks) -> List[ExecutionResult]
|
||||
|
||||
# Get prediction
|
||||
harness.predict(tool_name, params) -> Prediction
|
||||
|
||||
# Get stats
|
||||
harness.get_stats() -> Dict
|
||||
|
||||
# Get patterns
|
||||
harness.get_patterns() -> Dict
|
||||
```
|
||||
|
||||
### ExecutionResult Fields
|
||||
|
||||
```python
|
||||
result.success # bool
|
||||
result.data # Any
|
||||
result.error # Optional[str]
|
||||
result.provenance # Provenance
|
||||
result.suggestions # List[str]
|
||||
```
|
||||
|
||||
### Provenance Fields
|
||||
|
||||
```python
|
||||
provenance.house # str
|
||||
provenance.tool # str
|
||||
provenance.mode # str
|
||||
provenance.prediction # float
|
||||
provenance.execution_time_ms # float
|
||||
provenance.input_hash # str
|
||||
provenance.output_hash # str
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*For full documentation, see ARCHITECTURE.md*
|
||||
Reference in New Issue
Block a user