Administering Keen

Install and configure Keen

Chapter 1 of 30

Runtime and responsibilities

This chapter gets a self-managed Keen running: what the containers do, how to deploy and upgrade, the settings that matter on day one, and the Features switches that decide which parts of Keen your organisation sees.

Keen runs as a small set of services:

Admin ingest runners queue collection and return a task ID. A queued confirmation means the job was accepted, so check the worker results and logs to see it finish.

Artefacts live in the configured local storage or S3-compatible storage, and the API and worker must see the same artefacts. PostgreSQL holds the references, mappings and configuration that give those objects meaning, so a complete backup includes both.

Deploy a self-managed installation

You need a supported Docker Engine and Compose plugin, DNS for the application, a trusted TLS certificate, and storage for the database and artefacts. The supplied Compose file uses the published Keen images and pins the PostgreSQL and Valkey images by digest, so docker compose pull fetches the builds reviewed for that release.

1. Place the release files in the deployment directory and record the release or commit you used.
2. Create a protected .env from the release's settings: database, Valkey, public URL, authentication and artefact backend, with unique secrets.
3. Configure the HTTPS proxy and firewall, keeping internal services on the private Compose network.
4. Pull the images, start the backing services, apply the migrations, then start the application services.
5. Verify HTTPS, sign-in, the framework catalogues, an artefact round trip, one ingestion, and a restore into a separate test environment.

From the keen directory, with the supplied self-managed layout:

docker compose pull
docker compose up -d postgres valkey
docker compose run --rm keen-api alembic upgrade head
docker compose up -d
docker compose ps
docker compose logs --tail=100 keen-api keen-worker keen-beat

The API startup script applies migrations as well; the explicit step makes a failure visible before the rest of an upgrade proceeds. Never run two migration processes against the same database.

Create the first administrator

Set KEEN_BOOTSTRAP_ADMIN_USERNAME and KEEN_BOOTSTRAP_ADMIN_PASSWORD before the first start. Once that administrator can sign in, remove both variables and recreate the containers; the database keeps the account and its current password. Migrations, workers and later API starts do not need them.

Configure the runtime

The definitive list of settings is services/api/app/core/config.py. Most fields use the KEEN_ prefix; some connector secrets have explicit aliases. Apply the same relevant settings to API, worker and beat, and recreate a container after changing its environment: editing .env on the host changes nothing in a running container.

Core and authentication settings

Native OIDC, Google and GitHub

Native OIDC uses KEEN_OIDC_ENABLED, the issuer, authorisation and token endpoints, the JWKS URI, client ID, client secret, scopes and an exact redirect URI. The redirect URI sits on KEEN_PUBLIC_BASE_URL and ends in /api/v1/auth/sso/oidc/callback, /api/v1/auth/sso/google/callback or /api/v1/auth/sso/github/callback for the provider concerned. Register the same address with the provider; Keen refuses provider sign-in until each enabled provider has its redirect URI set.

Google and GitHub have their own enablement, client and claim settings. Provision authorised local identities according to the selected mode, and keep automatic provisioning restricted to the identities you intend to admit.

Storage, mail and privacy settings

KEEN_ARTIFACT_STORAGE_BACKEND selects the artefact backend and KEEN_ARTIFACT_LOCAL_DIR sets local storage. For S3, configure the bucket, region, endpoint and credentials; KEEN_S3_USE_INSTANCE_ROLE enables the AWS credential chain in the hosted integration, and its tenant role is never combined with broad static AWS credentials.

SMTP settings are KEEN_SMTP_HOST, port, username, password, TLS or SSL mode, sender address and name, and timeout. Match the TLS mode to the mail service.

Masking personal data

KEEN_EVENT_DATA_MASKING controls optional masking of e-mail and IP addresses, which are recognised by their shape:

• true masks every stored text field, structured payload and text artefact as evidence arrives, including mail headers such as From and To, where a display name written with its address is masked with it.
• samples masks the same text in evidence PDF and ZIP exports only.
• false keeps the data.

KEEN_SENSITIVE_KEYS removes the whole value of named fields instead. Sample PDF header and footer and the evidence filename prefix control export presentation; review an exported sample to confirm the wording and data treatment. Collect only what assurance needs, and treat automatic secret redaction as a safeguard that can miss an unusual secret.

Choose the features available in Keen

Open Administration → Features to switch workspaces and tools on or off for the whole installation. Everything starts enabled, each switch saves immediately, and the status message confirms the change. Only administrators can change these settings.

A parent switch controls its children. Turning off ISMS makes SWOT, Objectives, documents, assets and its other subsections unavailable; turning off Risk management also turns off the Mitigator, CIA assessments, the risk register, PESTLE(E) and Interested parties. Child preferences are kept and return when the parent is enabled again.