Orchestrator

Backups, restore and reset

A workspace's data is its Docker volume, mounted at /DATA in the container. The Data tab of a workspace has three actions. They are also available in the management API.

Download a backup

Download backup streams /DATA as a .tar.gz through the Docker archive API.

  • The console stops the workspace first, so the graph on disk is the one Studio stored on the way down. Open the workspace again afterwards to wake it.
  • The API does not stop it for you. A backup request for a running workspace is refused, so call stop first and wait until it is stopped.
  • Nothing can start the workspace while the backup runs.
curl -X POST -H "Authorization: Bearer $ORC_API_TOKEN" https://example.com/api/admin/instances/acme/stop
curl -H "Authorization: Bearer $ORC_API_TOKEN" -o acme.tar.gz \
     https://example.com/api/admin/instances/acme/backup

Restore

Restore replaces the workspace's data with an archive made by Download backup, from this workspace or another.

  1. The upload is read in full and checked first: a complete tar with every entry under DATA/. A cut-off or wrong archive is refused with 400, and nothing is deleted.
  2. Only after that check does the Orchestrator delete the current data.
  3. The workspace is re-created on a fresh volume, the archive is extracted, and the Orchestrator names the workspace again.

The console shows the upload's progress.

curl -H "Authorization: Bearer $ORC_API_TOKEN" -H 'Content-Type: application/octet-stream' \
     --data-binary @acme.tar.gz https://example.com/api/admin/instances/acme-copy/restore

Restoring into a differently named workspace is how you clone one. The copy is renamed to match its new address.

Restore deletes the current data

Restore replaces what is in the workspace. Download a backup of it first if you might need it.

Reset

Reset to an empty workspace starts over with an empty volume at the same address.

What a backup does not contain

  • The Orchestrator's own state, which lives in ORC_STORAGE: the workspace records, console users, accounts and certificates. Back that folder up as well, with the Orchestrator stopped or from a filesystem snapshot. Let's Encrypt certificates and the account key are in ORC_STORAGE/letsencrypt.
  • Anything outside /DATA in the container.

Scheduled backups are not built in. Run the API call from cron or a CI job.

Referenced by