Xuell Infra

Xuell Infra is a local deployment console for shipping Git repositories into Docker containers, routing them through Caddy, and monitoring live logs from a React frontend.

Architecture

• frontend/: React + Vite UI for creating and managing deployments
• api/: Express + TypeScript API that orchestrates clone/build/run/route operations
• api/deployments.db: SQLite database for deployment metadata
• api/logs/: Per-deployment log files streamed over Server-Sent Events
• Caddyfile: Base Caddy config (admin API enabled, readiness endpoint)

Key Features

• Create deployments from a Git URL
• Live status pipeline: pending -> building -> deploying -> running (or failed/stopped)
• Stop and delete deployment actions
• Environment variable injection for runtime containers
• Encrypted secret storage at rest (AES-256-GCM)
• Live log streaming from backend to frontend

Prerequisites

Install these tools locally:

• Node.js 20+
• npm
• Docker
• Git
• Caddy v2
• Railpack CLI (used by the build pipeline)

Also create the Docker network used by deployed containers:

docker network create brimble

Environment Variables

The API supports these optional environment variables:

• BRIMBLE_ENCRYPTION_KEY: Secret used to derive encryption key for env vars
• CADDY_ADMIN_URL: Caddy admin endpoint (default: http://localhost:2019)

Example:

export BRIMBLE_ENCRYPTION_KEY="replace-with-a-strong-secret"
export CADDY_ADMIN_URL="http://localhost:2019"

Local Development

1. Start Caddy

From project root:

caddy run --config ./Caddyfile

2. Start API

cd api
npm install
npx tsx src/index.ts

API runs on http://localhost:3001.

3. Start Frontend

In a new terminal:

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173 and proxies /deployments to the API.

Build for Production

Frontend:

cd frontend
npm run build

API Endpoints

Base path: /deployments

• POST /: Create a deployment
• GET /: List deployments
• GET /:id: Get one deployment
• GET /:id/logs: Stream logs via SSE
• POST /:id/stop: Stop a deployment
• DELETE /:id: Delete a deployment and related artifacts

Create Deployment Request

{
  "git_url": "https://github.com/owner/repo",
  "name": "my-app",
  "env_vars": {
    "NODE_ENV": "production",
    "API_KEY": "secret-value"
  }
}

Deployment Pipeline

For each deployment:

1. Clone repository to a temp directory
2. Build image with Railpack
3. Start container on Docker network brimble
4. Register Caddy reverse-proxy route for <id>.localhost
5. Persist state and stream logs

Notes

• Secrets are masked in API responses and frontend display.
• Deleting a deployment removes DB row, Docker image (if present), container (if present), Caddy route, and log file.
• Existing databases are migrated at startup to include env_secrets if missing.