Skip to main content

Back up and restore BoatKit

Back up BoatKit before replacing its hardware or making a major configuration change. A complete backup consists of separate configuration, vessel-history, and sensor-history files. You can download these files manually or have BoatKit maintain a restorable series in Google Drive or OneDrive.

Administrator and local access required

Backup settings and transfer controls require administrator access and a direct connection to BoatKit on the vessel's local network. They are intentionally unavailable through a remote BoatKit Cloud Viewer.

Once configured locally, scheduled cloud backups can run without an open Viewer.

Before you start​

You need:

  • Administrator access to BoatKit.
  • A direct local connection to the BoatKit host.
  • Stable power for the host throughout any restore.
  • Your installation's normal procedure for restarting the BoatKit host.
  • Internet access if you are connecting a cloud-storage provider, uploading a cloud backup, or restoring a cloud series.

Before replacing hardware, create fresh full backups of the configuration, vessel history, and sensor history. Keep an additional off-device copy when the data is important. BoatKit does not publish a fixed maximum archive size; practical limits depend on the host's available storage, the amount of history, and transfer speed.

What each backup contains​

Configuration​

A configuration backup contains nonsecret vessel configuration, including:

  • BoatKit settings and saved views.
  • Sensor and equipment setup.
  • Stable peripheral identity used to recognize configured equipment after migration.
  • Integrations and trigger rules.
  • Saved routes.
  • Maintenance records.
  • Local BoatKit Assistant conversations and their attached pictures.
  • The stable vessel and device identity needed to recover a replacement host.

Configuration backups do not contain passwords, API keys, credentials embedded in camera URLs, cloud-storage credentials, or BoatKit Cloud keys. These credentials must be entered or issued again after a restore when they are not already present on the destination.

A current downloaded configuration uses BoatKit portable configuration format version 26. BoatKit also accepts supported older formats. Within a supported format, restore operates by known key path and section: values present in the backup are applied, destination values are retained when a key is absent, and unknown removed or future keys are ignored. A file with an unsupported overall format or version is rejected.

When a configuration from another device is restored, its backed-up stable vessel and device identity replaces the destination identity. BoatKit invalidates the destination's BoatKit Cloud key so the replacement can be paired back to the same BoatKit Cloud vessel with newly issued credentials.

Vessel history​

Vessel history is a separate compressed archive containing track points, trips, and Trip Log events. Restoring it updates records with matching track timestamps, trip IDs, or event IDs while retaining unrelated existing history.

Sensor history​

Sensor history is another compressed archive containing canonical raw sensor rows. It is kept separate because it can be much larger than configuration or vessel history. Restoring it merges the raw rows and rebuilds derived summaries.

Create downloaded backups​

  1. Connect directly to BoatKit on the local vessel network.

  2. Open Settings > Backup & Restore.

  3. Under Configuration, select Download configuration.

  4. Under Vessel History, select one of these options:

    • Back up vessel history for a complete archive.
    • Back up last 24 hours for a time-ranged archive.

  5. Under Sensor History, select one of these options:

    • Back up all sensor history for a complete archive.
    • Back up last 24 hours for a time-ranged archive.

  6. Confirm that each requested file appears in your browser's downloads before leaving the page.

For hardware replacement, use the complete-history options unless you already maintain a deliberate incremental series. If time-ranged archives extend a baseline, their ranges must be adjacent and non-overlapping. Keep the baseline and every later archive together.

Restore downloaded backups​

Keep BoatKit powered during restore

Never remove power while a restore is running. Large history archives can take time, and a failed restore is not transactionally rolled back.

Restore configuration​

  1. Open Settings > Backup & Restore through a direct local connection.
  2. Under Configuration, select Restore configuration.
  3. Read the confirmation, select Choose backup, and choose the configuration JSON file.
  4. Wait for the Configuration restored success alert. Do not restart or remove power while the restore is still running.
  5. Restart the BoatKit host using your installation's normal restart procedure.
  6. Reconnect to the Viewer before relying on restored views, sensor configuration, or peripheral identity.
  7. Re-enter omitted passwords, API keys, camera credentials, and other secrets. If the backup came from another device, complete fresh BoatKit Cloud pairing for the restored vessel identity.

The restart is required because some restored views, sensor configuration, and peripheral identity are fully loaded only when BoatKit starts.

Restore vessel history​

  1. Under Vessel History, select Restore vessel history.
  2. Confirm the merge and choose the compressed archive.
  3. Wait for the success alert. It reports the number of restored track points, trips, and events and confirms that existing history was retained.
  4. If you have a baseline and incremental archives, restore the baseline first and then restore each incremental archive from oldest to newest.

Restore sensor history​

  1. Under Sensor History, select Restore sensor history.
  2. Confirm the merge and choose the compressed archive.
  3. Wait for the success alert reporting the number of restored raw sensor-history rows.
  4. If you have a baseline and incremental archives, restore the baseline first and then restore each incremental archive from oldest to newest.

BoatKit rebuilds derived sensor summaries after the raw rows are merged. Allow a large restore to finish before evaluating whether all history has returned.

Configure automatic cloud backups​

BoatKit can store automatic backups in your own Google Drive or OneDrive account.

  1. Connect locally and open Settings > Backup & Restore.

  2. Under Automatic Cloud Backups, select Connect Google Drive or Connect OneDrive.

  3. Complete the provider-specific authorization:

    • Google Drive: BoatKit opens Google's top-level folder Picker in the system browser. Sign in if necessary and choose an existing folder. BoatKit receives the limited drive.file access used for that folder. Back in BoatKit, select Use this folder, or enter a name and select Create new folder here to make one folder directly inside it. Google's Picker does not provide a create-folder control.
    • OneDrive: Complete Microsoft sign-in in the system browser. Return to BoatKit, browse the BoatKit app folder under Apps / BoatKit Automatic Backups, and select or create the folder for this vessel. Select Select this folder.

  4. Under Backup settings, choose Daily or Weekly for Frequency.

  5. Set Track history backup type, which controls vessel history, and Data history backup type, which controls sensor history. Each can be configured independently:

    • None excludes that history family.
    • Incremental creates a full baseline on its first run, then adds adjacent ranges on later runs. A large baseline can be split across several files; all of those first-run files are labeled baseline.
    • Full uploads a complete current history archive on every run.

  6. Select Back up now if you want to create the first series immediately. Otherwise, BoatKit waits 10 minutes after you confirm the folder before starting the first automatic backup, giving you time to revise the folder or backup settings. Later runs follow the selected daily or weekly schedule.

  7. Leave BoatKit powered until the running status clears and Last backup shows the successful time.

Every automatic run refreshes one complete compressed nonsecret configuration backup, regardless of the two history settings. Large sensor-history baselines, full backups, and catch-up ranges are split into compressed files targeted near 200 MiB rather than one multi-gigabyte upload. A file can be somewhat larger when many rows share the same timestamp because BoatKit keeps those rows together.

BoatKit checkpoints an in-progress run so it can resume without uploading another configuration or turning the rest of a first-run baseline into same-day incremental files. It commits the series manifest only after all required uploads finish. Until that commit succeeds, restore continues to use the preceding complete series rather than an incomplete run. After a successful commit, BoatKit removes its stale progress file and superseded automatic-backup files.

Backups made by releases using the earlier large-file layout remain restorable. The first backup made by this newer layout replaces that older history series with a newly bounded baseline and removes the superseded BoatKit files only after the replacement manifest commits; you do not need to empty the folder first.

One folder is one vessel root

The folder you select is already the backup root for the vessel. BoatKit does not add another vessel directory beneath it. The settings panel shows its provider-rooted breadcrumb; if Google's limited permission hides ancestor names, an ellipsis marks the hidden portion. Use the folder selected for that vessel when restoring.

Restore a cloud backup during first-run setup​

Cloud-series restore is offered during first-run setup, before the host pairs with BoatKit Cloud.

  1. Start the new or replacement BoatKit host and connect to it locally.

  2. On Set up or restore this vessel?, select Restore from cloud backup. Select Brand new setup only when you intend to create a new vessel with empty history.

  3. Connect the Google Drive or OneDrive account containing the backup.

  4. Select the vessel's backup folder. Remember that the selected folder itself is the vessel root.

  5. Wait while BoatKit finds and validates the committed backup series.

  6. When Backup found appears, check its last-updated time and the displayed vessel-history and sensor-history archive counts.

  7. Under Restoration mode, make an explicit choice:

    • Replace existing device recovers the original vessel identity and continues using this cloud backup series. When you pair the replacement with BoatKit Cloud, the device it replaces is disconnected.
    • Create a separate vessel copies the configuration and history while keeping this host's newly generated identity. BoatKit retains the connected provider account, but disconnects the source backup folder and leaves automatic backups off so the two vessels cannot write to the same series.

  8. Select Restore and replace device or Restore as a separate vessel, confirm the restore, and wait for all configuration and history to finish restoring.

  9. Continue through BoatKit Cloud pairing. Do not restart between restore and pairing. Replacement mode must pair using the recovered vessel identity first; separate-vessel mode registers the fresh identity as its own vessel.

  10. If you created a separate vessel, return to Settings > Backup & Restore, select a new backup folder for it, and confirm the desired backup settings. Never reuse the source vessel's backup root.

  11. After pairing succeeds, restart the BoatKit host once using the installation's normal restart procedure.

  12. Reconnect to the Viewer and enter any passwords, API keys, camera credentials, or other omitted secrets that the restored configuration requires.

BoatKit restores only the complete series referenced by the committed manifest. Incomplete uploads and progress files are not presented as a restorable series.

Confirm it is working​

Check the results appropriate to the operation:

  • A downloaded backup appears as a configuration JSON file or compressed history archive in the browser's downloads.
  • Automatic Cloud Backups shows Connected to Google Drive or Connected to OneDrive, the expected Backup folder, and a recent Last backup time.
  • A downloaded configuration restore displays its success alert, and the expected views, sensors, and equipment return after the required restart.
  • A downloaded history restore reports the number of merged records.
  • A first-run replacement restore completes BoatKit Cloud pairing for the recovered vessel identity. A separate-vessel restore appears as a new vessel and shows no backup folder until you select one. In either mode, the Viewer reconnects after the single post-pairing restart.

Internet and offline behavior​

Internet access is required to connect a provider, browse or select its folders, upload an automatic backup, and restore a cloud series.

A temporary provider or network failure does not stop local BoatKit operation. Scheduled work is tried again on a later run, and the last committed cloud series remains the restorable one. Downloaded backup and restore operations do not depend on the cloud-storage provider or an internet connection, but they still require a direct local connection to BoatKit.

Protect the cloud backup folder​

Do not manually delete or rename the manifest, configuration archive, baseline, or incremental files in the selected cloud folder. Those files form one coordinated series.

After a successful backup commit, BoatKit removes progress files and BoatKit-named configuration or history files that the committed manifest no longer references. Cleanup happens only after the new series is safely committed and does not touch unrecognized files in the selected folder. A provider error can leave a stale file behind without invalidating the committed backup; do not infer that an unreferenced-looking file is safe to remove manually.

Selecting Disconnect stops automatic backups and removes the provider connection from BoatKit. Existing files remain in cloud storage.

Retry a failed restore safely​

Configuration and history restores are merge-safe and may be retried with the same downloaded archive. A cloud restore may likewise be retried with the same committed series after a transient error.

A restore is not transactionally rolled back, so an error can occur after some data has already been applied. If a retry with the same archive or committed series fails again:

  1. Retain the exact visible error message.
  2. Leave the existing archives and cloud folder unchanged.
  3. Contact BoatKit support before trying a different archive or series.

Troubleshooting​

Backup & Restore is unavailable​

Confirm that you have administrator access and that the Viewer is connected directly to BoatKit on the local network. The controls do not appear through a remote BoatKit Cloud Viewer.

If Automatic Cloud Backups says the BoatKit device must be updated, update the device before trying to connect or restore a provider.

A downloaded file does not appear​

Check the browser's download list and confirm that downloads are permitted from the local BoatKit address. Start the download again if no file was created.

Provider authorization does not finish​

Keep BoatKit's authorization panel open. If the system browser did not open automatically, use Open Google Drive folder picker or Open Microsoft sign-in. Complete the provider sign-in and consent in that browser tab, then return to BoatKit. OneDrive folder selection appears after the account connection completes.

Internet access is required until authorization and folder selection finish.

BoatKit cannot find the cloud backup​

Verify that you connected the correct provider account and selected the vessel root folder, not a neighboring or newly created empty folder. Do not move or rename files to try to make the series appear. Correct the account or folder selection and use Retry finding backup.

Restored configuration appears incomplete​

Confirm that the restore displayed its success alert and that the BoatKit host was restarted afterward. Restored views, sensor configuration, and peripheral identity are not fully reloaded until that restart.

A large backup or restore is taking time​

Leave BoatKit powered and allow the operation to finish. Duration varies with available device storage, history volume, provider performance, and network speed. Do not remove power or modify the cloud backup folder while the operation is running.