road deploy

Part of BlackRoad OS — Sovereign Computing for Everyone

road deploy is part of the BlackRoad OS ecosystem — a sovereign, distributed operating system built on edge computing, local AI, and mesh networking by BlackRoad OS, Inc.

BlackRoad Ecosystem

Org	Focus
BlackRoad OS	Core platform
BlackRoad OS, Inc.	Corporate
BlackRoad AI	AI/ML
BlackRoad Hardware	Edge hardware
BlackRoad Security	Cybersecurity
BlackRoad Quantum	Quantum computing
BlackRoad Agents	AI agents
BlackRoad Network	Mesh networking

Website: blackroad.io | Chat: chat.blackroad.io | Search: search.blackroad.io

⚡️ INFRASTRUCTURE REVOLUTION ALERT ⚡️

!!!!!!!!!!!!!!!!!!!!!! WE ARE MOVING AWAY FROM CLOUDFLARE FOR DEPLOYMENTS !!!!!!!!!!!!!!!!!!!!!!

Git-based deployment engine for BlackRoad Pi cluster. Automatically clones, builds, and deploys websites from GitHub to the aria Pi with nginx configuration and SSL certificates.

🚀 What This Is

Node.js deployment engine that automates the entire deployment pipeline from GitHub push to live website. Supports multiple build systems, automatic SSL via Let's Encrypt, and GitHub webhook integration.

Features:

✅ Git-Based Deployments - Clone from GitHub, GitLab, Bitbucket
✅ Automatic Builds - npm, yarn, Go, Python, static sites
✅ nginx Configuration - Auto-generates reverse proxy configs
✅ Let's Encrypt SSL - Automatic HTTPS certificate generation
✅ GitHub Webhooks - Deploy on push automatically
✅ Rollback Support - Keep deployment history
✅ Zero Downtime - Atomic deployments with health checks

📊 Current Status

Status: Built and ready for deployment to alice Pi

Target Environment:

Host: alice (192.168.4.49)
Port: 9001
Target Server: aria (192.168.4.82)
Deploy Directory: /var/www/sites/

🏗️ Architecture

GitHub Push → Webhook → road-deploy (alice:9001)
                           ↓
                    1. Clone repo
                    2. Install dependencies
                    3. Run build command
                    4. rsync to aria Pi
                    5. Configure nginx
                    6. Generate SSL cert
                    7. Reload nginx
                           ↓
                    ✅ Website LIVE!

📦 API Endpoints

Health Check

GET /health

Deploy Website

POST /api/deploy
{
  "domain": "example.com",
  "repo_url": "https://github.com/user/repo",
  "branch": "main",
  "build_command": "npm run build",
  "deploy_path": "dist"
}

List Deployments

GET /api/deployments

Get Deployment Status

GET /api/deployments/:id

Rollback Deployment

POST /api/deployments/:id/rollback

GitHub Webhook Endpoint

POST /webhook/github
# Configure in GitHub repo settings:
# Payload URL: http://alice:9001/webhook/github
# Content type: application/json
# Events: push

🚀 Quick Start

Prerequisites:

Node.js 18+
SSH access to aria Pi (passwordless)
nginx installed on aria
certbot installed on aria (for SSL)

Installation:

# 1. Clone repo
git clone https://github.com/BlackRoad-OS/road-deploy.git
cd road-deploy

# 2. Install dependencies
npm install

# 3. Configure environment
cat > .env << EOF
PORT=9001
DEPLOY_BASE_DIR=/var/deployments
TARGET_HOST=pi@aria
TARGET_DEPLOY_DIR=/var/www/sites
NGINX_SITES_DIR=/etc/nginx/sites-available
NGINX_ENABLED_DIR=/etc/nginx/sites-enabled
EOF

# 4. Create deployment directories
mkdir -p /var/deployments
ssh pi@aria 'sudo mkdir -p /var/www/sites'

# 5. Setup SSH keys (passwordless to aria)
ssh-copy-id pi@aria

# 6. Start server
npm start

Deployment to Alice Pi:

# 1. Copy files to alice
scp -r ~/road-deploy pi@alice:~/

# 2. SSH into alice
ssh pi@alice

# 3. Install dependencies
cd ~/road-deploy
npm install

# 4. Setup SSH to aria
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519
ssh-copy-id pi@aria

# 5. Create deployment directory
mkdir -p /var/deployments

# 6. Install PM2
sudo npm install -g pm2

# 7. Start with PM2
pm2 start server.js --name road-deploy
pm2 save
pm2 startup

🔧 Usage Examples

Deploy a Static Site

curl -X POST http://alice:9001/api/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "blackroad.io",
    "repo_url": "https://github.com/BlackRoad-OS/blackroad-os-landing",
    "branch": "main",
    "build_command": "echo \"Static site - no build needed\"",
    "deploy_path": "."
  }'

Deploy a React App

curl -X POST http://alice:9001/api/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.blackroad.io",
    "repo_url": "https://github.com/BlackRoad-OS/blackroad-app",
    "branch": "main",
    "build_command": "npm install && npm run build",
    "deploy_path": "build"
  }'

Deploy a Next.js App

curl -X POST http://alice:9001/api/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "docs.blackroad.io",
    "repo_url": "https://github.com/BlackRoad-OS/docs",
    "branch": "main",
    "build_command": "npm install && npm run build",
    "deploy_path": ".next"
  }'

Check Deployment Status

# List all deployments
curl http://alice:9001/api/deployments

# Get specific deployment
curl http://alice:9001/api/deployments/abc-123-def

🌐 GitHub Webhook Setup

1. Configure Webhook in GitHub:

Go to: Settings > Webhooks > Add webhook

Payload URL: http://alice:9001/webhook/github
Content type: application/json
Secret: (optional - set in .env as WEBHOOK_SECRET)
Events: Just the push event
Active: ✅

2. Add Deployment Config to Repo:

Create .road-deploy.json in your repo root:

{
  "domain": "example.com",
  "build_command": "npm run build",
  "deploy_path": "dist",
  "ssl": true,
  "health_check": "/"
}

3. Push to Trigger Deployment:

git push origin main
# Deployment triggered automatically! 🚀

🗂️ Files

server.js - Express deployment engine (300+ lines)
package.json - Node.js dependencies
.env - Environment configuration
README.md - This file

🔧 Build Systems Supported

Node.js/npm

npm install && npm run build

Yarn

yarn install && yarn build

Go

go build -o app main.go

Python

pip install -r requirements.txt && python build.py

Static Sites

echo "No build needed"

🔐 nginx Configuration

The deployment engine automatically generates nginx configs:

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/sites/example.com;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Automatic SSL redirect after certbot
    # listen 443 ssl;
    # ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}

🔒 SSL/HTTPS Setup

Automatic Let's Encrypt:

# Deployment engine runs:
sudo certbot --nginx -d example.com -d www.example.com --non-interactive --agree-tos -m admin@blackroad.io

# Result: HTTPS automatically configured! 🔒

Manual SSL:

ssh pi@aria
sudo certbot --nginx -d example.com
sudo nginx -s reload

📊 Monitoring

Health Check:

curl http://alice:9001/health

PM2 Status:

pm2 status
pm2 logs road-deploy
pm2 monit

Deployment Logs:

# View deployment history
curl http://alice:9001/api/deployments | jq

# Watch live deployment
pm2 logs road-deploy --lines 50

🔄 Rollback

Automatic Rollback:

If deployment fails health check, automatically rolls back to previous version.

Manual Rollback:

curl -X POST http://alice:9001/api/deployments/abc-123/rollback

🚀 Advanced Features

Blue-Green Deployments

Deploys to new directory, health checks, then atomically switches symlinks.

Multi-Environment

Support for staging/production branches:

{
  "branches": {
    "main": "production",
    "staging": "staging"
  }
}

Pre/Post Deploy Hooks

Run custom scripts before/after deployment:

{
  "hooks": {
    "pre_deploy": "./scripts/backup-db.sh",
    "post_deploy": "./scripts/notify-slack.sh"
  }
}

🌐 Integration with Other Components

road-dns-deploy (PowerDNS)

Ensures DNS records point to aria (192.168.4.82)
Automatic subdomain configuration

road-registry-api

Reports deployment status to API
Tracks deployment history in database

road-control (Web UI)

Trigger deployments from web interface
View deployment logs and history

🖤🛣️ The Vision

Part of the BlackRoad Domain Registry ecosystem:

GitHub → [road-dns-deploy] → [road-registry-api] → [road-deploy] → [road-control]
            PowerDNS            API Server          This Engine      Web UI

Workflow:

Push code to GitHub
Webhook triggers road-deploy
Clone, build, deploy to aria
Configure nginx + SSL
Update road-registry-api status
Website live! 🚀

Total independence. Total control. Total sovereignty.

📚 Related Repos

road-dns-deploy - PowerDNS deployment
road-registry-api - Domain management API
road-control - Web control panel

📞 Support

Email: blackroad.systems@gmail.com
GitHub Issues: BlackRoad-OS/road-deploy/issues

Built with 🖤 by BlackRoad OS, Inc.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github		.github
node_modules		node_modules
.env		.env
.gitignore		.gitignore
BLACKROAD_IP_NOTICE.txt		BLACKROAD_IP_NOTICE.txt
CODEOWNERS		CODEOWNERS
INFRASTRUCTURE_ANNOUNCEMENT.md		INFRASTRUCTURE_ANNOUNCEMENT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js

Folders and files

Latest commit

History

Repository files navigation

road deploy

BlackRoad Ecosystem

⚡️ INFRASTRUCTURE REVOLUTION ALERT ⚡️

🚀 What This Is

Features:

📊 Current Status

🏗️ Architecture

📦 API Endpoints

Health Check

Deploy Website

List Deployments

Get Deployment Status

Rollback Deployment

GitHub Webhook Endpoint

🚀 Quick Start

Prerequisites:

Installation:

Deployment to Alice Pi:

🔧 Usage Examples

Deploy a Static Site

Deploy a React App

Deploy a Next.js App

Check Deployment Status

🌐 GitHub Webhook Setup

1. Configure Webhook in GitHub:

2. Add Deployment Config to Repo:

3. Push to Trigger Deployment:

🗂️ Files

🔧 Build Systems Supported

Node.js/npm

Yarn

Go

Python

Static Sites

🔐 nginx Configuration

🔒 SSL/HTTPS Setup

Automatic Let's Encrypt:

Manual SSL:

📊 Monitoring

Health Check:

PM2 Status:

Deployment Logs:

🔄 Rollback

Automatic Rollback:

Manual Rollback:

🚀 Advanced Features

Blue-Green Deployments

Multi-Environment

Pre/Post Deploy Hooks

🌐 Integration with Other Components

road-dns-deploy (PowerDNS)

road-registry-api

road-control (Web UI)

🖤🛣️ The Vision

📚 Related Repos

📞 Support

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages