Skip to main content

Back up and restore Pioreactor system files

Each Pioreactor keeps its configuration, calibration data, and persistent state inside ~/.pioreactor. The Inventory page now lets you export that directory as a zip for safekeeping and import it onto the same unit when you need to restore or clone a setup.

Manage Pioreactor menu showing export and import actions highlighted

Exporting system files​

  1. Open the Inventory page, find the Pioreactor you want to back up, and click Manage Pioreactor → Export system files.
  2. Confirm the export when prompted. The UI downloads a file named <pioreactor>_dot_pioreactor.zip.
  3. Store the archive somewhere safe. It contains every file from that unit’s ~/.pioreactor plus a pioreactor_export_metadata.json descriptor (hostname, version, export time).

Export system files confirmation dialog with the export button highlighted

After you confirm, the browser saves a zip named <pioreactor>_dot_pioreactor.zip.

Troubleshooting​

  • If export is blocked, check whether the unit has the sentinel file ~/.pioreactor/DISALLOW_UI_FILE_SYSTEM; removing it re-enables downloads.
  • Since the export is over http, you may need to "approve" your browser to download it (check the download tab in your browser).
  • For the leader Pioreactor, it's also exporting the sqlite database. This might take a while for very large databases.

Importing system files​

Use imports when you need to restore a backup, duplicate a Pioreactor after replacing hardware, or bring back calibration data after re-flashing an SD card.

  1. On the Inventory page, choose Manage Pioreactor → Import system files.
  2. Read the warning and confirm. You will be prompted to select a .zip generated by the export flow.
  3. Wait for confirmation in the snackbar. The UI shows a spinner while uploading and tells you when the Pioreactor begins rebooting.

Import system files confirmation dialog with the import button highlighted

Important behaviour to note:

  • Hostnames must match. The worker compares the archive metadata to the target unit name and rejects mismatches during import.
  • The ZIP is validated to block absolute paths, symlinks, or other unsafe entries before anything is extracted.
  • An automatic backup of the existing ~/.pioreactor is written to /tmp/<hostname>_dot_pioreactor_backup_<timestamp> before any files are replaced. You can manually restore from that folder if you need to undo the import.
  • After the files are moved into place, the worker schedules a reboot so the new configuration takes effect.
  • Imports and exports share the same guard: adding ~/.pioreactor/DISALLOW_UI_FILE_SYSTEM disables both operations until the file is removed.

Advanced notes​

  • For scripted workflows you can hit /api/units/$broadcast/zipped_dot_pioreactor to download archives for every worker in one request. The aggregated ZIP namespaces each unit under a folder that matches its hostname.
  • Imports are always per-unit. If you are automating restores, loop over your hosts and POST the zip to /api/units/<pioreactor>/import_zipped_dot_pioreactor one at a time.

With these tools you can keep regular snapshots of your cluster, move calibrations between identical builds, or roll back quickly after testing changes.