DocsGuidesDeployment

Deployment Guide

Learn how to deploy the TopGun server to production using Docker, Docker Compose, or Kubernetes.

Docker

TopGun provides a standardized Dockerfile for building the server. It uses a multi-stage build process to ensure a small image size.

Building the Image

terminal 
# From the root of the repository
docker build -t topgun-server .

The Dockerfile handles:

  • Copying workspace package definitions
  • Installing dependencies via npm ci
  • Building all packages (core, server, adapters, etc.)
  • Exposing port 8080
  • Starting the server via npm run start:server

Docker Compose

For local development or simple deployments, you can use Docker Compose to run the TopGun Server alongside a PostgreSQL database.
docker-compose.yml 
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 Server
  server:
    build: .
    container_name: topgun-server
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      NODE_ENV: production
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: postgres_password
      DB_NAME: topgun
    restart: unless-stopped

volumes:
  postgres_data:

Running with Compose

terminal 
docker-compose up -d

Kubernetes (Helm)

For production Kubernetes clusters, a Helm chart is provided in deploy/k8s/chart.

Chart Structure

  • templates/statefulset.yaml- Manages the server pods (StatefulSet is recommended for stable network IDs)
  • templates/service.yaml- Exposes the HTTP/WebSocket API
  • templates/service-headless.yaml- Headless service for internal cluster discovery
  • values.yaml- Default configuration values

Deploying with Helm allows easy scaling of the server replicas. TopGun nodes automatically discover each other when running in the same cluster (configured via cluster.discovery).

TLS Configuration

For production deployments, enable TLS to encrypt all client and cluster communications.

Security Requirement

Always enable TLS in production. Without TLS, all data (including authentication tokens) is transmitted in plaintext and can be intercepted.

Docker Compose with TLS

docker-compose.tls.yml 
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: .
    container_name: topgun-server
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "443:443"       # HTTPS/WSS
      - "9443:9443"     # Cluster TLS
    environment:
      NODE_ENV: production
      TOPGUN_PORT: 443
      TOPGUN_CLUSTER_PORT: 9443
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: postgres_password
      DB_NAME: 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:

Before starting, create your certificates in the ./certs directory:

terminal 
# 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

Kubernetes TLS Secret

Store TLS certificates securely using Kubernetes Secrets.
k8s/tls-secret.yaml 
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

Kubernetes Deployment with TLS

k8s/deployment.yaml 
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

cert-manager Integration

For automatic certificate management, consider using cert-manager with Let’s Encrypt or your internal CA. See the Security Guide for detailed setup instructions.
Previous

Time-To-Live

Next Guide

Observability