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.
  • 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 22. 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 the folder for this vessel. BoatKit receives the limited drive.file access used for the selected folder.
    • OneDrive: Complete the device-code 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.
    • 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 runs it when the selected schedule is due.

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

Every automatic run includes a complete nonsecret configuration backup, regardless of the two history settings. BoatKit 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.

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. Use the folder selected for that vessel when restoring.

Restore a cloud backup on a replacement host​

Cloud-series restore is offered during first-run setup, before BoatKit pairs a new device identity.

  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. Select Restore this vessel, confirm the restore, and wait for all configuration and history to finish restoring.
  8. Continue through BoatKit Cloud pairing for the restored vessel. Do not restart between restore and pairing. Pairing must finish using the recovered vessel identity first.
  9. After pairing succeeds, restart the BoatKit host once using the installation's normal restart procedure.
  10. 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 cloud restore completes BoatKit Cloud pairing for the restored vessel, and 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.

BoatKit does not currently apply a provider-side retention or cleanup policy. Older files that are no longer referenced by the current manifest may remain in the folder, but their presence does not mean they are safe to remove. Obtain BoatKit guidance before cleaning up an automatic-backup folder.

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 provider sign-in. For OneDrive, enter the displayed device code when requested.

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.