blackroad-os/blackroad-os-demo
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Sync latest templates from blackroad-sandbox

Browse Source 
✨ Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alexa Louise
2025-12-12 01:38:14 -06:00
committed by Your Name
parent 806c200ddd
commit d9c4a93cf0
30 changed files with 8732 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

803
templates/COPY-PASTE-COMMANDS-LIBRARY.md Normal file
View File

@@ -0,0 +1,803 @@
# Copy-Paste Commands Library
**The Ultimate Terminal Command Reference - Zero Typing Required**
This library contains **perfect, tested, copy-paste-ready command blocks** for every common operation. Just copy and paste - the comments teach you what's happening.
---
## Table of Contents
1. [Quick Deployments](#quick-deployments)
2. [Service Management](#service-management)
3. [Git Operations](#git-operations)
4. [Environment Setup](#environment-setup)
5. [Testing](#testing)
6. [Docker](#docker)
7. [SSH & Remote](#ssh--remote)
8. [File Operations](#file-operations)
9. [Debugging](#debugging)
10. [Security & Secrets](#security--secrets)
---
## Quick Deployments
### Deploy Everything
```bash
# Deploy to all platforms
cd ~/blackroad-sandbox
# 1. Cloudflare Pages (static sites)
./deploy-all-domains.sh
# 2. Railway (backends)
./deploy-all-railway-services.sh
# 3. Vercel (frontends)
./deploy-vercel-all.sh
# 4. Verify all
./br health
```
### Deploy to Cloudflare
```bash
# Deploy complete API
cd ~/blackroad-sandbox/cloudflare-workers
wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
# Initialize databases
wrangler d1 execute blackroad-users --file=../cloudflare-d1-schemas.sql
# Deploy edge router
wrangler deploy blackroad-edge-router.js
# Verify deployment
wrangler pages deployment list --project-name=blackroad-io
```
### Deploy to Railway
```bash
# Set token
export RAILWAY_TOKEN=your-token-here
# Link to project
railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
# Deploy service
railway up --service api-gateway
# Check status
railway status
# View logs
railway logs --tail 100
```
### Deploy to Vercel
```bash
# Deploy to production
cd ~/blackroad-sandbox/vercel-projects/app-name
vercel --prod
# Verify deployment
vercel ls
# View deployment details
vercel inspect
```
---
## Service Management
### Start All Services
```bash
# Start all services in background
cd ~/blackroad-sandbox
./start-all.sh
# Verify all running
curl http://localhost:8000/health
curl http://localhost:9700/api/health
curl http://localhost:9800/api/health
```
### Start Specific Service
```bash
# Start on default port
cd ~/blackroad-sandbox
python3 blackroad-service.py &
# Start on custom port
PORT=9999 python3 blackroad-service.py &
# Verify it started
sleep 2
curl http://localhost:9999/health
```
### Stop All Services
```bash
# Kill all BlackRoad services
pkill -f "blackroad-"
# Verify stopped
pgrep -f "blackroad-" || echo "All services stopped"
```
### Restart Services
```bash
# Kill all services
pkill -f "blackroad-"
# Wait for graceful shutdown
sleep 2
# Restart
cd ~/blackroad-sandbox
./start-all.sh
# Verify
./br health
```
### Check Service Status
```bash
# Check what's running
pgrep -af "blackroad-"
# Check specific ports
lsof -i :8000
lsof -i :9700
# Check Railway status
railway status
# Check Cloudflare deployments
wrangler pages deployment list
```
---
## Git Operations
### Complete Commit and Push
```bash
# Navigate to repo
cd ~/blackroad-sandbox
# Stage all changes
git add .
# Commit with message
git commit -m "feat: Add new feature
Description of changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
# Push to main
git push origin main
```
### Create Feature Branch
```bash
# Create and switch to new branch
git checkout -b feature/new-feature
# Push to remote
git push -u origin feature/new-feature
# Create PR
gh pr create --title "Add new feature" --body "Description of changes"
```
### Sync with Remote
```bash
# Pull latest changes
git pull origin main
# Fetch all branches
git fetch --all
# View status
git status
```
### Fix Merge Conflicts
```bash
# Pull with rebase
git pull --rebase origin main
# If conflicts, resolve them then:
git add .
git rebase --continue
# Or abort rebase
git rebase --abort
```
---
## Environment Setup
### Create .env File
```bash
# Copy template
cp .env.example .env
# Add secrets
cat >> .env <<'EOF'
# Core
RAILWAY_TOKEN=your-token-here
BLACKROAD_SECRET_KEY=your-secret-here
# AI Services
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
# Cloud Platforms
CLOUDFLARE_API_TOKEN=...
VERCEL_TOKEN=...
# Payment & Auth
STRIPE_SECRET_KEY=sk_live_...
CLERK_SECRET_KEY=sk_...
EOF
# Source environment
source .env
# Verify
echo "Railway token: ${RAILWAY_TOKEN:0:10}..."
```
### Load Environment
```bash
# Source from .env
source .env
# Export to child processes
set -a
source .env
set +a
# Verify variables are set
echo $RAILWAY_TOKEN
echo $STRIPE_SECRET_KEY
```
### Check Environment
```bash
# Check all required variables
for key in RAILWAY_TOKEN STRIPE_SECRET_KEY CLOUDFLARE_API_TOKEN CLERK_SECRET_KEY; do
if [ -n "${!key}" ]; then
echo "✅ $key is set"
else
echo "❌ $key not set"
fi
done
```
---
## Testing
### Run All Tests
```bash
# All tests with verbose output
cd ~/blackroad-sandbox
pytest -v
# All tests with coverage
pytest --cov=. --cov-report=html --cov-report=xml
# Open coverage report
open coverage_html/index.html
```
### Run Specific Test Types
```bash
# Unit tests only (fast)
pytest -m unit -v
# Integration tests
pytest -m integration -v
# End-to-end tests
pytest -m e2e -v
# Slow tests
pytest -m slow -v
```
### Quick Development Testing
```bash
# Stop on first failure
pytest -v -x
# Run last failed tests
pytest --lf
# Failed first, then others
pytest --ff
# Development loop: failed first, stop on failure
pytest -v -x --ff
```
### Test Specific Files
```bash
# Single file
pytest tests/unit/test_api.py -v
# Multiple files
pytest tests/unit/test_api.py tests/unit/test_auth.py -v
# All files matching pattern
pytest tests/integration/test_*.py -v
```
---
## Docker
### Start All Containers
```bash
# Start all services
cd ~/blackroad-sandbox
docker-compose up -d
# View status
docker-compose ps
# View logs
docker-compose logs -f
```
### Start Specific Services
```bash
# Start only specific services
docker-compose up -d auth-api event-bus service-registry
# View their logs
docker-compose logs -f auth-api event-bus
```
### Stop and Clean
```bash
# Stop all services
docker-compose down
# Stop and remove volumes
docker-compose down -v
# Remove all containers, networks, images
docker-compose down --rmi all -v
```
### Rebuild and Restart
```bash
# Rebuild images
docker-compose build
# Rebuild and start
docker-compose up -d --build
# Rebuild specific service
docker-compose build api-gateway
docker-compose up -d api-gateway
```
### View Logs
```bash
# All logs
docker-compose logs
# Follow logs (live)
docker-compose logs -f
# Specific service
docker-compose logs -f service-name
# Last 100 lines
docker-compose logs --tail 100
```
---
## SSH & Remote
### Connect to Servers
```bash
# Raspberry Pi
ssh alice@192.168.4.49
# DigitalOcean droplet
ssh root@159.65.43.12
# iPhone Koder
ssh mobile@192.168.4.68 -p 8080
```
### Run Remote Commands
```bash
# Single command on Pi
ssh alice@192.168.4.49 "cd /home/alice && ./start-services.sh"
# Multiple commands on droplet
ssh root@159.65.43.12 "cd /root/blackroad-os && git pull && docker-compose up -d"
# Get status from Pi
ssh alice@192.168.4.49 "systemctl status blackroad-*"
```
### Copy Files to Remote
```bash
# Copy file to Pi
scp local-file.txt alice@192.168.4.49:/home/alice/
# Copy directory to droplet
scp -r local-directory root@159.65.43.12:/root/
# Copy from remote to local
scp alice@192.168.4.49:/home/alice/remote-file.txt ./
```
---
## File Operations
### Create Directory Structure
```bash
# Create nested directories
mkdir -p ~/blackroad-sandbox/new-feature/{src,tests,docs}
# Create with specific permissions
mkdir -p ~/blackroad-sandbox/secure && chmod 700 ~/blackroad-sandbox/secure
```
### Create Files with Content
```bash
# Single line
echo "VARIABLE=value" >> .env
# Multi-line with heredoc
cat > config.yaml <<'EOF'
service:
name: api-gateway
port: 8000
environment: production
EOF
# Python file with template
cat > service.py <<'EOF'
#!/usr/bin/env python3
from flask import Flask
app = Flask(__name__)
@app.route('/health')
def health():
return {"ok": True}
if __name__ == '__main__':
app.run(host='0.0.0.0', port=8000)
EOF
# Make executable
chmod +x service.py
```
### Search and Replace
```bash
# Replace in single file
sed -i '' 's/old-value/new-value/g' config.yaml
# Replace in multiple files
find . -name "*.py" -exec sed -i '' 's/old-value/new-value/g' {} +
# Replace only in specific directory
find src/ -name "*.py" -exec sed -i '' 's/old-value/new-value/g' {} +
```
### Find Files
```bash
# Find by name
find . -name "blackroad-*.py"
# Find by type (files only)
find . -type f -name "*.py"
# Find and list with details
find . -name "*.py" -exec ls -lh {} +
# Find modified in last 24 hours
find . -name "*.py" -mtime -1
```
---
## Debugging
### Find What's Using a Port
```bash
# Find process using port 8000
lsof -i :8000
# Kill process using port 8000
kill -9 $(lsof -t -i:8000)
# Find all Python processes
lsof -i -P | grep python
```
### Check Process Status
```bash
# Find BlackRoad processes
pgrep -af "blackroad-"
# Find Python processes
pgrep -af "python3"
# Kill specific process
pkill -f "blackroad-service"
# Kill all Python processes
pkill python3
```
### Monitor Logs
```bash
# Tail local log file
tail -f /path/to/log/file
# Tail with line count
tail -n 100 -f /path/to/log/file
# Tail multiple files
tail -f log1.txt log2.txt
# Tail Railway logs
railway logs --tail 100 --follow
# Tail Docker logs
docker-compose logs -f --tail 100
```
### Test API Endpoints
```bash
# GET request
curl http://localhost:8000/health
# POST request with JSON
curl http://localhost:8000/api/resource \
-X POST \
-H "Content-Type: application/json" \
-d '{"key":"value"}'
# PUT request
curl http://localhost:8000/api/resource/123 \
-X PUT \
-H "Content-Type: application/json" \
-d '{"key":"new-value"}'
# DELETE request
curl http://localhost:8000/api/resource/123 -X DELETE
# With authentication
curl http://localhost:8000/api/protected \
-H "Authorization: Bearer $API_TOKEN"
```
---
## Security & Secrets
### Set Railway Secrets
```bash
# Single secret
railway variables set STRIPE_KEY=sk_live_...
# Multiple secrets
railway variables set \
STRIPE_KEY=sk_live_... \
CLERK_KEY=sk_... \
OPENAI_KEY=sk-...
# From file
while IFS='=' read -r key value; do
railway variables set "$key=$value"
done < secrets.txt
# Verify secrets
railway variables
```
### Set Cloudflare Secrets
```bash
# Set worker secret
wrangler secret put STRIPE_KEY
# Set multiple secrets
echo "sk_live_..." | wrangler secret put STRIPE_KEY
echo "sk-..." | wrangler secret put OPENAI_KEY
# List secrets
wrangler secret list
```
### Set GitHub Secrets
```bash
# Single secret
gh secret set RAILWAY_TOKEN -b"your-token-here"
# From file
gh secret set RAILWAY_TOKEN < token.txt
# For specific repo
gh secret set RAILWAY_TOKEN -b"your-token-here" -R BlackRoad-OS/repo-name
# List secrets
gh secret list
```
### Rotate Secrets
```bash
# 1. Generate new secret
new_secret=$(openssl rand -hex 32)
# 2. Update Railway
railway variables set SECRET_KEY=$new_secret
# 3. Update Cloudflare
echo "$new_secret" | wrangler secret put SECRET_KEY
# 4. Update GitHub
gh secret set SECRET_KEY -b"$new_secret"
# 5. Update local .env
sed -i '' "s/SECRET_KEY=.*/SECRET_KEY=$new_secret/" .env
# 6. Verify
railway variables | grep SECRET_KEY
```
---
## Emergency Procedures
### Complete System Restart
```bash
# 1. Kill all local services
pkill -f "blackroad-"
# 2. Stop Docker containers
docker-compose down
# 3. Wait for graceful shutdown
sleep 5
# 4. Pull latest code
cd ~/blackroad-sandbox
git pull origin main
# 5. Install dependencies
pip3 install -r requirements.txt
# 6. Restart Docker
docker-compose up -d
# 7. Start local services
./start-all.sh
# 8. Verify everything
./br health
```
### Emergency Rollback
```bash
# 1. Railway rollback
railway rollback --service api-gateway
# 2. Cloudflare rollback
wrangler pages deployment list --project-name=blackroad-io
wrangler pages deployment rollback [deployment-id]
# 3. Vercel rollback
vercel ls
vercel rollback [deployment-url]
# 4. Verify all
./br health
```
### Quick Health Check
```bash
# Check all critical endpoints
endpoints=(
"http://localhost:8000/health"
"https://api.blackroad.io/health"
"https://blackroad.io/"
)
for endpoint in "${endpoints[@]}"; do
echo "Testing $endpoint..."
curl -sf "$endpoint" && echo "✅" || echo "❌"
done
```
---
## Template: Custom Command Block
```bash
# [Step 1: Description]
command1 arg1 arg2
# [Step 2: Description]
command2 arg1 arg2
# [Step 3: Verification]
command3 arg1 arg2
```
---
## Copyright
```
# ============================================================================
# BlackRoad OS - Proprietary Software
# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
# All Rights Reserved.
# ============================================================================
```