Deploy
Anywhere

Architecture Overview

# Create a new Fly app
fly apps create warp-cluster

# Create volumes in each region
fly volumes create warp_data --region ams --size 10  # Amsterdam (EU)
fly volumes create warp_data --region iad --size 10  # Virginia (US)
fly volumes create warp_data --region sin --size 10  # Singapore (APAC)

# Deploy machines to each region
fly machine run . --region ams --volume warp_data:/data
fly machine run . --region iad --volume warp_data:/data
fly machine run . --region sin --volume warp_data:/data

Warp nodes automatically discover each other via Fly's internal DNS. No manual seed configuration needed.

# fly.toml
app = "warp-cluster"
primary_region = "iad"

[env]
  WARP_PORT = "9090"
  WARP_DATA_DIR = "/data"
  WARP_SHARDS = "16"
  # Enable DNS-based cluster discovery
  WARP_CLUSTER_DNS = "warp-cluster.internal"

[mounts]
  source = "warp_data"
  destination = "/data"

[[services]]
  internal_port = 9090
  protocol = "tcp"

  [[services.ports]]
    port = 9090

With DNS clustering, just use Warp.open() — nodes discover each other automatically.

import { Warp } from '@geeksquad/warp'

// Open spawns an embedded Warp server that auto-clusters via DNS
// WARP_CLUSTER_DNS is picked up from the environment (fly.toml)
const warp = await Warp.open({
  dataDir: '/data',  // Fly volume mount point
})

// That's it! The server joins the cluster automatically.
// Entity IDs with region prefixes route to the correct node.

// Create EU user → data stays in Amsterdam
const entity = warp.entity('eu/user/hans')
await entity.append('UserCreated', {
  name: 'Hans Schmidt',
  email: 'hans@example.de',
})

// Credit the account
await entity.append('Credited', { amount: 1000 }, { aggregate: 'Account' })

// Read state
const state = await entity.get('Account')

// Clean shutdown
await warp.close()

Add more machines and shards rebalance automatically. No code changes needed.

# Scale up — add another machine in each region
fly machine run . --region ams --volume warp_data:/data
fly machine run . --region iad --volume warp_data:/data

# The new machines:
# 1. Query DNS and discover existing nodes
# 2. Join the cluster automatically
# 3. Receive shards via live rebalancing
# 4. Start serving traffic immediately

# Scale down — remove a machine
fly machine stop <machine-id>

# Remaining nodes detect the departure and
# redistribute shards among themselves

Deploy multiple machines per region for automatic failover. Replicas sync asynchronously with zero latency impact.

# Deploy 2 machines per region for HA (leader + replica)
fly scale count 2 --region ams
fly scale count 2 --region iad
fly scale count 2 --region sin

# Or deploy 3 for quorum-based leader election
fly scale count 3 --region ams

# Enable HA + HyperMode in fly.toml
[env]
  WARP_MODE = "hyper"           # ETS caching, async SQLite flush
  WARP_HA_MODE = "replicated"
  WARP_HA_REPLICAS = "2"
  WARP_CLUSTER_DNS = "${FLY_APP_NAME}.internal"
  WARP_NODE_NAME = "warp_${FLY_MACHINE_ID}@${FLY_APP_NAME}.internal"
  WARP_COOKIE = "your_secret_cookie_here"  # REQUIRED: min 16 chars

import { Warp } from '@geeksquad/warp'

const warp = await Warp.open({ dataDir: '/data' })

// Check local node health
const health = await warp.health()
console.log(health)
// {
//   overall: 'healthy',
//   cluster: { nodes: 3, shards: 16 },
//   local: { shards: 6, events: 142857 }
// }

// List all nodes in the cluster
const cluster = await warp.clusterStatus()
// { localNode: '...', nodes: ['warp@...', ...], shardCount: 16 }

Summary