Initializing with an Archive

System archive seeding is a feature that lets an operator initialize a new SENSE deployment from an exported JSON archive. It leverages the same system as the interactive SENSE Portal import and export functions but runs in a non-interactive fashion during orchestrator startup. SENSE attempts seeding on each startup until an import succeeds, but only while no completion marker, global properties, drivers, profiles, service instances, or ACL records exist.

Prerequisites

• A fresh or unprovisioned deployment.
• A source archive approved for use in that environment.

Configure the Import Directory

For Docker Compose, configure the host archive directory:

ARCHIVE_IMPORT_DIR=/opt/sense/orch/archive-import

Then add this read-only bind mount to the app service alongside its existing volumes before the initial startup:

services:
  app:
    volumes:
      - ${ARCHIVE_IMPORT_DIR}:/opt/sense/archive-import:ro

The supplied Compose files do not include this volume by default. The importer always reads /opt/sense/archive-import inside the app container.

Prepare the Archive Files

Place direct regular files whose names end in .json, case-insensitively, in the host directory mounted at /opt/sense/archive-import. SENSE ignores symlinks, subdirectories, and other files, and processes eligible filenames in lexical order. Each file may be a settings, driver, profile, or system bundle archive.

The entire directory is parsed before writes begin. If parsing succeeds, the files are imported in one required transaction. If /opt/sense/archive-import is missing or empty, normal initialization continues without seeding. An unreadable path at that location or a non-directory causes startup failure.

Archive payload limits are fixed at 32 MiB per archive, nesting depth 100, and string length 1 MiB.

Import Behavior

The seeding functionality uses the global archive system, with a few distinct assumptions:

• Seeding uses the system principal, as there is no user present in this operation.
• Setting imports use MERGE mode, and the service automatically acknowledges settings that would require review.
• Profile imports use RESTORE mode, preserving their UUIDs, owners, and ACLs.

After a successful import, SENSE records a completion marker in the database, preventing a later boot from reimporting the archive. Do not manually clear the internal completion marker; use the SENSE portal or REST API to import a backup via normal archive operations.

For normal archive operations, see System Backup and Restore.

Operations Plan

Putting this all together:

1. Prepare the deployment configuration files and verify that the archive source is trusted, complete, and readable only by the required deployment components.
2. Mount the archive directory read-only at /opt/sense/archive-import before the initial start.
3. Start SENSE and observe the startup result through the deployment’s normal operational checks.
4. Verify the imported settings, drivers, profiles, and ACLs after startup. Newly created drivers remain unplugged and require inspection before connection.

For later imports, use the SENSE portal or REST API. Kubernetes archive staging remains an evidence gap; obtain a chart-specific verified procedure before using that deployment method.