XBP

XBP (XYLEX Build Pack) is a deployment and operations CLI for single-service and multi-service projects. It combines build/run workflows, PM2 process management, diagnostics, nginx helpers, secrets workflows, and project version synchronization in one tool.

Features

• monitoring
• docker
• kubernetes [exp]
• kafka [exp]
• pm2 [wip]

current version: 10.17.2

TL;DR (30-Second Start)

# 1) Install
cargo install xbp

# 2) Check project/runtime state
xbp ports
xbp services

# 3) Run and inspect
xbp service build api
xbp service start api
xbp logs api

# 4) Keep versions aligned
xbp version
xbp version patch

Why XBP

• One CLI for local service workflows and server-side operations.
• Supports Rust, Node.js, Next.js, Python, Express, and mixed repos.
• Handles PM2 lifecycle, logs, snapshots, and environment inspection.
• Includes version reconciliation across common manifest files and git tags.
• Adds operational helpers for ports, nginx, diagnostics, and secrets.

Feature Overview

• Project and service orchestration: services, service, redeploy, setup.
• Process/runtime control: list, start, stop, flush, snapshot, resurrect, env, logs, tail.
• Network and infra helpers: ports, nginx, diag, curl.
• Configuration and security: config, secrets.
• Version workflows: version report, bump, explicit set, git-tag view.
• Optional monitoring command family (feature-gated build).
• Optional Kubernetes helper (feature-gated): xbp kubernetes ... for manifest generation, apply, readiness checks, and cert-manager issuer bootstrap. Build with --features kubernetes.
• Optional Docker helper (feature-gated): xbp -l / xbp list shows docker ps snapshot when built with --features docker.

Installation

Option 1: Build From Source

git clone https://github.com/xylex-group/xbp.git
cd xbp
cargo build --release
./target/release/xbp --help

Option 2: Install From Cargo

cargo install xbp

Verify Installation

xbp --version
xbp --help

Quick Start

# Discover project/runtime state
xbp ports
xbp services

# Build or run a service from xbp config
xbp service build api
xbp service start api

# Deploy flow shortcut
xbp redeploy api

# PM2 snapshots for recovery
xbp snapshot
xbp resurrect

# Version report across manifests and tags
xbp version

Configuration

XBP resolves project config in this order:

1. .xbp/xbp.yaml
2. .xbp/xbp.yml
3. .xbp/xbp.json
4. xbp.yaml
5. xbp.yml
6. xbp.json

Both YAML and JSON are supported. If no explicit project version is set, default is 0.1.0.

Minimal YAML

project_name: my-app
version: 0.1.0
port: 3000
build_dir: /path/to/project

Multi-Service Example

project_name: my-stack
version: 0.1.0
port: 3000
build_dir: /srv/my-stack

services:
  - name: api
    target: rust
    branch: main
    port: 3000
    root_directory: apps/api
    url: https://api.example.com
    commands:
      install: cargo fetch
      build: cargo build --release
      start: ./target/release/api

  - name: web
    target: nextjs
    branch: main
    port: 3001
    root_directory: apps/web
    commands:
      install: pnpm install
      build: pnpm run build
      start: pnpm run start

Core Fields

• project_name: logical project name.
• version: semantic version string for project-level versioning.
• port: primary project port.
• build_dir: absolute path to project root.
• services: optional service list.
• environment: optional environment variables.

Service Fields

• name: service identifier.
• target: rust, nextjs, nodejs, python, or expressjs.
• branch: deploy branch.
• port: service port.
• root_directory: optional service-specific working directory.
• url: optional public URL.
• healthcheck_path: optional health route.
• commands: optional pre, install, build, start, dev commands.

Command Cookbook

Project and Service Commands

• xbp services: list services from config.
• xbp service build <name>: run service build command.
• xbp service install <name>: run service install command.
• xbp service start <name>: run service start command.
• xbp service dev <name>: run service dev command.
• xbp redeploy <name>: redeploy one service.

Runtime and Operations

• xbp list: PM2 process list.
• xbp logs [project]: view PM2 logs.
• xbp logs --ssh-host <host> --ssh-username <user> --ssh-password <pw>: remote logs.
• xbp ports: active listening ports.
• xbp ports --kill --port 3000: kill process(es) on a port.
• xbp ports --nginx: include nginx mapping view.
• xbp ports --full: include reconciled XBP project port data.
• xbp diag: run environment diagnostics.
• xbp ports --exposure: diagnose service bind + firewall exposure per port.
• xbp nginx setup --domain <domain> --port <port> --email <email>: provision HTTPS reverse proxy with Certbot.
• xbp nginx list: list discovered nginx sites.
• xbp nginx show <domain>: show nginx config.
• xbp nginx update --domain <domain> --port <port>: update upstream port.
• xbp network floating-ip add --ip <IP>: write persistent floating IP config on detected backend.
• xbp network floating-ip add --ip <IP> --apply: write and apply/reload network config.
• xbp network floating-ip list: list floating IPs from runtime + config.
• xbp network config list: list discovered network config files and backend detection.
• xbp curl <url-or-domain>: quick endpoint health/content check.
• xbp kubernetes addons list: show full MicroK8s addon status (enabled/disabled).
• xbp kubernetes addons enable <name>: enable a MicroK8s addon.
• xbp kubernetes addons disable <name>: disable a MicroK8s addon.
• xbp kubernetes dashboard-token: extract the dashboard JWT token from describe secret.
• xbp kubernetes observability-creds: print decoded Grafana admin credentials from observability secret.
• xbp kubernetes issuer --email <email>: create/update a cert-manager Let's Encrypt issuer (feature-gated build).

PM2 Shortcuts

• xbp snapshot: save PM2 process snapshot.
• xbp resurrect: restore PM2 state.
• xbp stop <target>: stop one process or all.
• xbp flush [target]: flush logs globally or for a process.
• xbp monitor check: one-shot monitor check.
• xbp monitor start: monitor daemon.
• xbp env <pm2-name-or-id>: show PM2 env.

Config, Setup, and Secrets

• xbp setup: guided local setup helpers.
• xbp config: show/open global XBP config paths.
• xbp config --project: show current project config.
• xbp config openrouter set-key [KEY]: store OpenRouter API key globally.
• xbp config openrouter show [--raw]: inspect stored OpenRouter key.
• xbp config openrouter delete-key: remove stored OpenRouter key.
• xbp config github set-key [TOKEN]: store GitHub OAuth2 token globally.
• xbp config github show [--raw]: inspect stored GitHub token.
• xbp config github delete-key: remove stored GitHub token.
• xbp secrets list: list required/local env keys.
• xbp secrets push --file .env.local: push secrets to provider.
• xbp secrets pull --output .env.local: pull secrets from provider.
• xbp secrets verify: validate required env key availability.

Nginx HTTPS Setup

xbp nginx setup now covers the full native Certbot + Nginx wiring flow for both regular and wildcard domains.

# Standard domain (HTTP-01)
xbp nginx setup --domain api.example.com --port 3000 --email ops@example.com

# Wildcard domain with manual DNS-01 prompts
xbp nginx setup \
  --domain '*.example.com' \
  --port 3000 \
  --email ops@example.com \
  --dns-mode manual \
  --include-base true

# Wildcard domain with DNS plugin automation
xbp nginx setup \
  --domain '*.example.com' \
  --port 3000 \
  --email ops@example.com \
  --dns-mode plugin \
  --dns-plugin cloudflare \
  --dns-creds /root/.secrets/certbot/cloudflare.ini

Setup behavior:

• Ensures nginx and certbot are installed.
• Ensures /etc/letsencrypt/options-ssl-nginx.conf and /etc/letsencrypt/ssl-dhparams.pem exist.
• Writes a temporary HTTP ACME config for regular domains, then final HTTPS config with redirect.
• Uses DNS-01 for wildcard domains (manual or plugin mode).
• Reuses existing certificates when present.
• Validates config with nginx -t and restarts nginx on success.

Floating IP Persistence

XBP can persist Floating IP configuration for Linux hosts by auto-detecting the active backend in this order:

1. Netplan
2. NetworkManager keyfiles
3. ifupdown
4. RHEL ifcfg scripts

# Hetzner-style IPv4 floating IP persistence (write-only)
xbp network floating-ip add --ip 203.0.113.10

# IPv6 floating IP with explicit CIDR and apply
xbp network floating-ip add --ip 2a01:4f9:0:2a1::2 --cidr 64 --interface eth0 --apply

# Inspect persisted + runtime addresses
xbp network floating-ip list
xbp network config list

Versioning

• xbp version: full version report (manifests + tags + registry when configured).
• xbp version --git: show normalized git tag versions.
• xbp version major: bump major in tracked files.
• xbp version minor: bump minor in tracked files.
• xbp version patch: bump patch in tracked files.
• xbp version <x.y.z>: set tracked files to an explicit semver.
• xbp version <package>=<x.y.z>: update package assignment versions in tracked TOML files.
• xbp version release: create/push v<version> git tag and publish GitHub release.
• xbp version release --version <x.y.z>: release an explicit version.
• xbp version release --notes-file <PATH>: use custom Markdown release notes.

Version Management Details

xbp version resolves versions from configured files, local/remote git tags, and configured package registries. It normalizes prefixed tags (v1.2.3) and plain semver (1.2.3) into one comparison space.

Package Assignment Updates In TOML

xbp version <package>=<x.y.z> updates both forms in tracked TOML files:

• <package> = "x.y.z"
• <package> = { version = "x.y.z", ... }

Example:

xbp version tokio=1.45.1

Default Tracked Version Files

• README.md
• openapi.yaml
• openapi.yml
• Cargo.toml
• Cargo.lock
• package.json
• package-lock.json
• pyproject.toml
• xbp.yaml
• xbp.json
• .xbp/xbp.yaml
• .xbp/xbp.json

The registry is synchronized into global XBP config as versioning-files.yaml. Missing defaults are re-added without removing custom entries.

PM2 Behavior

XBP uses PM2 as an execution/runtime layer for many commands.

• Deploy and start flows can (re)start services under PM2.
• snapshot stores recoverable process state.
• resurrect first tries native PM2 restore, then falls back to latest XBP snapshot.
• env maps PM2 names to IDs and prints effective runtime environment.

Ports and Diagnostics

• xbp ports reconciles active listeners with detected project and nginx metadata.
• xbp diag validates common system dependencies and service expectations.

MCP Server

XBP includes an MCP stdio server at scripts/xbp_mcp_server.py. It exposes tools for all current xbp commands and includes xbp_raw for raw arg passthrough.

Run MCP Server

python3 scripts/xbp_mcp_server.py

What It Returns

Each tool call returns:

• Executed command array.
• Working directory.
• Exit code.
• Captured stdout/stderr.

Server Tests

python3 -m unittest scripts/test_xbp_mcp_server.py

Repository Layout

• src/main.rs: binary entrypoint.
• src/lib.rs: library exports.
• src/cli/: clap command definitions and dispatch.
• src/commands/: command implementations.
• src/strategies/: deployment strategy and project detection.
• src/sdk/: PM2 and nginx integrations.
• src/utils/: shared helpers.
• scripts/: support scripts including MCP server.

Development

cargo fmt
cargo test
python3 -m unittest scripts/test_xbp_mcp_server.py

Troubleshooting

• If xbp is not found, ensure Cargo bin path is on PATH.
• If PM2 commands fail, verify PM2 is installed and reachable in your shell env.
• If nginx commands fail, run with elevated permissions where required.
• If xbp version cannot update package assignments, confirm the target file is TOML and listed in versioning registry.
• If MCP command calls fail, confirm xbp is installed on the same environment where xbp_mcp_server.py is running.

License

MIT