Skip to main content

Onboarding /setup

/setup appears when SPOT does not yet have enough configuration to operate. It is a single card-based screen, not a wizard.

Sections​

  • License: online activation or installation of the received offline file.
  • Server: host, port, and HTTP/HTTPS scheme.
  • TLS: certificate and private file when HTTPS is enabled.
  • Elastic: fixed package capability, not a free selector.
  • Connector Elastic: where metrics and events are written.
  • Read Elastic: used by dashboards and AI.
  • Initial SAP: system, client, user, secret, and RFC parameters.
  • First local admin: user that signs in after setup.

Rules​

  • The card must show License valid before the rest of the form is enabled. After creating the first administrator, license actions require that role.
  • HTTP is valid for first startup.
  • HTTPS requires a valid certificate pair.
  • In spot-suite, embedded Elastic always uses http://127.0.0.1:9200, without authentication or certificates; setup does not offer external mode.
  • In spot-suite-external, setup offers only an HTTPS destination or Configure later. Deferral creates the administrator and enters limited mode.
  • External Elastic requires HTTPS. Use system CAs, an imported CA, or explicitly enable Disable certificate validation.
  • SPOT manages Data Streams and ILM is enabled by default for embedded Elastic. It is disabled for external Elastic until an administrator authorizes it and the permission preflight succeeds.
  • SAP secrets are stored protected by the backend.
  • Previously stored secrets can remain masked only while the destination identity is unchanged.
  • There is no default credential for the first admin: define the local username and password during setup. The login screen accepts that username; changing its password, roles, or enabled state immediately closes earlier sessions.

Embedded Elastic​

The suite includes Elasticsearch 9.4.2 isolated on loopback with Elastic HTTP security disabled. Package metadata fixes embedded and clears incompatible authentication or TLS values. Backend and agent use the exact same URL.

Do not generate certificates, users, API keys, or p12 stores for this mode. The screen hides those fields because embedded Elastic is not editable as an external destination.

Package-aware setup with fixed embedded Elasticsearch

External Elastic and TLS validation​

An external destination must use HTTPS even when its address is 127.0.0.1. Choose one policy:

  • System CAs: full chain and hostname validation.
  • Imported CA: chain and hostname validation trusting only the selected CA from Configuration > Trust store; system roots are not merged into this mode.
  • Disable certificate validation: keeps TLS but validates neither chain nor hostname.

The last option always shows this warning:

The connection is encrypted, but the server identity is not verified. An intermediary could intercept credentials and data.

SPOT never enables this exception after a certificate failure. External HTTP remains rejected even when the option is selected. Changing URL, authentication, user, SNI, CA, or TLS policy requires the complete credential again.

An existing external HTTP profile must migrate to HTTPS before enabling the new profile. An upgrade never silently converts it to embedded or starts a configuration that would leave backend or agent without access.

If Elasticsearch is deferred, Elasticsearch pending remains visible. Admin surfaces stay available and data views show a specific blocked state. Complete the destination later through Configuration using Test and Save.

Limited mode while Elasticsearch is pending

Embedded-to-external assistant​

After a cold backup, the assistant states that history is not copied, tests the HTTPS/TLS/authentication/ILM policy twice, and saves backend and connector. It then writes a canary with the connector credential and requires the backend credential to read it. Local Elasticsearch stops only after that ingestion receipt. A write/read failure restores configuration and preserves embedded. Canary cleanup is best-effort and does not require connector delete privileges. Returning to embedded requires reinstall.

Embedded-to-external migration assistant

Setup temporarily unavailable​

SPOT opens initial setup only when it can conclusively determine whether a local administrator already exists. If that state cannot be verified, it blocks both the form and the rest of the product and shows Setup temporarily unavailable with a Retry action. This prevents an operational failure from reopening first-administrator enrollment.

Safe setup blocking state while administrator status cannot be verified

When this state appears:

  1. Confirm that the SPOT service is running and that its authentication storage is accessible to the service account.
  2. Review service logs and correct permissions, disk availability, or a temporary lock.
  3. Do not delete the store or try to create another first administrator.
  4. Select Retry after correcting the cause. SPOT requests only status again and loads configuration after the check becomes conclusive.

With local access, /api/setup/status returns HTTP 503 with code setup_state_unavailable while the block remains active. The response does not expose paths or internal details.

After saving​

  1. Check /api/setup/status if you have local access.
  2. Sign in with the first administrator.
  3. Open Landing and confirm that the target appears.
  4. If no data appears, review connector logs and RFC connectivity.
  5. Adjust users, thresholds, and AI before handing SPOT to operations.

After setup, manage status, usage, and renewal from Configuration > License. See Licenses and renewal.