240 lines
7.4 KiB
Markdown
240 lines
7.4 KiB
Markdown
# provctl - Machine Orchestration & Service Control Platform
|
|
|
|
<div align="center">
|
|
<img src="imgs/provctl_logo_h.svg" alt="provctl Logo" width="600" />
|
|
</div>
|
|
|
|
[](https://www.rust-lang.org)
|
|
[](LICENSE)
|
|
|
|
**provctl** is a production-grade Machine Orchestration & Service Control Platform for managing SSH-based deployments across multiple machines with sophisticated deployment strategies, resilience features, and comprehensive observability.
|
|
|
|
## Features
|
|
|
|
✅ **Local Service Management**
|
|
- 🔧 **Multi-Backend Support** - systemd (Linux), launchd (macOS), PID files (Unix)
|
|
- 🎯 **Unified Interface** - Single CLI for all platforms
|
|
- 📊 **Status & Logging** - Comprehensive service monitoring
|
|
- ⚙️ **Configuration-Driven** - TOML-based zero-hardcoded-strings approach
|
|
|
|
✅ **Machine Orchestration**
|
|
- 🚀 **SSH Command Execution** - Real async SSH with ssh2-rs
|
|
- 📦 **Multiple Deployment Strategies** - Rolling, Blue-Green, Canary
|
|
- 🔄 **Connection Pooling** - Per-host reuse with configurable limits
|
|
- 🎯 **Retry & Timeout Logic** - Exponential/linear/fibonacci backoff strategies
|
|
- 🔒 **Host Key Verification** - SSH known_hosts integration
|
|
- 💪 **Circuit Breaker** - Fault tolerance for failing hosts
|
|
- 🏥 **Health Checks** - Command/HTTP/TCP monitoring
|
|
- 📊 **Metrics & Audit Logging** - Comprehensive observability
|
|
|
|
✅ **REST API & Web Dashboard**
|
|
- 🌐 **Axum REST API** - Production-grade HTTP server
|
|
- 📱 **Leptos Dashboard** - Modern Rust web UI
|
|
- 📡 **Programmatic Access** - Full API for automation
|
|
|
|
✅ **Production-Ready**
|
|
- Zero unsafe code (`#![forbid(unsafe_code)]`)
|
|
- Comprehensive error handling with Result<T> types
|
|
- 100% documentation coverage (rustdoc)
|
|
- No unwrap() calls in production code
|
|
|
|
✅ **Developer Friendly**
|
|
- Async/await throughout (tokio-based)
|
|
- Thread-safe metrics collection (Arc<Mutex<>>)
|
|
- Trait-based design for extensibility
|
|
- Full rustdoc for all public APIs
|
|
|
|
## Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Option 1: Use the installer
|
|
nu scripts/install-provctl.nu
|
|
|
|
# Option 2: Build manually
|
|
cargo build --release
|
|
./target/release/provctl --help
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Start a service
|
|
provctl start my-service
|
|
|
|
# Stop a service
|
|
provctl stop my-service
|
|
|
|
# Restart a service
|
|
provctl restart my-service
|
|
|
|
# Check status
|
|
provctl status my-service
|
|
|
|
# View logs (last 50 lines)
|
|
provctl logs my-service --lines 50
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description | Example |
|
|
|---------|-------------|---------|
|
|
| `start` | Start a service | `provctl start api` |
|
|
| `stop` | Stop a service | `provctl stop api` |
|
|
| `restart` | Restart a service | `provctl restart api` |
|
|
| `status` | Check service status | `provctl status api` |
|
|
| `logs` | View service logs | `provctl logs api --lines 100` |
|
|
|
|
## Configuration
|
|
|
|
provctl is **100% configuration-driven**. All user-facing strings and defaults come from TOML files:
|
|
|
|
- **`configs/messages.toml`** - All user-facing messages
|
|
- **`configs/defaults.toml`** - Timeouts, paths, and operational parameters
|
|
|
|
Zero hardcoded strings in code!
|
|
|
|
## Architecture
|
|
|
|
provctl uses a **trait-based backend system** for easy extensibility:
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ provctl-cli (clap) │
|
|
├─────────────────────────────────────┤
|
|
│ Backend Trait │
|
|
├─────────────┬───────────┬───────────┤
|
|
│ systemd │ launchd │ Pidfile │
|
|
│ (Linux) │ (macOS) │ (Unix) │
|
|
└─────────────┴───────────┴───────────┘
|
|
```
|
|
|
|
### Backends
|
|
|
|
**systemd** (Linux)
|
|
- Uses `systemctl` for service management
|
|
- Queries `journalctl` for logs
|
|
- Best for production Linux systems
|
|
|
|
**launchd** (macOS)
|
|
- Generates plist files automatically
|
|
- Uses `launchctl` for management
|
|
- Best for macOS development and production
|
|
|
|
**PID files** (Universal)
|
|
- Works on any Unix system
|
|
- File-based process tracking
|
|
- Fallback when systemd/launchd unavailable
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
provctl/
|
|
├── crates/
|
|
│ ├── provctl-core/ # Service management fundamentals
|
|
│ ├── provctl-config/ # Configuration loading
|
|
│ ├── provctl-backend/ # Backend trait + implementations
|
|
│ ├── provctl-cli/ # CLI interface
|
|
│ ├── provctl-machines/ # Machine orchestration core
|
|
│ │ ├── ssh_async.rs # Real async SSH
|
|
│ │ ├── ssh_pool.rs # Connection pooling
|
|
│ │ ├── ssh_retry.rs # Retry & timeout logic
|
|
│ │ ├── ssh_host_key.rs # Host key verification
|
|
│ │ ├── health_check.rs # Health monitoring
|
|
│ │ ├── metrics.rs # Metrics & audit logging
|
|
│ │ └── ... (other modules)
|
|
│ ├── provctl-api/ # REST API server
|
|
│ └── provctl-dashboard/ # Web UI (Leptos)
|
|
├── configs/
|
|
│ ├── messages.toml # User messages
|
|
│ └── defaults.toml # Configuration defaults
|
|
├── .coder/info/ # Project tracking & docs
|
|
├── docs/ # Documentation
|
|
└── scripts/ # Development & infrastructure scripts
|
|
```
|
|
|
|
## Development
|
|
|
|
### Build
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Test
|
|
|
|
```bash
|
|
cargo test --all
|
|
```
|
|
|
|
### Lint & Format
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo clippy --all --all-targets
|
|
```
|
|
|
|
### Documentation
|
|
|
|
```bash
|
|
cargo doc --open --no-deps
|
|
```
|
|
|
|
## Integration with syntaxis-api
|
|
|
|
provctl provides service management for syntaxis-api:
|
|
|
|
```bash
|
|
# In syntaxis-api.nu wrapper:
|
|
provctl start syntaxis-api
|
|
|
|
# Or from provisioning schema:
|
|
provctl deploy --config provisioning/syntaxis-api.toml
|
|
```
|
|
|
|
See [provisioning/](provisioning/) for integration examples.
|
|
|
|
## Code Quality Standards
|
|
|
|
✅ **No unsafe code** - Enforced via `#![forbid(unsafe_code)]`
|
|
✅ **100% documented** - All public APIs have rustdoc comments
|
|
✅ **Fully tested** - 332+ unit tests, 100% passing
|
|
✅ **Formatted & linted** - `cargo fmt` + `cargo clippy` clean
|
|
✅ **Zero hardcoded strings** - All in TOML configuration
|
|
✅ **Proper error handling** - Comprehensive Result<T> types
|
|
|
|
|
|
## License
|
|
|
|
MIT License - See [LICENSE](LICENSE) for details.
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome! Please ensure:
|
|
- `cargo fmt --all` passes
|
|
- `cargo clippy --all --all-targets` passes
|
|
- All tests pass: `cargo test --all`
|
|
- No unsafe code
|
|
|
|
## Documentation Overview
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| **QUICKSTART.md** | Get started with machine orchestration in 5 minutes |
|
|
| **docs/CLI_GUIDE.md** | Complete CLI reference for all commands |
|
|
| **docs/ARCHITECTURE.md** | System design and architecture |
|
|
| **docs/INSTALLATION_GUIDE.md** | Installation and setup instructions |
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
- **Quick Start**: See [QUICKSTART.md](QUICKSTART.md)
|
|
- **CLI Reference**: See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md)
|
|
- **Documentation**: See [docs/](docs/) directory
|
|
- **Architecture**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
|
|
|
---
|
|
|
|
**Made with ❤️ for the Rust community**
|