Skip to Content
Getting StartedQuickstart

Quickstart gets a working backup platform running first. After the platform is up, install agents from Installation and point them at the backup endpoint from this page.

Before You Start

Agents

  • Linux kernel 4.7+ for eBPF change tracking
  • Ubuntu 20.04+ / Debian 10+ / RHEL 8+ / CentOS 8+ / Fedora
  • Windows 10/11 with Administrator access
  • Supported filesystems: NTFS, ext4, XFS

Server platform

  • Docker with Docker Compose, or a Kubernetes cluster with Helm 3
  • TCP 50051 reachable from agents to the backup server
  • TCP 3000 or an ingress route for the web UI
  • An XReplicator license file
  • TLS certificate, key, and CA file for backup-server gRPC
  • Privileged backup-server runtime with host /dev access. Prepare/mount restore uses dynamically-created loop devices such as /dev/loopN.

Published artifacts:

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

Use Docker Compose for a single-host trial. Use Helm when you want the frontend, backup-server, PostgreSQL, and object storage managed inside a Kubernetes cluster.

Option 1: Docker Compose Quickstart

This starts the frontend, backup-server, PostgreSQL, and MinIO on one Docker host.

The Compose package runs the backup server as a privileged container with host /dev mounted so prepare/mount restore can create loop devices.

1. Download the Compose files

mkdir -p xreplicator-compose
cd xreplicator-compose
 
curl -LO https://raw.githubusercontent.com/xmigrate/xreplicator/main/deploy/docker-compose/compose.yaml
curl -LO https://raw.githubusercontent.com/xmigrate/xreplicator/main/deploy/docker-compose/.env.example
cp .env.example .env

2. Add TLS and license files

mkdir -p tls license
 
openssl req -x509 -newkey rsa:4096 -nodes -days 365 \
  -keyout tls/tls.key \
  -out tls/tls.crt \
  -subj "/CN=backup-server.xmigrate.com" \
  -addext "subjectAltName=DNS:backup-server.xmigrate.com,DNS:backup-server,IP:127.0.0.1"
 
cp tls/tls.crt tls/ca.crt
cp /path/to/license.json license/license.json

3. Start XReplicator

docker compose up -d
docker compose ps

Services:

Frontend:      http://localhost:3000
Backup gRPC:   localhost:50051
Metrics:       http://localhost:9090
MinIO API:     http://localhost:9000
MinIO console: http://localhost:9001
PostgreSQL:    localhost:5432

4. Shut down the Docker quickstart

docker compose down
docker compose down -v

Option 2: Helm Quickstart

This starts XReplicator on Kubernetes with bundled PostgreSQL and MinIO.

The Helm chart enables restore host access by default. The backup-server pod runs privileged as root with host /dev mounted so losetup can expose dynamic /dev/loopN devices inside the container.

1. Set release values

export VER=VERSION
export NAMESPACE=xreplicator
export RELEASE=xreplicator
export CHART=oci://ghcr.io/xmigrate/charts/xreplicator-backup-server

GHCR publishes the chart as an OCI artifact, so helm repo add and helm repo update are not required. If your environment requires authentication for GHCR, log in first:

helm registry login ghcr.io

2. Create license and TLS secrets

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

3. Install with Helm

helm upgrade --install "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --create-namespace \
  --set fullnameOverride=xreplicator \
  --set image.tag="$VER" \
  --set frontend.image.tag="$VER" \
  --set replicaCount=1 \
  --set server.activeActive=false

4. Check the deployment

kubectl -n "$NAMESPACE" get pods
kubectl -n "$NAMESPACE" get svc

For local access without an ingress:

kubectl -n "$NAMESPACE" port-forward svc/xreplicator-frontend 3000:80
kubectl -n "$NAMESPACE" port-forward svc/xreplicator 50051:50051

Open http://localhost:3000.

5. Upgrade the Helm release

export VER=VERSION
 
helm upgrade "$RELEASE" "$CHART" \
  --version "$VER" \
  --namespace "$NAMESPACE" \
  --set fullnameOverride=xreplicator \
  --set image.tag="$VER" \
  --set frontend.image.tag="$VER"

Next Steps

Last updated on
IntroductionInstallation