Skip to main content

Portable / non-root

Choose spot-agent-sap-portable, spot-suite-portable, or spot-suite-external-portable, each in a separate $SPOT_HOME.

For example, extract the embedded suite into a fresh $SPOT_HOME:

umask 077
mkdir -p "$HOME/spot"
tar -xzf spot-suite-portable_X.Y.Z_linux_amd64.tar.gz -C "$HOME/spot" --strip-components=1
cd "$HOME/spot"
cp config/spot.env.example config/spot.env

Use spot-suite-external-portable_X.Y.Z_linux_amd64.tar.gz for the external suite. For connector-only, use spot-agent-sap-portable_X.Y.Z_linux_amd64.tar.gz and extract it to $HOME/spot-agent-sap-portable if you want to reuse the included units without changes. Never mix variants or extract over another variant. The Connector-only guide contains the complete checksum, configuration, license, systemd --user, upgrade, and uninstall procedure.

Activate or install the license​

Before the first run-agent.sh, start the included validator and activate the online key or install the offline file:

export SPOT_HOME="$HOME/spot"
"$SPOT_HOME/scripts/run-license.sh" >"$SPOT_HOME/log/license.out" 2>"$SPOT_HOME/log/license.err" &
"$SPOT_HOME/bin/spot-agent-sap" license-activate
# or: "$SPOT_HOME/bin/spot-agent-sap" license-install /protected/path/license
"$SPOT_HOME/bin/spot-agent-sap" license-check

For connector-only, set SPOT_HOME to the directory where you extracted spot-agent-sap-portable. Never pass the key as a positional argument. See Licenses and renewal for renewal export without a web interface.

Encrypt the SAP password​

The portable wrapper derives and exports its own SPOT_HOME, so you can generate the passwd value before the first startup:

"$HOME/spot-agent-sap-portable/bin/spot-agent-sap" encrypt

Copy the single enc:v1:... line into the SAP connection. The first execution creates $HOME/spot-agent-sap-portable/config/spot-sap-secret.key with mode 0600 if it does not exist. Keep that file in the backup: do not regenerate it during an upgrade or replace it with one from another installation. See Connector-only for --stdin, --password-file, permissions, and automation examples.

Start only the processes included in the selected variant:

# Embedded suite
SPOT_HOME="$HOME/spot" scripts/run-elasticsearch.sh
SPOT_HOME="$HOME/spot" scripts/run-server.sh
SPOT_HOME="$HOME/spot" scripts/run-agent.sh

# External suite
SPOT_HOME="$HOME/spot" scripts/run-server.sh
SPOT_HOME="$HOME/spot" scripts/run-agent.sh

# Connector-only (in its own SPOT_HOME)
SPOT_HOME="$HOME/spot-agent-sap-portable" \
  "$HOME/spot-agent-sap-portable/scripts/run-agent.sh"

External contains no Elasticsearch directory or script and may finish setup in limited mode. Connector-only contains neither a local backend nor Elasticsearch.

All configuration, state, logs, and temporary files remain below $SPOT_HOME; there must be no required writes to /opt, /etc, or /var. Use a dedicated user and a user supervisor. The same user owns code and process, so choose RPM/DEB when real ownership separation is required.

Apply connector configuration​

Always edit $SPOT_HOME/config/spot-agent-sap.yaml. Every run-agent.sh invocation recreates $SPOT_HOME/run/spot-agent-sap.yaml from that file, publishes it atomically with mode 0600, and passes the same copy to elastic-bootstrap and the daemon. Do not edit or delete the copy under run/ to apply a change; restart the supervised process or run the script again.

In a portable suite with a local or hybrid connector, saving in the UI persists the configuration first and applies the change serially. An identical save does not restart a healthy agent. If SPOT cannot identify, stop, or start the correct process, it shows a retryable error and neither reports false success nor starts a duplicate. Inspect the reported process and retry the same save; that retry also applies a change that was already persisted.

Clean installation with existing configuration​

Extract the artifact into an empty $SPOT_HOME and verify its checksum first. You can load the target configuration again and install an offline license file that is valid for that host. Use license-install for the license; do not copy an old run/spot-agent-sap.yaml, because startup recreates it.

If config/spot-agent-sap.yaml retains encrypted passwords (enc:v1: or the compatible legacy format), also restore the original config/spot-sap-secret.key with mode 0600. Without that key, re-enter the SAP passwords so SPOT can encrypt them with the new installation's key. A different key cannot decrypt the existing ciphertext.

For upgrades, verify the checksum, extract into a new directory, copy only documented mutable state, and retain the old generation until health and ingestion pass. Never extract over the active tree.

Verification by variant​

Embedded suite​

curl -fsS http://127.0.0.1:9200
curl -fsS http://127.0.0.1:8080/api/health

External suite​

SPOT_HOME="${SPOT_HOME:-$HOME/spot}"
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8080/api/setup/status | \
  jq -e '.elastic_configuration_state == "pending" and .operational_ready == false'

If Elasticsearch was deferred, the public setup status must report pending and operational_ready=false. A real data API called with a valid Bearer token returns HTTP 503 with code elastic_not_configured. After configuration, verify health and ingestion against the external cluster; do not probe local :9200.

Connector-only​

SPOT_HOME="${SPOT_HOME:-$HOME/spot-agent-sap-portable}"
test -x "$SPOT_HOME/bin/spot-agent-sap"
pgrep -af "$SPOT_HOME/bin/spot-agent-sap"
tail -n 100 "$SPOT_HOME/log/spot-agent-sap.log"
test ! -e "$SPOT_HOME/scripts/run-elasticsearch.sh"

No local backend or run-elasticsearch.sh is expected. Use $HOME/spot-agent-sap-portable as the default when installing the included systemd --user units. See Connector-only for persistent startup and safe runtime-configuration regeneration after a change.