DataBrain User Manual

01Hardware & Software Requirements

DataBrain ships as a single Docker image. On startup it auto-detects the hardware and selects the appropriate tier — no manual tuning required.

1. Base prerequisites

GPU mode additionally requires: NVIDIA GPU driver (kernel module) + NVIDIA Container Toolkit. CPU mode can skip this.

Docker install example (only if Docker is not yet installed on the host)

Ubuntu / Debian:

sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER   # log out and back in to take effect

CentOS / RHEL / Rocky / Alma 8 (CentOS 8 is EOL; needs vault redirection + runc conflict resolution + SELinux relaxation):

sudo sed -i -e 's|^mirrorlist=|#mirrorlist=|' -e 's|^#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|' /etc/yum.repos.d/CentOS-*.repo
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y --allowerasing docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo setenforce 0 || true; sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
sudo usermod -aG docker $USER; sudo systemctl enable --now docker

GPU: after installing Docker, install nvidia-container-toolkit (Ubuntu apt / RHEL dnf), then sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker.

2. Recommended configuration

On startup the tier is selected automatically by VRAM: ≥ 8 GB → GPU-large; has GPU but < 8 GB → GPU-small; no GPU → CPU. All three tiers have identical accuracy — only speed differs (CPU is roughly 1/19–1/33 of GPU). The active tier is shown in the log as profile=….

3. Ports

To change a port: at install time DATABRAIN_PORT=<port> bash <databrain>.sp, or edit the ports in docker-compose.prod.yml.

02Installation & Startup

The .sp file is a self-extracting installer: bash <file>.sp is a single command that performs loading, CPU/GPU detection, startup, health gating, and sample verification.

Two packages (the actual filenames in your delivery may differ; test builds may be siipulse-beta_*):

• siipulse-rel_baseimage_1.0.sp (~2.9 GB): the shared Docker dependency base, installed once per machine, reused by all versions / products.
• siipulse-rel_databrain_<ver>.sp (~0.7 GB): the application package, re-issued every release. The version number = the image tag = the trailing digits of the filename.

Quick start

# 0) One-time host preparation (needs sudo; creates the install directory + opens firewall 18000/18001)
sudo bash siipulse-rel_databrain_<ver>.sp --prepare-host

# 1) Install (enter the install directory created in step 0 — its path is printed by --prepare-host; place both .sp files there; the app package auto-installs BaseImage first, then starts the service)
cd <install-dir>
bash siipulse-rel_databrain_<ver>.sp

# 2) Activate the license (first install prints the machine code; send it to the vendor to obtain license.json)
bash databrain-ops.sh fingerprint
bash databrain-ops.sh activate license.json

# 3) Confirm readiness + first scan
bash databrain-ops.sh status
curl -X POST http://127.0.0.1:18000/v1/text/scan -H 'Content-Type: application/json' \
  -d '{"text":"Contact John Doe, email john.doe@google.com, phone +1-415-555-0142."}'

curl -X POST http://127.0.0.1:18000/v1/text/scan -H 'Content-Type: application/json' \
  -d '{"text":"联系人张伟，邮箱 zhangwei@google.com，手机 +86 13800138000。"}'

Upgrade / rollback

bash siipulse-rel_databrain_<new-version>.sp  # installer path: auto-reuses the on-host BaseImage; auto-rolls back on failure
bash databrain-ops.sh upgrade <new-version>   # safe in-place upgrade when the image is already loaded (multi-step guard chain, auto-rollback on any failure)
bash databrain-ops.sh revert                  # undo the most recent upgrade

The license lives in the license/ volume and is never touched by an upgrade, so no re-activation is needed.

License (offline authorization)

DataBrain uses offline authorization. Scanning endpoints (/v1/text/scan, /v1/values/scan) require an activated license first, otherwise they return 403 license_required; /v1/health and /v1/license/status are always open.

Activation (commands are in "Quick start" step 2 above): collect the machine code from this host → send it to Siipulse in exchange for license.json → load and activate it.

• The license is bound to this machine; upgrades, reboots, and container rebuilds on the same machine require no re-activation.
• When replacing the host or migrating to another machine, you must re-collect the machine code on the new machine and re-issue the license.
• Verify: curl http://127.0.0.1:18000/v1/license/status should return valid:true.

Management console (port 18001, HTTPS)

After the container starts, the console is served at https://<host>:18001/ on the same host, with default credentials admin/admin (you are prompted to change the password on first login). It shares the same license as the inference API. The console provides:

• Dashboard: run overview and key metrics.
• System management: system status / license import / .sp version management / restart.
• Self-learning: new-type discovery and corpus-bundle management.
• Playground: live test scans.
• Audit: detection-log review / human labeling / statistics and pagination.
• Troubleshooting: diagnostic bundling.
• Top-bar health alerts: persistent status banner.

HTTPS notes (enabled by default since 2026-08-21)

• Certificate mechanism: the console is served via native TLS with a self-signed certificate generated automatically on first start (ECDSA P-256, 10-year validity, SAN covers the host IP + localhost, determined by DATABRAIN_TLS_HOST_IP written to .env by the installer).
• First-visit warning: private-IP hosts cannot obtain a public CA signature, so the browser shows "Your connection is not private" — click Advanced → Proceed to continue.
• Certificate persistence: the certificate lives in the console-data/ volume; container upgrades/rebuilds keep it, no re-trusting needed.
• Eliminating the warning: import console-data/tls/console.crt (in-container /app/webui/tls/console.crt) into the OS / enterprise certificate trust store.
• Falling back to HTTP: set DATABRAIN_CONSOLE_TLS=0 in .env (local debugging only).
• Public deployments: still recommended to front nginx to terminate TLS (with a proper domain certificate) + an IP allow-list.

Operations commands (databrain-ops.sh)

start | stop | restart | status | logs -f | health | license | verify | fingerprint | activate <file> | upgrade <ver> | rollback <ver> | revert | clear | deps | diagnose | version

Usable from any directory: add the install directory to your PATH (export PATH=<install-dir>:$PATH). For more troubleshooting see 07-Operations & Troubleshooting; for response field semantics see 03-API Integration Guide.

Common issues

ops-agent (optional · WebUI remote upgrade / restart)

Once installed, the console's "System Management" page can trigger restarts and .sp version upgrades remotely over a local secure channel (the service is unavailable for ~30–90s during container rebuild, with automatic rollback on failure). Once per machine (the app must already be installed):

sudo bash siipulse-rel_databrain_<ver>.sp --install-ops-agent

03API Integration Guide

DataBrain exposes its sensitive-data discovery capability over HTTP. Choose the integration path based on the shape of your data:

Every decision carries decision-provenance fields (method / role, always returned) and optional decision evidence (evidence, returned on request), making each decision traceable and auditable. Field semantics are in section 3.

1. Document-level scan POST /v1/text/scan

For unstructured free text. The engine locates all sensitive entities within a text and returns their type, character offsets, confidence, and decision provenance.

1. Health check

GET /v1/health

{"status":"ok","ready":true}

2. Sensitive-data scan

POST /v1/text/scan
Content-Type: application/json

{
  "text": "Text to scan (1–100,000 characters)",
  "min_confidence": 0.5,
  "return_evidence": false
}

Request parameters

Response

{
  "results": [
    {
      "value": "zhangwei@example.com",
      "pii_type": "EMAIL",
      "start": 11,
      "end": 31,
      "confidence": 0.99,
      "needs_review": false,
      "method": "truth_table",
      "role": "reference"
    }
  ]
}

Error codes

2. Value-level batch classification POST /v1/values/scan

For scanning structured column values such as database tables, CSV / Excel columns, or data-lake fields. Operates on a "batch of values", judging each value independently and returning confidence.

POST /v1/values/scan
Content-Type: application/json

{
  "values": [
    {"value": "zhangwei@example.com", "value_id": "r1", "label_hint": "email"},
    {"value": "110101199003077334", "value_id": "r2", "label_hint": "id_card"},
    {"value": "13800138000", "value_id": "r3", "container_path": "customer.phone"}
  ],
  "return_evidence": false
}

Request parameters

Response

{
  "results": [
    {"value_id": "r1", "value": "zhangwei@example.com", "pii_type": "EMAIL",   "confidence": 0.99, "needs_review": false, "is_mock": false, "method": "truth_table", "role": "subject"},
    {"value_id": "r2", "value": "110101199003077334",    "pii_type": "ID_CARD", "confidence": 0.92, "needs_review": false, "is_mock": false, "method": "truth_table", "role": "identifier"}
  ]
}

Error codes

3. Decision-provenance fields (method / role / evidence)

Every DataBrain decision carries provenance information, making the decision process transparent, verifiable, and auditable — not a black-box output.

method — decision path

Identifies which engine path produced this result, reflecting the signal strength and confidence tier behind the decision:

role — semantic role

Inferred from the column / field name (label_hint), indicating the value's semantic role in the business, to assist downstream policy decisions:

evidence — decision evidence (on request)

evidence is not returned by default; it is attached only when return_evidence=true is requested. It carries the objective evidence supporting the decision, for example:

4. label_hint notes (value-level only)

label_hint is the column / field-name hint supplied in the request (e.g. email, id_card, passport). It is a strong clue that assists the engine's decision and notably improves accuracy on pure-digit, format-similar identifiers (e.g. national ID vs passport vs social-security number).

• How to supply: set the label_hint field on each object in values[];
• When label_hint is not supplied, the system auto-derives it from the last segment of container_path (e.g. customer.phone→phone, users.email→email) — so as long as you put the real column / field name into container_path, you get the same boost as an explicit label_hint, with no duplicate entry;
• It only takes effect when the column name matches a known type word (e.g. phone / email / ssn / id_card / passport / dob); meaningless names (e.g. col_0, value1) are safely ignored and do not affect the decision;
• An explicit label_hint always takes precedence; if neither is supplied, the engine still judges normally;
• Production tip: database field names and CSV headers are naturally high-quality column-name hints — pass them in via container_path or label_hint.

5. Complete call examples

curl

English sample:

curl -X POST http://127.0.0.1:18000/v1/text/scan \
  -H 'Content-Type: application/json' \
  -d '{"text":"Order #A12345, customer john.doe@google.com, phone +1-415-555-0142.","min_confidence":0.5}'

Chinese sample (same engine, multilingual):

curl -X POST http://127.0.0.1:18000/v1/text/scan \
  -H 'Content-Type: application/json' \
  -d '{"text":"订单 #A12345，客户 john.doe@google.com，电话 +1-415-555-0142。","min_confidence":0.5}'

Python (HTTP)

import requests

resp = requests.post(
    "http://127.0.0.1:18000/v1/text/scan",
    json={"text": "Customer john.doe@google.com, phone +1-415-555-0142.", "min_confidence": 0.5},
    timeout=30,
)
for m in resp.json()["results"]:
    print(m["pii_type"], m["value"], m["confidence"], m["method"])

Java

// Uses JDK 11+ HttpClient
import java.net.http.*;
import java.net.URI;

var body = "{\"text\":\"Customer john.doe@google.com, phone +1-415-555-0142.\",\"min_confidence\":0.5}";
var req = HttpRequest.newBuilder()
    .uri(URI.create("http://127.0.0.1:18000/v1/text/scan"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

C# (.NET)

using var http = new HttpClient();
var body = """{"text":"Customer john.doe@google.com, phone +1-415-555-0142.","min_confidence":0.5}""";
var content = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
var resp = await http.PostAsync("http://127.0.0.1:18000/v1/text/scan", content);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

Go

body := []byte(`{"text":"Customer john.doe@google.com, phone +1-415-555-0142.","min_confidence":0.5}`)
resp, err := http.Post("http://127.0.0.1:18000/v1/text/scan",
    "application/json", bytes.NewReader(body))
// ...read resp.Body

Value-level batch (/v1/values/scan)

import requests

resp = requests.post(
    "http://127.0.0.1:18000/v1/values/scan",
    json={"values": [
        {"value": "john.doe@google.com", "label_hint": "email"},
        {"value": "123-45-6789",          "label_hint": "ssn"},
    ]},
    timeout=30,
)
for r in resp.json()["results"]:
    print(r["value_id"], r["pii_type"], r["confidence"], r["method"], r["role"])

With decision evidence (return_evidence=true)

curl -X POST http://127.0.0.1:18000/v1/values/scan \
  -H 'Content-Type: application/json' \
  -d '{"values":[{"value":"4111 1111 1111 1111","label_hint":"credit_card"}],"return_evidence":true}'

6. Integration best practices

1. Startup dependency check: probe /v1/health before calling, and only send requests once ready:true, to avoid 503 during cold start.
2. Timeout: a single /v1/text/scan client timeout should be ≥ 30 seconds (the first request includes model warm-up); in steady state a single text is usually millisecond-level.
3. Large batches of text: one HTTP request per text; for huge document volumes, concurrency on the caller side is recommended (the server-side concurrency cap depends on the hardware tier, see 05-Performance & Capacity); for very large batches of structured data use value-level /v1/values/scan (call in batches of ≤1000 per request).
4. Handling needs_review: set policy by business — risk / compliance scenarios should do manual or secondary rule-based review; general scenarios can trust the type label directly.
5. Use provenance: method lets you track decision-path distribution and the share of borderline cases; enable return_evidence when you need the full rationale, for audit, forensics, and policy tuning.
6. Idempotency: the same input always yields the same output — feel free to retry, cache, and build comparison baselines.
7. Offset usage: start/end can be used directly for front-end highlighting and redaction (e.g. replace the [start,end) span with ***).

04PII Type Catalog

DataBrain supports 32 types of sensitive data, grouped into four categories by sensitivity and detection reliability. The pii_type field returned by the system takes its values from the "Type" column in the tables below.

Category overview

I-A · Strong identifiers (4 types, with mathematical validation)

I-B · Identifiers (16 types, with format / validation)

II-A · Common PII (9 types, context-dependent)

II-B · Intrinsic attributes (3 types, AI semantic recognition)

Coverage breadth

• Languages: the AI recognition model is based on multilingual pre-training and covers 100+ languages (Chinese, English, Japanese, Korean, Hindi, many European languages, etc.).
• Regions: national IDs cover 30+ country formats and tax IDs cover 20+ country formats (per the built-in type definitions), including mainland-China national ID / license plate / travel permit / securities account, Indian Aadhaar/PAN/UPI/IFSC, Japan My Number, various European/American IDs, etc.
• Regulatory alignment: the types above cover the sensitive-data categories regulated by mainstream data-protection laws (see the brochure's "Regulatory alignment" section).

05Performance & Capacity

This chapter gives measured reference performance and hardware-sizing guidance, to help estimate throughput and capacity.

1. Latency & throughput (reference)

Document-level (HTTP /v1/text/scan, single text)

Value-level (batch classification benchmark)

2. Concurrency & throughput notes

• Per-tier concurrency caps: CPU tier 4 / GPU-small 8 / GPU-large 16;
• Multiple requests can overlap concurrently; effective throughput rises with concurrency until GPU compute saturates;
• Callers are advised to do client-side concurrency control according to the hardware tier's cap, to avoid queuing under overload.

3. Sizing guidance

4. Capacity estimation example

Estimated with GPU-large, document-level single-stream ~100 texts/sec:

5. VRAM & memory footprint

• AI model: ~0.7 GB (multilingual sensitive-data recognition model, delivered encrypted inside the image, loaded into VRAM at startup);
• Dependency layer: ~2.7 GB (AI runtime stack, disk footprint, not resident in VRAM);
• Runtime peak: VRAM ≥ 8 GB and system memory ≥ 16 GB recommended;
• Disk: image ~3.4 GB; recommend reserving ≥ 15 GB (including 2-version rollback headroom). The detection log rotates daily with a default 180-day retention and is protected by a low-disk-space guard (auto-stops writing below 2 GB free; see 06-Security & Privacy).

06Security & Privacy

This chapter describes DataBrain's security design across deployment topology, data handling, supply chain, and offline authorization.

1. No data egress (offline deployment)

• Fully offline operation: the image is loaded from an offline package; at runtime it does not connect to Docker Hub, does not connect to any external source, and makes no outbound network request.
• Data never leaves the customer network: all sensitive-data scanning and judgment happens entirely inside the customer's own server/container; results are returned only to the caller.
• No telemetry, no callbacks: the system neither collects nor reports any scanned content or statistics to Siipulse or any third party.

2. Data persistence posture

• Scanning is real-time compute by default: input text is recognized in memory and the result emitted, with no on-disk persistence of the scanned content itself; operational logs (startup, health, errors) do not log PII.
• Detection log (default-on): the decision stream is written to disk for the console audit page (review and human labeling); values in records are redacted by default (only a few leading/trailing characters kept), rotated daily with a default 180-day retention and automatic cleanup on expiry.
• Low-disk-space guard: if free disk space drops below 2 GB, detection-log writing pauses automatically (keeping the classification service alive); it resumes once space recovers to about 3 GB; the stopped state is surfaced via /v1/health and console alerts.
• Data-reflow exception (default-on, see §9): when a request carries valid consent, the system retains an encrypted sample of the PII on the customer's local disk (for human review + offline model retraining, AES-256-GCM encrypted), bounded by a dual gate + retention period.

3. Container security

• Non-root: the container runs as a dedicated low-privilege user databrain, not root;
• Dependency isolation: the container bundles its entire runtime dependency set (AI inference framework, GPU runtime, etc.), isolated from the host's native environment, with no mutual interference;
• Only shared resource: in GPU mode the host and container share only the GPU driver (kernel module); no other system component is shared.

4. Data control rights

Console Playground capture: text submitted by operators in the console Playground enters the self-learning capture pipeline by default (console-playground customer bucket, encrypted retention), feeding the audit page for human labeling corrections. Per-request opt-out: check "do not record" when submitting (request body no_audit: true; the request is then not captured). Channel-wide off: deployment environment variable DATABRAIN_CONSOLE_CONSENT=false (default true). The bucket's retention cleanup and export are explicit ops actions (GET /v1/learning/export-corpus?customer=console-playground); it does not appear in the console's default corpus view.

5. Input limits (abuse prevention)

• /v1/text/scan caps a single text at 100,000 characters (exceeding returns 422), preventing oversized-payload memory abuse;
• min_confidence lets the caller control the emission threshold, tuning between "high precision" and "high recall" per scenario.

6. Compliance posture

DataBrain's detection capability covers the sensitive-data types regulated by mainstream data-protection laws (GDPR, CCPA, China PIPL, HIPAA, PCI-DSS, SOC 2, etc.), with type-level mappings established.

7. Upgrade & supply-chain security

• Upgrade packages (.sp) are offline incremental packages verified before loading with ECDSA signature validation + payload SHA-256 integrity comparison (the signature is bound to the payload hash, preventing "keep the signature, swap the content"); packages uploaded through the console's version-management page go through the same verification chain;
• The upgrade script has built-in path-traversal / absolute-path defenses and version-format validation, rejecting tampered packages;
• Versions are always pinned to an explicit tag (no :latest), for audit and precise rollback.

8. Offline license authorization

DataBrain uses fully offline authorization: all authorization checks happen locally on the customer side, with no outbound network request, no callback to Siipulse, and no online attestation, deployable in strict air-gapped environments.

• Host binding: the license is bound to the machine — bound to the host, not the container, so container rebuilds on the same machine do not affect authorization; each deployment instance must activate its own license. Replacing the host or migrating to another machine requires re-activation (see 02 "License (Offline Authorization)").
• Gate scope: /v1/text/scan, /v1/values/scan require a valid license; /v1/health, /v1/license/status are always open for diagnostics.
• Validity & grace period: a license has an expiry date, followed by a grace period (per authorization type); after the grace period the scan endpoints return 403, while the health / status endpoints stay open; renew before expiry — no reinstall needed.

For the activation flow see 02 "License (Offline Authorization)"; for authorization status and renewal see 07-Operations & Troubleshooting.

9. Data reflow (self-learning data collection)

Data reflow makes DataBrain more accurate over time: it samples "needs-review" verdicts from production traffic → human annotation → export of an encrypted corpus → hand-off to offline model retraining. Sampled data stays encrypted on the customer's own host and never leaves the network.

Not enabling it: no changes needed

Without the request headers below, the scan APIs behave exactly as usual, with zero collection. Collection is guarded fail-closed by two gates (an encryption key auto-generated at deployment + a per-request consent header); if either is missing, nothing is collected at all — the capability ships pre-installed and is activated per request only via the headers.

Enabling collection: add one header to scan requests

X-DataBrain-Consent: {"ts":"<YYYY-MM-DD>","crown_pii":true}

• This header only affects local sampling and detection logs; it never changes detection results
• crown_pii: true consents to collecting the PII original values in that request; omitting the header = no collection for that request

Review annotation and corpus management are performed by operators in the console (/self-learning and the review UI); no caller involvement is required. Data subjects exercising erasure rights should contact the operator.

07Operations & Troubleshooting

One-click self-check (online diagnostics, preferred)

The console's Diagnostics page (host port 18001 → Diagnostics) provides a one-click self-check that runs 9 checkpoints (in 6 groups) across deployment, startup, and runtime — each with a status light: 🟢 green = normal / 🟡 yellow = abnormal but core functions unaffected / 🔴 red = core functions impaired / ⚪ grey = not applicable (e.g. dependencies that cannot be assessed while the inference service is unreachable).

• Automatic: runs once after startup (first install / upgrade / manual restart); retries during model loading until a meaningful result converges.
• Manual: click the "Self-check" button at any time.
• Check groups: service status (inference service / ops agent) → licensing (license, distinguishing expiring / grace-period / pending-activation states) → model assets (integrity of the recognition-model components) → core function (built-in sample-detection verification, consistent with the pre-release verification criteria) → pipeline health (audit persistence / audit index) → data persistence (storage writes). Resource capacity (memory / disk / GPU), quality gates, drift, and p95 latency are on the dashboard and health-alerting pages.
• Remediation guidance: every yellow/red light carries handling advice and a jump link (e.g. license activation, audit page, restart from system administration); the raw data is expandable.
• Proactive alerting: when the overall result is red/yellow, the console's top alert bar shows "Self-check found issues" and can be pushed out via webhook (if DATABRAIN_ALERT_WEBHOOK_URL is configured).
• Result retention: output/selfcheck/ (history included), exported together with the diagnostic bundle; on a fresh install without an activated license, a yellow "pending activation" light is the expected state.

Diagnostic bundle (offline fallback)

When the container or the console fails to start and you need to send diagnostic information to support, run on the host, from the install directory:

bash databrain-ops.sh diagnose

• Output: <install-dir>/diagnostics/diag_<timestamp>.zip (send to the vendor).
• Collected: version / machine code / health / license status / container process logs (docker compose logs) / docker info / nvidia-smi, all best-effort — even if the container is down or docker is missing, a usable partial diagnostic bundle is still produced.
• Redaction: automatically strips sensitive environment-variable values; the license file and key material of any kind are never bundled.
• When the container is running normally, it is preferable to use the console's Troubleshooting page (host port 18001) for one-click bundling — its content is more complete (includes audit samples / metric series / model version), with the same redaction.

1. Daily operations commands

The databrain-ops.sh commands below and throughout this chapter are run from the install directory (or add the install directory to your PATH first — see the tip below).

2. Monitoring essentials

3. Version management

• Always pin an explicit TAG (e.g. TAG=1.0.1); do not use :latest, for audit and precise rollback;
• Keep the latest 2 application versions (current + previous) for instant rollback;
• Never manually delete the dependency layer (base) — it is large but changes rarely (about once a year), and it is key to rollback; only manually clean up "orphan" dependency layers that no application version references;
• Upgrades are handled end-to-end (signature verification → load → health gate → rollback on failure) by the application siipulse package (bash siipulse-rel_databrain_<new-version>.sp), reusing the on-host BaseImage; .sp packages uploaded through the console's version-management page go through the same signature and integrity verification (see 06-Security & Privacy §7).

4. Rollback / revert / cleanup / dependency self-check

4.1 Roll back to a specific version rollback

# Switch back to any old version still in the local image store (dependency layer + old app image still present)
bash databrain-ops.sh rollback <old-version>

A rollback completes within seconds (a tag switch + restart + ~30–70 s model reload).

4.2 Undo the most recent upgrade revert

# No need to remember the version: returns to the pre-upgrade version (auto-recorded by the installer)
bash databrain-ops.sh revert

Difference between revert and rollback: rollback <ver> requires an explicit version number and can switch to any old version; revert takes no argument and specifically "undoes the last upgrade", relying on the previous version recorded by the installer. Neither touches the license volume.

4.3 Clean from scratch clear (dangerous)

For extreme troubleshooting or before migrating to a new machine, you can fully clean this installation back to a "only delivery packages left" state:

bash databrain-ops.sh clear        # interactive confirm (type YES)
bash databrain-ops.sh clear --yes  # skip confirm (for scripts / automation)

clear will: stop & remove containers → delete all siipulse-databrain:* application images → delete compose and the installation state files. Kept: license/ (the authorization volume, sparing re-activation), *.sp delivery packages, siipulse-baseimage:1.0 (the base, sparing a re-load). After cleanup, reinstall with bash siipulse-rel_databrain_<version>.sp.

4.4 Dependency self-check deps

Confirm whether the current base image contains all runtime dependencies (the dependency list is in requirements.lock inside the delivery package):

bash databrain-ops.sh deps

It checks the installed version of each key component (torch / transformers / fastapi, etc.) inside the base image, marking missing ones as MISS. Use it at delivery acceptance or when troubleshooting to answer "is the base complete?".

5. Troubleshooting table

License renewal

Renew the license before it expires to avoid scan interruptions:

1. Host hardware unchanged → you can reuse the original machine code and request a new license.json from the issuer;
2. Host hardware changed → re-collect the machine code bash databrain-ops.sh fingerprint, then request it;
3. Load the new license and restart to take effect: bash databrain-ops.sh activate license.json (= replace license/license.json + restart + verify);
4. After expiry you enter a grace period (per authorization type); once the grace period ends, scanning returns 403; after renewal it recovers immediately — no image reinstall needed.

6. Reading the logs

The startup log shows the following key signals in order (exact format subject to actual output):

• Hardware detection completes and the effective tier is determined (e.g. profile=gpu-large, i.e. "GPU-large");
• The engine finishes loading and reports the concurrency cap for that tier;
• The HTTP service starts listening on the port (8000 in-container, 18000 published on the host).

7. Deploying on Kubernetes and other orchestration platforms

The delivery is provided by default as Docker Compose. To deploy on Kubernetes or similar platforms:

• Import the image into your registry (docker load then docker tag + push, or use the offline package directly);
• Run as a Deployment with one replica (or more for horizontal scale-out, as needed);
• Point readiness/liveness probes at GET /v1/health, with the ready condition ready:true;
• In GPU mode, declare GPU resources the platform way (e.g. K8s nvidia.com/gpu).

8. Getting support

When troubleshooting, prepare the following information to help locate issues quickly:

1. DataBrain version number (the TAG of docker images siipulse-databrain, or bash databrain-ops.sh version);
2. Full startup logs (docker compose logs databrain);
3. Hardware configuration (CPU/memory, GPU model and VRAM, operating system);
4. Reproduction steps and request/response (please redact before sending; do not send real PII).

08Frequently Asked Questions (FAQ)