---
title: How to deploy SIE
description: Run SIE as a single Docker server or as a Kubernetes cluster with gateway, config service, NATS, and GPU worker pods.
canonical_url: https://superlinked.com/docs/deployment
last_updated: 2026-08-08
---

SIE has two deployment paths. Use Docker for a single `sie-server` with no external SIE services. Use Kubernetes when you need the clustered runtime: `sie-gateway`, `sie-config`, NATS JetStream, and GPU worker pods. Each worker pod runs the SIE server sidecar beside the Python `sie-server` adapter container.

---

## Which Deployment Path Should I Use?

**Use Docker if:**
- You are running on a single server or VM
- You are in development or running a low-traffic service
- You want the simplest possible setup

**Use Kubernetes if:**
- You need horizontal scaling or autoscaling to zero
- You need high availability across multiple nodes
- You are deploying on GCP, AWS, or Azure with GPU node pools

| | Docker | Kubernetes |
|---|---|---|
| Setup time | Minutes | Hours |
| Scaling | Manual | Automatic |
| High availability | No | Yes |
| Scale-to-zero | No | Yes |
| Best for | Dev, single-server | Production, high traffic |

See [Kubernetes on GCP](https://superlinked.com/docs/deployment/cloud-gcp/), [Kubernetes on AWS](https://superlinked.com/docs/deployment/cloud-aws/), and [Kubernetes on Azure](https://superlinked.com/docs/deployment/cloud-azure/) for cloud-specific guides.

---

## Getting Started With Docker

The fastest way to run SIE is a single `docker run`:

```bash
# CPU only
docker run -p 8080:8080 ghcr.io/superlinked/sie-server:latest-cpu-default

# With GPU (recommended)
docker run --gpus all -p 8080:8080 ghcr.io/superlinked/sie-server:latest-cuda12-default
```

The server starts on port 8080. Models load on first request with no pre-configuration needed.

### Common Options

```bash
# Custom port
docker run --gpus all -p 3000:8080 ghcr.io/superlinked/sie-server:latest-cuda12-default

# Specific models only (faster startup)
docker run --gpus all -p 8080:8080 ghcr.io/superlinked/sie-server:latest-cuda12-default \
  serve -m BAAI/bge-m3,BAAI/bge-reranker-v2-m3

# Persistent model cache (skip re-downloads)
docker run --gpus all -p 8080:8080 \
  -v sie-hf-cache:/app/.cache/huggingface \
  ghcr.io/superlinked/sie-server:latest-cuda12-default

# Different bundle (e.g. SGLang backend for large LLM embeddings)
docker run --gpus all -p 8080:8080 ghcr.io/superlinked/sie-server:latest-cuda12-sglang
```

See the full [Docker deployment guide](https://superlinked.com/docs/deployment/docker/).

---

## What Hardware Does SIE Need?

### Minimum Specs

| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 8GB | 16GB+ |
| GPU | Optional | Any NVIDIA with 16GB+ VRAM |
| Disk | 20GB | 100GB+ for model cache |

### GPU Recommendations by Workload

| GPU | VRAM | Best for |
|---|---|---|
| T4 | 16GB | Development, light production |
| L4 | 24GB | Standard production (recommended starting point) |
| A10 | 24GB | Standard production on Azure (its closest L4-class size) |
| A100 40GB | 40GB | High-throughput or large model serving |
| A100 80GB | 80GB | 7B+ parameter models |

See [Hardware and Capacity](https://superlinked.com/docs/deployment/resources/) for full sizing guidance.

---

## When Should I Move to Kubernetes?

Move from Docker to Kubernetes when you need:

- **Autoscaling** to handle traffic spikes by spinning up additional workers
- **Scale-to-zero** to save costs by scaling down during idle periods
- **High availability** with multiple replicas to survive node failures
- **Multi-region** deployment to serve users in different geographies

Note: Kubernetes clusters with scale-to-zero have cold start times of 3 to 7 minutes. Use `wait_for_capacity=True` in the Python SDK (or `waitForCapacity: true` in TypeScript) to handle this gracefully. See [Scale-from-Zero and Autoscaling](https://superlinked.com/docs/deployment/autoscaling/).

---

## Kubernetes Cluster Prerequisites

These requirements apply to any Kubernetes install path. The external Terraform modules ([terraform-google-sie](https://github.com/superlinked/terraform-google-sie), [terraform-aws-sie](https://github.com/superlinked/terraform-aws-sie), [terraform-azure-sie](https://github.com/superlinked/terraform-azure-sie)) provision a cluster that satisfies the cluster-level items below. Account-level prerequisites (quota, IAM, API enablement) still apply, see each cloud page. Operators using `helm install` against an existing cluster must confirm each item first.

### Cluster

- **Kubernetes 1.29 or newer.** Older versions are untested.
- **Worker nodes with NVIDIA GPUs** (L4, A100 40GB, or A100 80GB). CPU-only worker pools exist for local testing but are not a supported production target.
- **NVIDIA device plugin installed** and exposing `nvidia.com/gpu` as a schedulable resource. GKE ships this on GPU node pools automatically; EKS and AKS do not (the Terraform modules install it via Helm).
- **Node disk of at least 350Gi** per GPU node for production. Workers cache models in an `emptyDir` capped at 300Gi via `workers.common.cacheStorageSize: 300Gi` in the Helm values (no PVC, no storage class needed for the cache itself). Node disk sizing is the operator's responsibility: check the GPU-node disk size in your cluster or in the external Terraform module you use, and raise it for production so the node disk can hold the cache plus images and system overhead.

### In-cluster components

- **Ingress controller.** The chart defaults to `ingressClassName: nginx`. Install ingress-nginx if you plan to expose the gateway publicly. Port-forward works for smoke tests and internal-only setups.
- **cert-manager** (optional). Required only if you want the chart to issue Let's Encrypt certificates via HTTP-01. BYO TLS via a `kubernetes.io/tls` Secret is also supported and is the default.
- **Storage class.** Only matters if you enable the `sie-config` PVC (1Gi, default off). The cluster default class is fine.
- **KEDA, Prometheus, Loki, Alloy, DCGM Exporter.** Packaged as optional sub-charts (`keda.install=true`, `kube-prometheus-stack.install=true`, etc.). Skip them for a minimal smoke test; enable for autoscaling and observability.

### Cluster identity

- **Workload Identity (GCP and Azure) or IRSA (AWS)** bound to a service account named `sie-server` in the SIE release namespace. This is how worker pods read the model cache bucket (GCS, S3, or Azure Blob Storage) without static credentials. The external Terraform modules create and bind this for you.

### Network egress

The cluster must reach:

- `ghcr.io` for chart images (`sie-gateway`, `sie-server`, `sie-server-sidecar`, `sie-config`) and the OCI chart itself
- `huggingface.co` for model weights on first request (unless you pre-populate a cluster cache bucket with standard tools such as `aws s3 sync` or `gsutil rsync` and point `workers.common.clusterCache.url` at it, as described in the [offline guide](/docs/deployment/offline/))

Air-gapped environments must mirror both registries and configure `workers.common.clusterCache.url` to a pre-populated S3, GCS, or Azure Blob location.

### Tokens and secrets

- **`HF_TOKEN`** required for gated HuggingFace models (e.g. `google/embeddinggemma-300m`, `naver/splade-v3`). Optional for the `BAAI/bge-m3` smoke test.

For cloud-account-level requirements (GCP project, GPU quotas, IAM roles, API enablement), see the **Prerequisites** section on the [GCP](/docs/deployment/cloud-gcp/), [AWS](/docs/deployment/cloud-aws/), or [Azure](/docs/deployment/cloud-azure/) page.

---

## Frequently Asked Questions

**Can SIE run without a GPU?**
Yes. SIE runs on CPU and works well for development and low-traffic workloads. For production inference at scale, a GPU is strongly recommended, especially for batch encoding. See [Hardware and Capacity](https://superlinked.com/docs/deployment/resources/).

**How do I monitor a SIE deployment?**
SIE exposes Prometheus metrics and structured logs. See [Monitoring and Observability](https://superlinked.com/docs/deployment/monitoring/) for dashboards, alerting, and log configuration.

**How do I tune SIE for better performance?**
The main levers are batch size, worker concurrency, and model preloading. See [Performance Tuning](https://superlinked.com/docs/deployment/tuning/) for a step-by-step guide.

**How do I upgrade SIE without downtime?**
See the [Upgrade Runbook](https://superlinked.com/docs/deployment/upgrades/) for rolling upgrade procedures on both Docker and Kubernetes.

**Is there a managed cloud option?**
Superlinked offers managed SIE deployments for teams that do not want to manage infrastructure themselves. [Contact us](https://superlinked.com/) to learn more.