Overview

XReplicator has two separate backend choices:

• Metadata backend: SQLite or PostgreSQL
• Backup data backend: local disk or object storage

XReplicator does not require Kubernetes. It can run on VMs as a single-server or multi-server deployment, or as a cloud-agnostic backup platform in your Kubernetes cluster with Helm.

For marketing demos, production evaluation, MSP environments, and teams already using Kubernetes, lead with the Kubernetes + Helm deployment. It presents the complete platform as backup infrastructure that fits existing platform operations: frontend, backup-server, PostgreSQL, object storage, ingress, secrets, persistent storage, and upgrade controls.

Single-server deployments remain supported and useful. Treat them as the adoption ladder for labs, Community Edition, and smaller production sites.

Published Artifacts

Use these artifacts for container and Kubernetes deployments:

ghcr.io/xmigrate/xreplicator-backup-server:VERSION
ghcr.io/xmigrate/xreplicator-frontend:VERSION
oci://ghcr.io/xmigrate/charts/xreplicator-backup-server --version VERSION

The Helm chart is published as a GHCR OCI artifact. OCI charts do not use helm repo add or helm repo update. Use helm upgrade --install with the oci:// URL. If your organization mirrors the chart into a normal HTTP chart repository, use helm repo add, helm repo update, and the same values files shown below.

Common setup:

export VER=VERSION
export NAMESPACE=xreplicator
export RELEASE=xreplicator
export CHART=oci://ghcr.io/xmigrate/charts/xreplicator-backup-server
 
kubectl create namespace "$NAMESPACE"
 
kubectl -n "$NAMESPACE" create secret generic xreplicator-license \
  --from-file=license.json=/path/to/license.json
 
kubectl -n "$NAMESPACE" create secret generic xreplicator-tls \
  --from-file=tls.crt=/path/to/server.crt \
  --from-file=tls.key=/path/to/server.key \
  --from-file=ca.crt=/path/to/ca.crt

Optional GHCR login:

helm registry login ghcr.io

Upgrade any model by changing VER and running the same helm upgrade --install command again.

Configure PostgreSQL and Object Storage

Use the deployment surface you installed with:

• VM/systemd: edit /etc/xreplicator/server.yaml; see Backup Server Mode.
• Helm: edit your release values.yaml and run helm upgrade --install.
• Docker Compose: edit .env for bundled service credentials, or edit compose.yaml when pointing at external PostgreSQL or object storage.

Helm: Bundled PostgreSQL and MinIO

The chart can run PostgreSQL and MinIO inside the release:

server:
  metadataBackend: postgres
  storageBackend: object
 
postgres:
  enabled: true
  database: xreplicator
  username: xreplicator
  password: CHANGE_ME
  persistence:
    size: 100Gi
    storageClassName: fast-retain
 
minio:
  enabled: true
  rootUser: minioadmin
  rootPassword: CHANGE_ME
  persistence:
    size: 1Ti
    storageClassName: fast-retain
 
objectStorage:
  bucket: xreplicator-backups
  prefix: repo
  useSSL: false

Apply the change:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  -f values.yaml

Helm: External PostgreSQL

Create a secret for the PostgreSQL DSN:

kubectl -n "$NAMESPACE" create secret generic xreplicator-postgres \
  --from-literal=postgres-dsn='postgres://xreplicator:CHANGE_ME@postgres.example.com:5432/xreplicator?sslmode=require'

Point the chart at that secret:

server:
  metadataBackend: postgres
 
postgres:
  enabled: false
  dsnSecretName: xreplicator-postgres
  dsnSecretKey: postgres-dsn

Helm: External Object Storage

Create a secret for object storage credentials:

kubectl -n "$NAMESPACE" create secret generic xreplicator-object-storage \
  --from-literal=object-access-key='CHANGE_ME' \
  --from-literal=object-secret-key='CHANGE_ME'

Point the chart at the external object backend:

server:
  storageBackend: object
 
minio:
  enabled: false
 
objectStorage:
  provider: s3
  endpoint: s3.example.com
  bucket: xreplicator-backups
  prefix: repo
  useSSL: true
  accessKeySecretName: xreplicator-object-storage
  accessKeySecretKey: object-access-key
  secretKeySecretName: xreplicator-object-storage
  secretKeySecretKey: object-secret-key

Docker Compose: Bundled PostgreSQL and MinIO

For the bundled quickstart services, edit .env:

XREPLICATOR_VERSION=VERSION
POSTGRES_PASSWORD=CHANGE_ME
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=CHANGE_ME
XREPLICATOR_INTERNAL_SECRET=CHANGE_ME
XREPLICATOR_WEB_SESSION_SECRET=CHANGE_ME

Then restart:

docker compose up -d

Docker Compose: External PostgreSQL or Object Storage

When using external services, edit the backup-server.environment section in compose.yaml:

backup-server:
  environment:
    XREPLICATOR_POSTGRES_DSN: postgres://xreplicator:CHANGE_ME@postgres.example.com:5432/xreplicator?sslmode=require
    XREPLICATOR_STORAGE_BACKEND: object
    XREPLICATOR_OBJECT_PROVIDER: s3
    XREPLICATOR_OBJECT_ENDPOINT: s3.example.com
    XREPLICATOR_OBJECT_BUCKET: xreplicator-backups
    XREPLICATOR_OBJECT_PREFIX: repo
    XREPLICATOR_OBJECT_USE_SSL: "true"
    XREPLICATOR_OBJECT_ACCESS_KEY: CHANGE_ME
    XREPLICATOR_OBJECT_SECRET_KEY: CHANGE_ME

If you no longer use bundled PostgreSQL or MinIO, also remove those services from depends_on for backup-server.

Kubernetes + Helm: Recommended Production Path

XReplicator can be deployed on Kubernetes using the project-provided manifests or Helm chart. This is the preferred production packaging for platform demos, MSP deployments, GitOps environments, and teams that already operate workloads on Kubernetes.

Use Kubernetes packaging for:

• PostgreSQL + object storage single-server deployments.
• Multi-server PostgreSQL + object storage deployments.
• Environments that standardize on ingress, secrets, persistent volumes, rolling upgrades, image promotion, and GitOps.
• Sales engineering and production evaluation where a complete platform install is easier to explain than a manual single-host setup.

Helm Install

Create values-kubernetes.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 2
 
server:
  metadataBackend: postgres
  storageBackend: object
  activeActive: true
 
postgres:
  enabled: true
 
minio:
  enabled: true

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-kubernetes.yaml
 
kubectl -n "$NAMESPACE" get pods
kubectl -n "$NAMESPACE" get svc

Pros

• Best enterprise and MSP operating model.
• Helm values provide a repeatable install and upgrade path.
• Ingress, services, secrets, and persistent volumes are managed consistently.
• PostgreSQL and object storage can be bundled for evaluation or connected to external managed services.
• Cleanest path from single-server production to multi-server HA.

Cons

• Requires Kubernetes operational skills.
• More moving parts than a single-host Community deployment.
• Production use still needs monitoring, backup policies, retention policies, and tested restore procedures.

Single Server: SQLite + Local Disk

This is the simplest deployment. One backup server owns both the SQLite metadata store and local repository storage.

Helm Install

Create values-sqlite-local.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 1
 
server:
  metadataBackend: sqlite
  storageBackend: local
  activeActive: false
 
postgres:
  enabled: false
 
minio:
  enabled: false

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-sqlite-local.yaml

Pros

• Lowest operational complexity.
• No external database required.
• Fast local restore path when storage is healthy.
• Good default for small single-tenant deployments.

Cons

• One server and one local volume are the failure domain.
• Repository operations grow with backup history.
• No active-active failover.
• Scaling is limited by one server’s CPU, memory, network, and disk IOPS.

Single Server: SQLite + Object Storage

Use this when you want the simple SQLite operational model but want backup content in S3, GCS, Azure Blob, or another object backend.

Helm Install

Create values-sqlite-object.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 1
 
server:
  metadataBackend: sqlite
  storageBackend: object
  activeActive: false
 
postgres:
  enabled: false
 
minio:
  enabled: true

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-sqlite-object.yaml

Pros

• Keeps metadata operations simple.
• Moves durable backup content outside the server disk.
• Object storage can provide versioning, encryption, lifecycle controls, and multi-AZ durability.
• Useful when the server disk should not be the primary long-term backup store.

Cons

• SQLite metadata still belongs to one active server.
• Metadata remains the failover bottleneck.
• Restores may depend on object-store latency and egress.
• Not a multi-server active-active topology.

Single Server: PostgreSQL + Local Disk

Use this as a migration step when operational state should move out of local SQLite before backup data moves to object storage.

Helm Install

Create values-postgres-local.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 1
 
server:
  metadataBackend: postgres
  storageBackend: local
  activeActive: false
 
postgres:
  enabled: true
 
minio:
  enabled: false

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-postgres-local.yaml

Pros

• Better inventory, reporting, and operational history.
• Better base for reporting, tenancy, audit, and operational state.
• Easier migration path toward PostgreSQL plus object storage.
• Keeps backup reads and writes local.

Cons

• Local repository storage is still one server’s storage failure domain.
• Multiple active servers cannot safely share that local filesystem repository.
• PostgreSQL adds an external service to operate.
• Does not solve storage capacity or repository-node failure by itself.

Single Server: PostgreSQL + Object Storage

This is the strongest single-server production model and the best stepping stone toward HA. PostgreSQL owns durable metadata and object storage owns durable backup content.

Helm Install

Create values-postgres-object.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 1
 
server:
  metadataBackend: postgres
  storageBackend: object
  activeActive: false
 
postgres:
  enabled: true
 
minio:
  enabled: true

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-postgres-object.yaml

Pros

• Separates server compute from durable metadata and content storage.
• Supports durable operational history.
• Object storage provides scalable durable backup content.
• Cleanest path to a future multi-server deployment.

Cons

• More services to deploy and monitor.
• Restore performance depends on object-store latency and network throughput.
• Requires clear backup-completion policy before a restore point is marked available.

Multi Server: PostgreSQL + Object Storage

This is the recommended active-active cell target. Agents connect through a stable endpoint or load balancer. PostgreSQL coordinates shared operational state, while object storage is the durable backup data store.

Helm Install

Create values-multiserver-postgres-object.yaml:

fullnameOverride: xreplicator
 
image:
  tag: "VERSION"
 
frontend:
  image:
    tag: "VERSION"
 
replicaCount: 2
 
server:
  metadataBackend: postgres
  storageBackend: object
  activeActive: true
 
postgres:
  enabled: true
 
minio:
  enabled: true

Install or upgrade:

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f values-multiserver-postgres-object.yaml

Pros

• Multiple active backup servers.
• PostgreSQL coordinates backup, restore, DR, and maintenance activity.
• Object storage allows restore activity to continue from any healthy server.
• Better failure isolation and scale-out than a larger single server.

Cons

• Highest operational complexity of the supported models.
• Requires strict operational ownership and failover rules.
• Needs monitoring for backup servers, PostgreSQL, object storage, restore activity, DR activity, and maintenance work.

What Not To Run

Recommendation

Lead with Kubernetes + Helm when the goal is a production platform, MSP deployment, or sales/demo environment. Use the smaller models when the goal is local simplicity or a constrained single-server install.

The five combinations above are valid documentation targets. The important boundary is that only PostgreSQL plus object storage should be presented as the multi-server active-active model.