Skip to content

ScaleTrade Backup Server Overview

The ScaleTrade Backup Server is a standalone remote receiver for backup artifacts produced by the ScaleTrade trading server. It is designed to run on a separate machine and store verified backup files outside the primary server filesystem.

The current implementation is an offsite backup transport component. It does not execute trades, serve client sessions, provide hot standby failover, or replicate live databases in real time. Its role is to receive completed backup artifacts from BackupManager, validate them, and store them in a predictable directory layout for disaster recovery workflows.

Connection Schema

flowchart LR
    A[Platform data stores] --> B[BackupManager]
    B --> C[Local backup catalog]
    B -->|Open TCP connection| D[backupserver endpoint]
    D --> E[Validate token and upload metadata]
    E --> F[Write temporary artifact]
    F --> G[Verify SHA-256 checksum]
    G --> H[Publish artifact to remote storage]
    H --> I[Write receipt]
    I -->|JSON response| B

The backup server does not initiate connections to the trading server. Connection direction is always from BackupManager to backupserver.

Role In The Backup Flow

BackupManager first creates a local backup run on the main trading server. After the local artifacts are created and validated, the manager can publish them to one or more enabled remote backup endpoints.

While the local backup and remote publish are running, the trading server publishes progress through the TCP/WS backup.progress channel and exposes the same snapshot through the GetBackupProgress TCP method. Remote transfer progress is reported as phase: "publish_remote" with remote_total and remote_done counters.

The remote publish flow is:

  1. The trading server creates a local backup run.
  2. Each participant artifact is validated locally by size, SHA-256, and integrity checks where applicable.
  3. The local run is published as completed or partial.
  4. BackupManager opens a TCP connection to the configured backup server.
  5. Artifacts are uploaded using the put_artifact wire protocol.
  6. The backup server verifies the payload SHA-256 before publishing the file.
  7. A receipt file is written next to every accepted artifact.

Remote upload is best effort. Network or backup server errors are logged on the main server, but they do not change the status of the local backup run.

Network Protocol

The backup server accepts TCP connections. Each upload uses one connection and contains:

  1. One JSON header line terminated by \n or \r\n.
  2. Exactly size bytes of binary payload.
  3. One JSON response line from the server.

Header version 1:

{
  "command": "put_artifact",
  "version": 1,
  "token": "secret",
  "run_id": "20260630-120000-123456",
  "participant": "trades",
  "file": "trades.snapshot",
  "size": 1048576,
  "sha256": "..."
}

Required fields:

Field Description
command Must be put_artifact.
version Protocol version. Current version is 1.
token Shared secret configured on the backup server.
run_id Backup run identifier generated by the trading server.
participant Logical backup participant, for example trades or staff.
file Artifact filename.
size Payload size in bytes.
sha256 Expected SHA-256 checksum of the payload.

Successful response:

{"ok":true,"message":"stored","path":"backups-remote/runs/..."}

Failed response:

{"ok":false,"message":"sha256 mismatch"}

Read commands use the same JSON-line request format:

Command Purpose
list_runs Return remote backup run identifiers available under the configured storage directory.
get_artifact Return one stored artifact as a JSON metadata line followed by binary payload.

The trading server uses these read commands to import a remote run back into the local backup catalog before validation and restore.

Storage Layout

Accepted files are stored under the configured storage directory:

<storage>/runs/<run_id>/<participant>/<file>
<storage>/runs/<run_id>/<participant>/<file>.receipt.json

The server writes uploads to <file>.part first. The final artifact is published only after the complete payload has been received and the SHA-256 checksum matches the header.

Security Model

The current transport uses a shared token in the upload header. Run the backup server on a private network, VPN, WireGuard tunnel, or another protected transport whenever possible.

Production deployments should plan for:

  • firewall rules that allow uploads only from trusted trading servers;
  • a non-empty token;
  • encrypted transport through VPN or TLS termination;
  • restricted filesystem permissions for the storage directory;
  • monitoring of disk usage and failed upload responses;
  • retention rules for old backup runs.

Next Step

Proceed to the installation guide: