blackroad-operating-system/templates/minimal-service/README.md

BlackRoad OS - Minimal Service Template

A production-ready FastAPI service template that implements the BlackRoad OS syscall API specification.

Features

✅ Core Endpoints:

• / - Hello World landing page (HTML)
• /health - Basic health check (required by Railway)
• /version - Version information

✅ Syscall API Endpoints (BlackRoad OS standard):

• /v1/sys/identity - Complete service identity
• /v1/sys/health - Detailed health metrics
• /v1/sys/version - Extended version info
• /v1/sys/config - Service configuration

✅ Additional Features:

• CORS middleware
• Custom error handlers (404, 500)
• OpenAPI documentation (/api/docs, /api/redoc)
• Railway deployment support
• Environment-based configuration
• Startup/shutdown hooks

Usage

1. Local Development

# Install dependencies
pip install fastapi uvicorn

# Set environment variables
export SERVICE_NAME="blackroad-os-example"
export SERVICE_ROLE="example"
export ENVIRONMENT="development"
export PORT=8000

# Run the service
python main.py

Visit: http://localhost:8000

2. Deploy to Railway

# 1. Copy this template to your satellite repo
cp templates/minimal-service/main.py /path/to/satellite-repo/

# 2. Create Dockerfile
cat > Dockerfile <<EOF
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "\${PORT:-8000}"]
EOF

# 3. Create requirements.txt
cat > requirements.txt <<EOF
fastapi==0.104.1
uvicorn[standard]==0.24.0
python-multipart==0.0.6
EOF

# 4. Push to satellite repo
git add .
git commit -m "Add minimal service implementation"
git push origin main

# Railway will automatically deploy

3. Configure Environment Variables (Railway)

In Railway dashboard, set:

SERVICE_NAME=blackroad-os-docs
SERVICE_ROLE=docs
ENVIRONMENT=production
ALLOWED_ORIGINS=https://blackroad.systems,https://api.blackroad.systems
CLOUDFLARE_URL=https://docs.blackroad.systems

Environment Variables

Variable	Required	Default	Description
SERVICE_NAME	No	blackroad-os-service	Full service name
SERVICE_ROLE	No	unknown	Service role (docs, web, api, etc.)
SERVICE_VERSION	No	1.0.0	Service version
ENVIRONMENT	No	development	production or development
PORT	No	8000	Port to run on
ALLOWED_ORIGINS	No	*	CORS allowed origins (comma-separated)
CLOUDFLARE_URL	No	-	Public Cloudflare URL
RAILWAY_STATIC_URL	Auto	-	Provided by Railway
RAILWAY_GIT_COMMIT_SHA	Auto	-	Provided by Railway

Testing

# Test health endpoint
curl http://localhost:8000/health

# Test version endpoint
curl http://localhost:8000/version

# Test identity (syscall API)
curl http://localhost:8000/v1/sys/identity

# Test detailed health (syscall API)
curl http://localhost:8000/v1/sys/health

# View API docs
open http://localhost:8000/api/docs

Customization

Add Custom Endpoints

@app.get("/api/custom")
async def custom_endpoint():
    """Your custom endpoint"""
    return {"message": "Custom data"}

Add Static File Serving

from fastapi.staticfiles import StaticFiles

# Mount static files
app.mount("/static", StaticFiles(directory="static"), name="static")

Add Database Connection

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession

# Add to startup event
@app.on_event("startup")
async def startup_event():
    global engine
    database_url = os.getenv("DATABASE_URL")
    engine = create_async_engine(database_url)

Add Health Checks

@app.get("/v1/sys/health")
async def sys_health():
    checks = {
        "database": await check_database(),
        "redis": await check_redis(),
        "external_api": await check_external_api()
    }

    all_healthy = all(c["status"] == "ok" for c in checks.values())

    return {
        "status": "healthy" if all_healthy else "degraded",
        "checks": checks,
        ...
    }

Integration with BlackRoad OS

Service Registry

This template is compatible with the BlackRoad OS service registry (INFRASTRUCTURE.md).

Each service automatically reports its identity via /v1/sys/identity, which includes:

• DNS endpoints (Cloudflare, Railway, internal)
• Runtime information (host, port, uptime)
• Health status
• Capabilities

Inter-Service Communication

To call other services:

import httpx

# Call another BlackRoad service
async with httpx.AsyncClient() as client:
    response = await client.get(
        "http://blackroad-os-core.railway.internal:8000/v1/sys/identity"
    )
    core_identity = response.json()

RPC Support (Optional)

To add RPC support, implement /v1/sys/rpc:

@app.post("/v1/sys/rpc")
async def sys_rpc(request: Request):
    """Handle RPC calls from other services"""
    body = await request.json()
    method = body.get("method")
    params = body.get("params", {})

    # Route to method handler
    if method == "getStatus":
        result = await get_status()
    elif method == "getData":
        result = await get_data(params)
    else:
        return JSONResponse(
            status_code=404,
            content={"error": {"code": "METHOD_NOT_FOUND", "message": f"Method '{method}' not found"}}
        )

    return {"result": result}

Production Checklist

Before deploying to production:

• Set ENVIRONMENT=production
• Configure ALLOWED_ORIGINS (no wildcards)
• Set proper SERVICE_NAME and SERVICE_ROLE
• Add health check monitoring
• Enable structured logging
• Add error tracking (Sentry, etc.)
• Configure rate limiting
• Add authentication (if needed)
• Test all endpoints
• Verify CORS configuration
• Check Railway deployment logs
• Verify Cloudflare DNS routing

References

• Syscall API Spec: SYSCALL_API.md
• Service Registry: INFRASTRUCTURE.md
• DNS Configuration: infra/DNS.md
• Deployment Guide: docs/RAILWAY_DEPLOYMENT.md

---

Template Version: 1.0 Compatible with: BlackRoad OS v2.0 Last Updated: 2025-11-20