Skip to content

Deploy the platform

This guide walks you through the full installation of Sekoia Self-Hosted, from downloading the release archive to validating a healthy platform state. Follow the steps in order.

Prerequisites

Preparation

Step 1: Download and verify the release archive

Sekoia provides access to a dedicated object storage bucket containing the release archive and its SHA-256 checksum. You receive the bucket credentials (endpoint, access key, and secret key) from Sekoia after contract validation.

Verify before you extract

Always verify the checksum before extracting the archive. A mismatch indicates a corrupted or incomplete download. Do not proceed if verification fails. Download the archive again before retrying.

Download the archive and its checksum file, then verify integrity. Fill in your credentials where indicated.

AWS CLI 
export AWS_ACCESS_KEY_ID=""
export AWS_SECRET_ACCESS_KEY=""
export AWS_DEFAULT_REGION="fr-par"
export ENDPOINT="https://fr-par-13.linodeobjects.com"
export BUCKET="self-hosted"
export KEY="archives/sekoia-self-hosted-v0.1.0.tar"
export OUT="sekoia-self-hosted-v0.1.0.tar"
export AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
export AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED

aws --endpoint-url "$ENDPOINT" s3 cp "s3://$BUCKET/$KEY" "$OUT"
aws --endpoint-url "$ENDPOINT" s3 cp "s3://$BUCKET/$KEY.sha256" "$OUT.sha256"

sha256sum -c "$OUT.sha256"

AWS CLI v2 checksum compatibility

AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED and AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED disable the automatic checksum behavior introduced in AWS CLI v2, which is incompatible with non-AWS S3-compatible providers.

rclone 
export RCLONE_CONFIG_SEKOIA_TYPE="s3"
export RCLONE_CONFIG_SEKOIA_PROVIDER="Other"
export RCLONE_CONFIG_SEKOIA_ACCESS_KEY_ID=""
export RCLONE_CONFIG_SEKOIA_SECRET_ACCESS_KEY=""
export RCLONE_CONFIG_SEKOIA_ENDPOINT="https://fr-par-13.linodeobjects.com"
export RCLONE_CONFIG_SEKOIA_REGION="fr-par"

rclone copyto sekoia:self-hosted/archives/sekoia-self-hosted-v0.1.0.tar ./sekoia-self-hosted-v0.1.0.tar
rclone copyto sekoia:self-hosted/archives/sekoia-self-hosted-v0.1.0.tar.sha256 ./sekoia-self-hosted-v0.1.0.tar.sha256

sha256sum -c sekoia-self-hosted-v0.1.0.tar.sha256

Expected output: sekoia-self-hosted-v0.1.0.tar: OK

Step 2: Transfer and extract the archive

To transfer the archive to the orchestration node if you downloaded it on a separate machine, run:

scp sekoia-self-hosted-v0.1.0.tar user@<ORCHESTRATION_NODE>:$SEKOIA_LOCAL_DIR

Disk space

Ensure at least 150 GB of available disk space at the destination before extracting.

To extract the archive on the orchestration node, run:

tar -xvf sekoia-self-hosted-v0.1.0.tar -C $SEKOIA_LOCAL_DIR

Step 3: Load the self-hosted-controller (SHC) Docker image

For the first installation, the SHC image is not yet available on the orchestration node. Load it manually from the extracted archive:

docker load -i $SEKOIA_LOCAL_DIR/v0.1.0/images/registry.sekoia.io_sekoialab_self-hosted-controller-cli-v0.1.0.tar.gz

To confirm the image loaded successfully, run:

docker images | grep self-hosted-controller

Air-gapped deployments

In air-gapped environments, the SHC image is always loaded from the local archive. After loading, tag the image and export its reference to override the default DOCKER_IMAGE value used by the execution script:

docker tag <IMAGE_ID> sekoialab/self-hosted-controller-cli:v0.1.0
export DOCKER_IMAGE="sekoialab/self-hosted-controller-cli:v0.1.0"

Replace <IMAGE_ID> with the image ID returned by docker images.

Step 4: Create the execution script

The execution script run-shc.sh wraps all SHC invocations, injects credentials from environment variables, and mounts your config file into the container.

Create a file named run-shc.sh with the following content:

#!/bin/bash
DOCKER_IMAGE="${DOCKER_IMAGE:-sekoialab/self-hosted-controller-cli:latest}"

# Allocate a TTY when the script runs in a terminal, so the interactive
# interface can render. Skipped in non-interactive contexts such as CI.
TTY_FLAGS=""
[ -t 0 ] && [ -t 1 ] && TTY_FLAGS="-it"

docker run --rm $TTY_FLAGS \
  -e SERVERS_SUDO_PASSWORD="$SERVERS_SUDO_PASSWORD" \
  -e SERVERS_SSH_KEY="$SERVERS_SSH_KEY" \
  -e STORAGE_S3_REGION="$STORAGE_S3_REGION" \
  -e STORAGE_S3_ENDPOINT="$STORAGE_S3_ENDPOINT" \
  -e STORAGE_S3_ACCESS_KEY="$STORAGE_S3_ACCESS_KEY" \
  -e STORAGE_S3_SECRET_KEY="$STORAGE_S3_SECRET_KEY" \
  -e REGISTRY_USERNAME="$REGISTRY_USERNAME" \
  -e REGISTRY_PASSWORD="$REGISTRY_PASSWORD" \
  -e GIT_HTTP_USERNAME="$GIT_HTTP_USERNAME" \
  -e GIT_HTTP_PASSWORD="$GIT_HTTP_PASSWORD" \
  -e SEKOIA_INSTANCE_PUBLIC_KEY="$SEKOIA_INSTANCE_PUBLIC_KEY" \
  --network=host \
  -v $SEKOIA_CONFIG_FILE:/tmp/config.yaml \
  -v $SEKOIA_LOCAL_DIR:/opt/sekoia \
  ${DOCKER_IMAGE} -c /tmp/config.yaml "$@"

Set the following environment variables on the orchestration node before running the script:

Variable Required Description
SEKOIA_LOCAL_DIR Yes Absolute path to the directory where you extracted the release archive.
SEKOIA_CONFIG_FILE Yes Absolute path to your config.yml manifest on the orchestration node.
SERVERS_SSH_KEY Yes SSH private key used to connect to Kubernetes nodes.
STORAGE_S3_REGION Yes Region of the S3-compatible platform storage.
STORAGE_S3_ENDPOINT Yes Endpoint of the S3-compatible platform storage.
STORAGE_S3_ACCESS_KEY Yes Access key for the S3-compatible platform storage.
STORAGE_S3_SECRET_KEY Yes Secret key for the S3-compatible platform storage.
REGISTRY_USERNAME Yes Username for your local OCI registry.
REGISTRY_PASSWORD Yes Password for your local OCI registry.
GIT_HTTP_USERNAME Yes Username for your local code repository.
GIT_HTTP_PASSWORD Yes Password or token for your local code repository.
SERVERS_SUDO_PASSWORD No Sudo password for target nodes, if required by your SSH configuration.
DOCKER_IMAGE No Override the self-hosted-controller (SHC) Docker image reference. Required in air-gapped environments.
SEKOIA_INSTANCE_PUBLIC_KEY Yes Public key for the SEKOIA instance.

To make the script executable and verify the SHC responds, run:

chmod +x run-shc.sh
./run-shc.sh list

A successful run displays the full list of available SHC commands.

Commands in this documentation

Commands elsewhere in this documentation omit the ./run-shc.sh prefix. Enter them as shown in the TUI, or prefix them with ./run-shc.sh to run them in one-shot CLI mode.

Interactive interface

Running ./run-shc.sh with no command opens the interactive interface of the SHC instead of returning a one-shot result. See Use the SHC interface.

Deployment

Choose one of the two deployment options below.

Option 1: Bundle deployment

The bundle command runs all installation steps sequentially. This is the simplest path for standard deployments.

To run the full installation, enter:

exec Install

The platform installation is normally the longest stage. Leave the command running while it continues to emit progress messages, then wait for the final convergence report before proceeding to Post-deployment validation.

Pre-release installation logs

Warning-level log messages can be normal while Self-Hosted 0.1.0 remains in pre-release. Do not interrupt an installation only because a warning appears while the workflow continues to make progress. The installation has completed when the terminal Install.start terminated message reports success=True and the post-deployment validation passes. Investigate a terminal success=False result, exhausted retries, or a workflow that stops making progress.

Option 2: Step-by-step deployment

Use this option when your environment requires manual validation or approval between stages.

Step 1: Run preflight checks.

To validate the environment before any changes are made, run:

exec CheckLocalConfig
exec CheckLocalGit
exec CheckLocalOCIRegistry
exec CheckLocalReleaseFiles
exec CheckServersAreReachable
exec CheckServerSpec
exec CheckLocalTools

Preflight block

The SHC will not proceed if any critical validation check fails. Each failure is logged with an actionable error message. Resolve all errors before continuing.

CheckServerSpec fails the installation when a manager or worker node does not have 44 CPU cores and 120 GiB of RAM, does not run Debian 12 or later, has no unused 200 GB block device, shares its hostname with another node, or has no synchronized clock. See CheckServerSpec for each failure message and its remediation.

Step 2: Configure servers.

Run the server-configuration stage:

exec ConfigureServersWithAnsible

0.1.0 pre-release behavior

In the 0.1.0 pre-release, ConfigureServersWithAnsible is a placeholder and may complete immediately without changing the nodes. Provision the operating system and packages required by Technical requirements before continuing.

Step 3: Provision local registries.

First resolve the versioned detection-rules, intake-formats, and playbook-library bundles. Then push all Docker images, Helm charts, and ArgoCD stack manifests to your local repositories:

exec DownloadDataFiles
exec PushImages
exec PushCharts
exec PushArgoStacks

Each push module runs DownloadReleaseFiles as an automatic prerequisite. In online mode, it downloads missing release artifacts; in air-gapped mode, it uses the artifacts staged locally. Repeated runs skip release files and images already present, and PushArgoStacks succeeds without a commit when the generated manifests are unchanged.

Step 4: Install the Kubernetes stack.

To install K3s and deploy the cluster services, run:

exec K3SInstall
exec GetKubeconfig
exec HelmInstall
exec CheckKubernetesCluster

Step 5: Deploy the Sekoia platform.

To generate the platform configuration, run the installer job, and retrieve the initial access credentials, run:

exec PlatformConfigurationFile
exec PlatformInstallation
exec PlatformAccess

Step 6: Bootstrap and scale the platform.

To provision the default storage and the per-community ExaLog indexes, then scale the ingestion and detection workers to their configured replica count, run:

exec InstanceBootstrap
exec ScaleServices

Run these two modules in this order. Until InstanceBootstrap completes, ExaLog has no index and cannot write events to your S3-compatible storage. See Post-installation bootstrap for what each module provisions.

Repeated prerequisite modules

The SHC automatically retrieves a current kubeconfig before cluster and platform operations. PlatformInstallation and PlatformAccess also regenerate the platform configuration before running. Repeated GetKubeconfig and PlatformConfigurationFile entries in the log are expected and allow each module to run independently.

Post-deployment validation

After the installation completes, run the following checks to confirm the platform is healthy before directing users to it.

Step 1: Verify cluster node health.

To confirm all nodes joined the cluster and are ready, run:

exec CheckKubernetesCluster
Expected output 
Kubernetes cluster is healthy nodes=6 expected=6

If the node count does not match, check kubectl get nodes to identify which node is missing.

Step 2: Check application sync and health status.

To inspect every ArgoCD application, run:

exec DebugArgoCD

Every application must show Sync: Synced and Health: Healthy. Progressing is normal for a few minutes immediately after deployment. Degraded or OutOfSync requires investigation. See Debug your deployment.

Step 3: Verify database availability.

To confirm all database StatefulSets and CNPG clusters are ready, run:

exec DebugDatabases

All entries must report Healthy status with the expected number of ready replicas.

Step 4: Check the health of the platform services.

To run every bundled diagnostic target against the platform's Prometheus metrics, run:

exec Diagnostic

Every check must report OK. A CRIT or WARN result names the affected service, its likely causes, and the remediation actions. See Run platform diagnostics.

Step 5: Access the platform.

To open the Sekoia interface, navigate to the URL set in global.host of your config.yml (for example, https://app.sekoia.local).

First login

PlatformAccess returns the generated instance-administrator credentials at the end of the installation. Store them securely, then use them to create your first operational community. See Set up the first administrator account.