xbp universal build and deployment toolkit

xbp helps you build deploy and manage rust nextjs nodejs python expressjs and more integrates tightly with nginx and modern cloud devops workflows modular scriptable and built with extensibility in mind

features

• deploy and manage rust js nextjs python expressjs and custom multi language projects
• nginx integration and config templating
• modular cli with portable library core
• easy yaml config ssh support secrets management
• lightweight minimal dependencies cross platform
• multi service deployment support with pm2 integration
• version management via api integration
• service based configuration with validation

quickstart

# install rust cargo required
cargo install xbp-cli
# or build from source
cargo build --release

# list all running network ports
xbp ports
# filter by port number
xbp ports -p 3000
# list all services in current project
xbp services
# build a service
xbp service build zeus
# redeploy a service
xbp redeploy zeus

installation

• release binaries see releases
• from source requires rust 1.72+

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

configuration

xbp uses xbp.json configuration files located in .xbp/xbp.json or xbp.json in the project root

single service configuration legacy

{
  "project_name": "my-app",
  "port": 3000,
  "build_dir": "/path/to/project",
  "target": "nextjs",
  "branch": "main",
  "npm_script": "start"
}

multi service configuration

{
  "project_name": "my-project",
  "port": 3040,
  "build_dir": "/path/to/project",
  "services": [
    {
      "name": "api",
      "target": "expressjs",
      "branch": "main",
      "port": 3000,
      "root_directory": "apps/api",
      "url": "https://api.example.com",
      "healthcheck_path": "/",
      "restart_policy": "on_failure",
      "restart_policy_max_failure_count": 10,
      "start_wrapper": "pm2",
      "force_run_from_root": false,
      "commands": {
        "pre": "npm install -g pnpm",
        "install": "pnpm install",
        "build": "pnpm run build",
        "start": "pnpm run start",
        "dev": "pnpm run dev"
      }
    }
  ]
}

service configuration fields

• name unique service name required
• target one of python expressjs nextjs rust required
• branch git branch to deploy from required
• port service port number required
• root_directory relative or absolute path to service root optional defaults to project root
• url service url for healthchecks optional
• healthcheck_path path for healthcheck requests optional
• restart_policy pm2 restart policy optional defaults to on_failure
• restart_policy_max_failure_count max failures before stopping optional defaults to 10
• start_wrapper wrapper for start command typically pm2 optional
• force_run_from_root if true runs commands from project root instead of root_directory optional defaults to false
• commands object containing pre install build start dev commands optional

validation

xbp validates service configurations and will error if

• duplicate service names found
• duplicate ports found
• duplicate urls found
• invalid target type not one of python expressjs nextjs rust

commands

service management

• xbp services list all services from current xbp.json config
• xbp service <command> <service-name> run command for a service
  • commands: build install start dev
  • example: xbp service build zeus
• xbp service --help <service-name> show help for a specific service
• xbp redeploy <service-name> redeploy a specific service via pm2

deployment

• xbp redeploy [<service-name>] redeploy using redeploy.sh legacy or specific service
• xbp redeploy_v2 [-p <password>] [-u <username>] [-h <host>] [-d <project-dir>] remotely redeploy using redeploy.sh

general

• xbp ports [-p <port>] [--kill] [-n] list active ports and processes optionally search nginx configs
• xbp setup run initial setup commands
• xbp config display xbp.json contents
• xbp install <package> install a package
• xbp logs [<project>] view pm2 logs
• xbp list list pm2 processes
• xbp -l list pm2 processes shortcut
• xbp curl [<url>] fetch url and display response

redeploy workflow

when you run xbp redeploy <service-name> the following happens

1. git reset --hard to clean local changes
2. git pull origin to get latest code
3. fetch version from api.xbp.app/version?project_name=
4. create dist folder at /home/{USER}/.xbp/dist/{version}/
5. run pre command if configured
6. run install command if configured
7. run build command if configured
8. stop existing pm2 process for the service
9. copy build artifacts to dist folder
10. start pm2 process with wrapped start command
11. write logs to .xbp/logs/{service-name}/
12. update version via api increment endpoint
13. cleanup stopped and errored pm2 processes

service commands

service commands respect the root_directory and force_run_from_root settings

• if force_run_from_root is true commands run from project root
• if root_directory is set and force_run_from_root is false commands run from root_directory
• if neither is set commands run from project root

start commands are automatically wrapped with pm2 when start_wrapper is set to pm2 the start command will be executed as pm2 start "{start_command}" --name {name} -- --port {port}

pm2 integration

xbp integrates with pm2 for process management

• processes are named using the service name
• logs are written to .xbp/logs/{service-name}/stdout.log and stderr.log
• pm2 save is called after deployments to persist process list
• stopped and errored processes are automatically cleaned up

version management

xbp integrates with the xbp version api for version tracking

• versions are fetched from api.xbp.app/version?project_name=
• versions are incremented via api.xbp.app/version/increment after successful deployment
• version folders are created at /home/{USER}/.xbp/dist/{version}/

logging

xbp writes logs to multiple locations

• general logs: /var/log/xbp/ or ~/.xbp/logs/
• service logs: .xbp/logs/{service-name}/stdout.log and stderr.log
• pm2 logs: redirected to service log directories

logs are rotated when they exceed 10mb

architecture

• /src/main.rs cli entrypoint command parsing and dispatch
• /src/lib.rs core library module exports
• /src/commands/ cli subcommand implementations
  • service.rs service management commands
  • redeploy_service.rs service redeployment logic
  • pm2.rs pm2 process management
  • config_cmd.rs configuration display
  • and more
• /src/strategies/ deployment strategies and config management
  • deployment_config.rs config loading validation and service management
  • project_detector.rs project type detection
  • deployment_executor.rs deployment execution
• /src/utils/ utility functions
  • version.rs version api integration
• /src/logging.rs structured async logging
• /src/config.rs ssh and yaml config management

backward compatibility

xbp maintains backward compatibility with legacy single service configurations if no services array is found in xbp.json the top level config is treated as a single service this allows existing projects to continue working without modification

examples

list all services

xbp services

build a service

xbp service build zeus

install dependencies for a service

xbp service install zeus

start a service with pm2

xbp service start zeus

run dev mode for a service

xbp service dev zeus

redeploy a service

xbp redeploy zeus

show help for a service

xbp service --help zeus

contributing

prs welcome please document new modules and keep interfaces generic and reusable see src/lib.rs for api docs all code must follow rust conventions documentation should be lowercase with minimal punctuation

license

mit