Deployment Guide

# From the root of the repository
docker build -t topgun-server -f deploy/Dockerfile.server .

version: '3.8'

services:
  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    container_name: topgun-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres_password
      POSTGRES_DB: topgun
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  # TopGun Rust Server
  server:
    build:
      context: .
      dockerfile: deploy/Dockerfile.server
    container_name: topgun-server
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      RUST_LOG: topgun_server=info
      DATABASE_URL: postgres://postgres:postgres_password@postgres:5432/topgun
    restart: unless-stopped

volumes:
  postgres_data:

docker-compose up -d

# Production deployment with PostgreSQL persistence
# Currently requires embedding the server in a Rust application
# (production CLI binary with env var config is planned)
#
# The Rust server includes built-in production optimizations:
# - Tower middleware pipeline (LoadShed, Timeout, Metrics)
# - Automatic backpressure via bounded channel capacity
# - Configurable operation timeouts and concurrency limits
# - Prometheus metrics endpoint at /metrics
#
# Key configuration structs:
#   NetworkConfig  -- host, port, TLS, CORS, connection settings
#   ServerConfig   -- node_id, timeouts, concurrency, partitions
#
# For full configuration, see: /docs/reference/server

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: topgun-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres_password
      POSTGRES_DB: topgun
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  server:
    build:
      context: .
      dockerfile: deploy/Dockerfile.server
    container_name: topgun-server
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "443:443"       # HTTPS/WSS
      - "9443:9443"     # Cluster TLS
    environment:
      RUST_LOG: topgun_server=info
      TOPGUN_PORT: 443
      TOPGUN_CLUSTER_PORT: 9443
      DATABASE_URL: postgres://postgres:postgres_password@postgres:5432/topgun
      # TLS Configuration
      TOPGUN_TLS_ENABLED: "true"
      TOPGUN_TLS_CERT_PATH: /etc/topgun/tls/server.crt
      TOPGUN_TLS_KEY_PATH: /etc/topgun/tls/server.key
      TOPGUN_TLS_MIN_VERSION: TLSv1.3
      # Cluster TLS (mTLS)
      TOPGUN_CLUSTER_TLS_ENABLED: "true"
      TOPGUN_CLUSTER_TLS_CERT_PATH: /etc/topgun/tls/cluster.crt
      TOPGUN_CLUSTER_TLS_KEY_PATH: /etc/topgun/tls/cluster.key
      TOPGUN_CLUSTER_TLS_CA_PATH: /etc/topgun/tls/ca.crt
      TOPGUN_CLUSTER_MTLS: "true"
    volumes:
      - ./certs:/etc/topgun/tls:ro
    restart: unless-stopped

volumes:
  postgres_data:

# Create certs directory
mkdir -p certs

# Copy your certificates
cp /path/to/server.crt certs/
cp /path/to/server.key certs/
cp /path/to/ca.crt certs/

# For cluster mTLS (separate certs)
cp /path/to/cluster.crt certs/
cp /path/to/cluster.key certs/

# Start with TLS
docker-compose -f docker-compose.tls.yml up -d

apiVersion: v1
kind: Secret
metadata:
  name: topgun-tls
  namespace: topgun
type: kubernetes.io/tls
data:
  # Base64-encoded certificate and key
  tls.crt: LS0tLS1CRUdJTi...  # base64 -w0 server.crt
  tls.key: LS0tLS1CRUdJTi...  # base64 -w0 server.key
  ca.crt: LS0tLS1CRUdJTi...   # base64 -w0 ca.crt
---
# Create secret from files:
# kubectl create secret generic topgun-tls \
#   --from-file=tls.crt=./server.crt \
#   --from-file=tls.key=./server.key \
#   --from-file=ca.crt=./ca.crt \
#   -n topgun

apiVersion: apps/v1
kind: Deployment
metadata:
  name: topgun
  namespace: topgun
spec:
  replicas: 3
  selector:
    matchLabels:
      app: topgun
  template:
    metadata:
      labels:
        app: topgun
    spec:
      containers:
      - name: topgun
        image: topgun:latest
        ports:
        - containerPort: 443
          name: https
        - containerPort: 9443
          name: cluster
        env:
        - name: TOPGUN_PORT
          value: "443"
        - name: TOPGUN_CLUSTER_PORT
          value: "9443"
        - name: TOPGUN_TLS_ENABLED
          value: "true"
        - name: TOPGUN_TLS_CERT_PATH
          value: "/etc/topgun/tls/tls.crt"
        - name: TOPGUN_TLS_KEY_PATH
          value: "/etc/topgun/tls/tls.key"
        - name: TOPGUN_TLS_MIN_VERSION
          value: "TLSv1.3"
        - name: TOPGUN_CLUSTER_TLS_ENABLED
          value: "true"
        - name: TOPGUN_CLUSTER_TLS_CA_PATH
          value: "/etc/topgun/tls/ca.crt"
        - name: TOPGUN_CLUSTER_MTLS
          value: "true"
        volumeMounts:
        - name: tls-certs
          mountPath: /etc/topgun/tls
          readOnly: true
      volumes:
      - name: tls-certs
        secret:
          secretName: topgun-tls

# The Rust TopGun server does not support serverless edge deployment.
# The server is a long-running process that maintains in-memory state,
# WebSocket connections, and cluster membership.
#
# For serverless environments, deploy TopGun as a persistent service
# and connect from your edge functions via the TopGun client SDK.
#
# Recommended deployment modes:
#   - Docker container (see docker-compose example above)
#   - Kubernetes StatefulSet (see k8s example above)
#   - Any platform that supports long-running processes
#
# See the Server API reference for deployment options:
# /docs/reference/server

# AWS Lambda is not supported for the TopGun server.
# The Rust server requires persistent state and WebSocket connections.
#
# Deploy TopGun as an ECS/EKS service instead:
# - ECS Fargate with an Application Load Balancer (WebSocket support)
# - EKS with a StatefulSet for cluster deployments
#
# Your Lambda functions can connect as TopGun clients.
# See: /docs/reference/server

# Cloudflare Workers are not supported for the TopGun server.
# The Rust server requires persistent state and WebSocket connections.
#
# Deploy TopGun as a container or VM-based service.
# Your Cloudflare Workers can connect as TopGun clients.
# See: /docs/reference/server

import { HttpSyncProvider, SyncEngine } from '@topgunbuild/client';
import { HLC } from '@topgunbuild/core';
import { IDBAdapter } from '@topgunbuild/adapters';

const hlc = new HLC('client-1');
const provider = new HttpSyncProvider({
  url: 'https://your-api.vercel.app',
  clientId: 'client-1',
  hlc,
  authToken: 'your-jwt-token',
  syncMaps: ['todos'],
});

const engine = new SyncEngine({
  nodeId: 'client-1',
  connectionProvider: provider,
  storageAdapter: new IDBAdapter(),
});

import { AutoConnectionProvider, SyncEngine } from '@topgunbuild/client';
import { HLC } from '@topgunbuild/core';
import { IDBAdapter } from '@topgunbuild/adapters';

const hlc = new HLC('client-1');
const provider = new AutoConnectionProvider({
  url: 'https://your-api.vercel.app',
  clientId: 'client-1',
  hlc,
  authToken: 'your-jwt-token',
  maxWsAttempts: 3,
  syncMaps: ['todos'],
});

const engine = new SyncEngine({
  nodeId: 'client-1',
  connectionProvider: provider,
  storageAdapter: new IDBAdapter(),
});