# XBP CLI Complete Guide
## Overview
XBP (eXtensible Build Pack) is a comprehensive deployment, monitoring, and logging toolkit with native support for Rust, Next.js, Node.js, Python, and more. It integrates tightly with Nginx, PM2, systemctl, and modern cloud DevOps workflows.
## Installation
```bash
cargo install xbp
# or build from source
cargo build --release --features kafka
```
## Core Commands
### 📊 Diagnostics
```bash
# Run full system diagnostics
xbp diag
# Check only Nginx configuration
xbp diag --nginx
# Check specific ports
xbp diag --ports 3000,8080,9090
# Skip internet speed test
xbp diag --no-speed-test
```
**What `xbp diag` checks:**
- CPU usage percentage
- RAM usage and availability
- Disk space
- Network statistics
- System uptime and process count
- Nginx status (running, enabled, config valid)
- Port availability and firewall blocking
- Internet connectivity
- Internet speed (download/upload/ping)
### 🔌 Port Management
```bash
# List all ports
xbp ports
# Check specific port
xbp ports -p 3000
# Kill processes on port
xbp ports -p 3000 --kill
# Check Nginx ports
xbp ports -n
```
### 🔧 Nginx Management
```bash
# Setup Nginx reverse proxy
xbp nginx setup --domain api.example.com --port 3000
# List all Nginx configurations
xbp nginx list
# Update existing configuration
xbp nginx update --domain api.example.com --port 3001
```
### Service Management
```bash
# List all services
xbp services
# Build a service
xbp service build my-api
# Install dependencies
xbp service install my-api
# Start a service
xbp service start my-api
# Run dev mode
xbp service dev my-api
# Show service help
xbp service --help my-api
```
### 🚀 Deployment
```bash
# Redeploy all services
xbp redeploy
# Redeploy specific service
xbp redeploy my-api
# Remote deployment
xbp redeploy-v2 -u username -h host -d /path/to/project
```
### 📝 PM2 Management
```bash
# List PM2 processes
xbp list
# View logs
xbp logs my-service
# Stop process
xbp pm2 my-service stop
# Start process
xbp pm2 my-service start
# Restart process
xbp pm2 my-service restart
# Delete process
xbp pm2 my-service delete
```
### 📡 Monitoring
```bash
# Run single health check
xbp monitor check
# Start monitoring daemon
xbp monitor start
```
**Configuration in `xbp.json`:**
```json
{
"monitor_url": "https://api.example.com/health",
"monitor_method": "GET",
"monitor_expected_code": 200,
"monitor_interval": 60
}
```
### 📋 Log Management
```bash
# Tail local log files
xbp tail
# Ship logs to Kafka
xbp tail --ship
# Tail Kafka topic
xbp tail --kafka
```
**Configuration in `xbp.json`:**
```json
{
"log_files": [
"/var/log/app/api.log",
"/var/log/app/worker.log"
],
"kafka_brokers": "localhost:9092",
"kafka_topic": "application-logs",
"kafka_public_url": "https://kafka.example.com"
}
```
### 🌐 HTTP Utilities
```bash
# Make HTTP request
xbp curl https://api.example.com/health
# With custom URL
xbp curl https://example.com/api/status
```
### Configuration
```bash
# View configuration
xbp config
# Setup XBP
xbp setup
```
### Package Installation
```bash
# Install package
xbp install docker
xbp install nginx
xbp install grafana
```
## Configuration File
### Complete `xbp.json` Example
```json
{
"project_name": "my-application",
"port": 3000,
"build_dir": "/home/user/projects/my-app",
"app_type": "rust",
"build_command": "cargo build --release",
"start_command": "./target/release/my-app",
"install_command": "cargo fetch",
"services": [
{
"name": "api",
"target": "rust",
"port": 3000,
"branch": "main",
"url": "https://api.example.com"
},
{
"name": "frontend",
"target": "nextjs",
"port": 3001,
"branch": "main",
"url": "https://app.example.com"
}
],
"monitor_url": "https://api.example.com/health",
"monitor_method": "GET",
"monitor_expected_code": 200,
"monitor_interval": 60,
"log_files": [
"/var/log/app/api.log",
"/var/log/app/frontend.log"
],
"kafka_brokers": "localhost:9092",
"kafka_topic": "app-logs",
"kafka_public_url": "https://kafka.example.com",
"environment": {
"NODE_ENV": "production",
"RUST_LOG": "info"
}
}
```
## API Mode
Start XBP as an API server:
```bash
export PORT_XBP_API=8080
xbp
```
API documentation available at `openapi.yaml`.
## Advanced Features
### Systemctl Integration
XBP automatically checks systemctl services:
- Nginx status and configuration
- Service health monitoring
- Auto-restart on failures
### Kafka Integration
Enable Kafka support:
```bash
cargo build --release --features kafka
```
Features:
- Real-time log streaming
- Topic tailing
- Bulk log shipping
- Automatic service name detection
### Monitoring Features
- Continuous health checks
- Response time tracking
- Status code validation
- Automatic alerting
- Configurable intervals
### Diagnostics Features
- CPU usage monitoring
- Memory usage tracking
- Disk space analysis
- Network statistics
- Port availability checking
- Firewall status
- Internet speed testing
- Nginx configuration validation
## Environment Variables
```bash
# API server port
PORT_XBP_API=8080
# Logging level
RUST_LOG=info
# Debug mode
XBP_DEBUG=1
```
## Exit Codes
- `0` - Success
- `1` - General error
- `2` - Configuration error
- `3` - Network error
- `4` - Service error
## Best Practices
1. **Always run `xbp diag` before deployment** to ensure system health
2. **Use `xbp monitor start`** for production monitoring
3. **Configure Kafka** for centralized logging in multi-server setups
4. **Keep `xbp.json`** in version control
5. **Use `xbp nginx setup`** for automatic reverse proxy configuration
## Troubleshooting
### Port conflicts
```bash
xbp ports -p 3000 --kill
```
### Nginx issues
```bash
xbp diag --nginx
```
### Service not starting
```bash
xbp service build my-service
xbp service install my-service
xbp service start my-service
```
### Logs not appearing
```bash
# Check log file paths
xbp config
# Verify Kafka connection
xbp tail --kafka
```
## Examples
### Deploy a Rust API
```bash
# Setup project
cd my-rust-api
xbp setup
# Configure Nginx
xbp nginx setup --domain api.example.com --port 3000
# Deploy
xbp service build api
xbp service start api
# Monitor
xbp monitor start
```
### Multi-service deployment
```json
{
"services": [
{"name": "api", "target": "rust", "port": 3000},
{"name": "frontend", "target": "nextjs", "port": 3001},
{"name": "worker", "target": "python", "port": 3002}
]
}
```
```bash
xbp services
xbp redeploy
```
### Centralized logging
```bash
# Ship logs to Kafka
xbp tail --ship
# On monitoring server, tail all logs
xbp tail --kafka
```
## Contributing
See `README.md` for contribution guidelines.
## License
MIT License - see `LICENSE` file.