Deployment

Deploy HX-SDP using Docker Compose. The stack consists of three services: HX-Gate (reverse proxy), HX-Engine (GPU compute), and Redis (shared state).

---

Prerequisites

• Docker Engine 24+ with Compose V2
• NVIDIA Container Toolkit (for GPU support)
• A valid Stripe account (if enabling billing)

Quick deploy

# Clone the repository
git clone https://github.com/tigantic/physics-os.git
cd physics-os

# Copy the environment template
cp deploy/hx-gate/.env.template .env

# Edit configuration
$EDITOR .env

# Start the stack
docker compose -f deploy/hx-gate/docker-compose.fleet.yml up -d

Docker Compose

The production Compose file defines three services:

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  gate:
    image: ghcr.io/tigantic/hx-gate:latest
    ports:
      - "8080:8080"
    environment:
      HX_GATE_ENGINE_SERVICE_KEY: ${HX_GATE_ENGINE_SERVICE_KEY}
      HX_GATE_REDIS_URL: redis://redis:6379/0
      HX_GATE_BILLING_ENABLED: ${HX_GATE_BILLING_ENABLED:-false}
      HX_GATE_CORS_ORIGINS: ${HX_GATE_CORS_ORIGINS:-}
      HX_GATE_STRIPE_SECRET_KEY: ${HX_GATE_STRIPE_SECRET_KEY:-}
      HX_GATE_STRIPE_PUBLISHABLE_KEY: ${HX_GATE_STRIPE_PUBLISHABLE_KEY:-}
      HX_GATE_STRIPE_WEBHOOK_SECRET: ${HX_GATE_STRIPE_WEBHOOK_SECRET:-}
    volumes:
      - ./tenants.json:/etc/hx-gate/tenants.json
      - gate_audit:/var/log/hx-gate
    depends_on:
      - redis

  engine:
    image: ghcr.io/tigantic/hx-engine:latest
    ports:
      - "8000:8000"
    environment:
      HOLONOMIX_API_KEYS: ${HX_GATE_ENGINE_SERVICE_KEY}
      HOLONOMIX_ADMIN_API_KEYS: ${HX_GATE_ENGINE_SERVICE_KEY}
      HOLONOMIX_STORE_ROOT: /var/lib/holonomix/data
      HOLONOMIX_REQUIRE_AUTH: "true"
    volumes:
      - engine_data:/var/lib/holonomix/data
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    depends_on:
      - redis

---

Service architecture

Internet
   │
   ▼
┌─────────┐     ┌─────────────┐     ┌───────┐
│ HX-Gate │────▶│  HX-Engine  │     │ Redis │
│  :8080  │     │    :8000    │     │ :6379 │
└─────────┘     └─────────────┘     └───────┘
  Reverse         GPU worker        Shared state
  proxy           (compute)         (rate limits,
  (auth,                             sessions)
   meter,
   audit)

• HX-Gate is stateless and horizontally scalable. Run multiple instances behind a load balancer.
• HX-Engine is GPU-bound. Scale vertically (more powerful GPU) or run multiple instances with data partitioning.
• Redis is optional for single-instance deployments (Gate falls back to in-memory state).

---

Environment file

Create an .env file (or use deploy/hx-gate/.env.template as a starting point):

# Required
HX_GATE_ENGINE_SERVICE_KEY=your-secret-service-key-min-32-chars

# Billing (optional)
HX_GATE_BILLING_ENABLED=false
HX_GATE_STRIPE_SECRET_KEY=
HX_GATE_STRIPE_PUBLISHABLE_KEY=
HX_GATE_STRIPE_WEBHOOK_SECRET=

# CORS (optional)
HX_GATE_CORS_ORIGINS=https://app.example.com

Service key security

The HX_GATE_ENGINE_SERVICE_KEY is the master credential. Use a cryptographically random string of at least 32 characters. Store it in a secrets manager, not in version control.

---

Initial tenant setup

Create a tenants.json file or use the admin API after startup:

# Create your first tenant
curl -X POST http://localhost:8080/gate/onboard/create \
  -H "Authorization: Bearer $HX_GATE_ENGINE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-org",
    "plan": "pro",
    "namespaces": ["default", "production"]
  }'

Save the returned api_key — it's shown once.

---

GPU configuration

The engine requires an NVIDIA GPU with CUDA support. Verify the GPU is accessible:

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

For multi-GPU hosts, specify which GPU the engine uses:

environment:
  CUDA_VISIBLE_DEVICES: "0"

---

Profiles

Pre-configured environment profiles are available in deploy/profiles/:

Profile	Use case
saas.env	Managed SaaS deployment with billing
enterprise.env	On-prem enterprise with auth, no billing
dev.env	Local development, relaxed settings

Load a profile:

docker compose -f deploy/hx-gate/docker-compose.fleet.yml \
  --env-file deploy/profiles/saas.env up -d

---

Health checks

After deployment, verify all services:

# Gate health
curl http://localhost:8080/health

# Engine health (via gate proxy)
curl http://localhost:8080/v1/health \
  -H "X-Api-Key: $TENANT_API_KEY"

# Direct engine health (internal network)
curl http://localhost:8000/health

---

Upgrades

# Pull latest images
docker compose -f deploy/hx-gate/docker-compose.fleet.yml pull

# Rolling restart
docker compose -f deploy/hx-gate/docker-compose.fleet.yml up -d

Data volumes (engine_data, redis_data, gate_audit) persist across upgrades.