Set up Content Replication between Backstage servers

The Replicate feature keeps project files and media assets in sync across several Backstage machines over the network. One machine is the Primary — the authoritative source — and one or more are Replicators, which pull updates from it.

Typical uses: a hot standby running alongside the Primary, identical content on several servers in parallel, or pushing a show to a remote venue without transferring files by hand.

How it works

The Primary exposes the current project and assets over HTTP. When something changes — a project is saved, an asset imported, an asset file overwritten on disk — it notifies every connected Replicator over a persistent WebSocket. Each Replicator downloads only the files that actually changed (compared by file size and modification time) and reloads the project once the sync completes.

Before you start

• All machines are on the same trusted network (replication traffic is unencrypted)
• Backstage is installed and running on every machine
• You know the Primary's IP address

Steps

1. Set the project directory

Replication reads and writes project files from a dedicated directory, separate from the system save path. Set it on every machine — Primary and Replicators alike.

1. Open Settings ▸ Role.

2. Click the Saves button and choose the folder where your projects live.

3. Confirm the path shown next to the button is correct. If the folder does not exist on this machine, a Path does not exist warning appears — create the folder first or choose an existing one.

2. Configure the Primary

Open Settings ▸ Role and set Role to Primary. No other configuration is needed — the HTTP server that powers replication starts alongside Backstage.

While content is being prepared, tick Block Replicators to prevent Replicators from pulling a half-finished state. Clear it when you are ready.

The Replicated by list appears once at least one Replicator is connected. Hover an entry for the IP address and the time of the last completed sync.

3. Configure each Replicator

1. Open Settings ▸ Role.

2. Set Role to Backup.

3. Enter the Primary's IP address in Primary IP, for example 192.168.1.100. You can also expand Discovered on network and select it from the list of online Backstage machines.

4. Choose a Replication scope — see below.

5. Confirm the Saves path points to the folder where this machine should store replicated projects.

6. Restart Backstage. The Replicator connects to the Primary and begins syncing.

4. Run the first sync

After the Replicator has restarted and connected, click Sync Now for the initial pull. Wait for Status: idle, then confirm the project and asset files are present locally.

For ongoing sync, set Sync Mode to Event-driven (the default). In this mode, saving a project or importing an asset triggers a sync automatically. Manual mode waits for an explicit Sync Now click or a trigger from the Replicator node in the Node Editor.

Replication scopes

The scope decides which files on the Primary are offered for download. Set it under Settings ▸ Role ▸ Replication scope on the Replicator.

For Mirror folder, add the absolute path(s) on the Primary. For Mirror drive, enter the letter alone — D, not D:.

Mirror drive and Mirror folder scopes can optionally remove files on the Replicator that no longer exist on the Primary. Tick Delete stale files to enable this. By default, deleted files are moved to a quarantine folder and kept for 30 days before being purged. A safety cap prevents runaway deletion — if a sync would remove more files than the configured maximum, deletion is skipped entirely and a sync error is raised.

Authentication

Replication uses HTTP Basic authentication. The credentials configured on the Replicator must match those on the Primary. The defaults are admin / admin.

Checking the status

The top bar shows a replicator icon when the machine is configured as a Replicator. Green means connected and idle; a spinning icon means syncing; red means the Primary is unreachable or the last sync failed.

Under Settings ▸ Role the status line shows Status: idle when connected with nothing in progress, or the current sync progress.

The Log window records every file downloaded and sync completion:

ReplicatorManager: connected to primary WebSocket
ReplicatorManager: full sync started
ReplicatorManager: asset updated - clip.mp4 (1/1 files)
ReplicatorManager: sync complete: 1 updated, 0 failed

If the connection drops, the Replicator retries automatically with increasing backoff up to thirty seconds. No intervention is needed.

Using the Replicator node

The Replicator node (System category) brings replication into show logic. It has two inputs and four outputs:

• triggerSync (input, Bang) — fire to start a sync.

• getPrimaryStatus (input, Bang) — fire to poll whether the Primary is reachable.

• isPrimaryAlive (output, Int) — 1 if the Primary responds, 0 if unreachable.

• syncComplete (output, Bang) — fires when a sync finishes.

• syncProgress (output, Float) — progress of the current sync.

• serverRole (output, String) — the machine's current role.

Chain syncComplete before a sequence start so content is always fresh before playback begins. Use isPrimaryAlive for a fallback sequence that plays local content when the Primary goes offline.

Known limitations

• One-way sync only — Primary → Replicator. Local edits on a Replicator are overwritten on the next sync.

• No selective exclusion — file types or paths cannot be excluded within a scope. Use Active assets to limit what is synced.

• No TLS — traffic is unencrypted. Use a trusted internal network.

• Follower role not yet implemented — the option is visible in Settings but disabled. Only Backup is functional.

• File locking — if Windows holds a file open (a virus scan, an Explorer preview), the replacement is queued and retried on the next sync. Nothing is lost.

Common Mistakes

• Projects replicate to the wrong folder after an update — the replication project directory is now separate from the system save path. Set Settings ▸ Role ▸ Saves on every machine to match the folder your projects live in.

• Changed the wrong Saves setting — Settings ▸ Paths ▸ Saves is the general file-dialog path and does not affect replication. The replication directory is under Settings ▸ Role ▸ Saves.

• Nothing syncs after setting Role to Backup — the setting takes effect only after a restart.

• Edits made on a Replicator disappear — sync is one-way and the Primary always wins. Make changes on the Primary.

• Replicators sit idle during preparation — Block Replicators is still set on the Primary from an earlier maintenance window.

Tips

• A relative Saves path (the default) resolves next to the Backstage executable. For portable setups this is convenient — for permanent installations, set an absolute path so the location is explicit.

• For the initial sync of a large media library, consider copying files by hand first, then enabling replication. The Replicator compares each file by size and modification time and skips anything that already matches, so a pre-seeded machine syncs in seconds.

• Use the Replicator node's isPrimaryAlive output to build a failover: when the Primary drops off the network, switch to a locally cached sequence.

• Project backup files are excluded from replication, so backup history does not consume network bandwidth.

Related

Node Editor Window — the Node Editor, where the Replicator node lives

Settings — full Settings reference