Installation Guide

This guide ties together the checked-in deployment helpers into one end-to-end install path for Sentinel Secure X.

Use it when you want a practical sequence for:

• installing the Linux control plane
• placing the API behind a reverse proxy
• deploying endpoint agents on supported operating systems
• publishing the optional agent bundle downloads used by the dashboard and landing page

1. Choose your deployment shape

Sentinel Secure X is split into two parts:

• The control plane: Flask API, PostgreSQL database, and background workers
• The endpoint agent: installed on managed devices running Linux, Windows, or macOS

Recommended production shape:

1. Run the control plane on a Linux host.
2. Put NGINX in front of the API for browser TLS and device mTLS.
3. Run PostgreSQL instead of SQLite.
4. Install the endpoint agent on each managed device with the platform-specific service wrapper.

2. Prerequisites

Before you begin, make sure you have:

• a Linux server for the control plane
• Python 3.12 or another supported Python 3 runtime
• PostgreSQL reachable from the control-plane host
• a DNS name for the dashboard and API
• a certificate strategy for browser TLS and device certificates
• a reverse proxy host path for NGINX

Recommended references before install:

• production_profile.md
• README.md
• deploy/systemd/README.md
• deploy/nginx/README.md

3. Prepare the control-plane checkout

From the repository root:

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env

Set production values in .env before you continue.

At minimum, replace:

• SENTINEL_DATABASE_URI
• SENTINEL_SECRET_KEY
• SENTINEL_JWT_SECRET
• SENTINEL_ADMIN_PASSWORD_HASH
• SENTINEL_DATA_ENCRYPTION_KEYS_JSON
• SENTINEL_DATA_ACTIVE_KEY_ID
• SENTINEL_ALLOWED_ORIGINS
• SENTINEL_MONITORING_BEARER_TOKEN

If you use WebAuthn or passkeys in production, also set:

• SENTINEL_WEBAUTHN_RP_ID
• SENTINEL_WEBAUTHN_RP_NAME
• SENTINEL_WEBAUTHN_ALLOWED_ORIGINS

4. Generate admin and secret values

Create an admin password hash:

./.venv/bin/python -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('change-me'))"

Generate session, JWT, and data-protection keys:

./.venv/bin/python - <<'PY'
from cryptography.fernet import Fernet
import secrets

print("SENTINEL_SECRET_KEY=" + secrets.token_urlsafe(48))
print("SENTINEL_JWT_SECRET=" + secrets.token_urlsafe(48))
print('SENTINEL_DATA_ENCRYPTION_KEYS_JSON={"v1":"' + Fernet.generate_key().decode() + '"}')
print("SENTINEL_DATA_ACTIVE_KEY_ID=v1")
print("SENTINEL_MONITORING_BEARER_TOKEN=" + secrets.token_urlsafe(32))
PY

Paste the generated values into .env.

5. Run preflight and migrations

Validate the runtime posture before you start services:

make server-preflight ENV_FILE=.env

Apply database migrations:

make db-upgrade

For production, keep:

• SENTINEL_DATABASE_REQUIRE_POSTGRESQL=true
• SENTINEL_AUTO_CREATE_SCHEMA_ON_BOOT=false

6. Install Linux services

Render and install the Linux systemd units:

sudo ./.venv/bin/python deploy/systemd/install_services.py \
  --output-dir /etc/systemd/system \
  --install-root "$(pwd)" \
  --python-executable "$(pwd)/.venv/bin/python" \
  --user sentinel \
  --group sentinel \
  --env-file "$(pwd)/.env" \
  --services api worker maintenance scheduled-job-coordinator update-campaign-scheduler \
  --reload-systemd \
  --enable \
  --start

Smoke-test the installed services:

./.venv/bin/python deploy/systemd/smoke_test_services.py \
  --services api worker maintenance scheduled-job-coordinator update-campaign-scheduler \
  --base-url http://127.0.0.1:8000

For more detail, see deploy/systemd/README.md.

7. Put NGINX in front of the API

Production deployments should leave the Flask listener on the local host and terminate TLS at NGINX.

Run the proxy-aware preflight:

./.venv/bin/python -m server.preflight \
  --env-file .env \
  --expect-proxy-cert-headers

Then render and install the proxy config:

sudo ./.venv/bin/python deploy/nginx/install_mtls_proxy.py \
  --output-path /etc/nginx/conf.d/sentinel-secure-x.conf \
  --server-name sentinel.example.com \
  --tls-cert-path /etc/nginx/certs/server.crt \
  --tls-key-path /etc/nginx/certs/server.key \
  --client-ca-path /etc/nginx/certs/device-ca.crt \
  --upstream-url http://127.0.0.1:8000 \
  --env-file .env \
  --check-nginx-config \
  --reload-nginx

Required production settings for this path:

• SENTINEL_REQUIRE_DEVICE_MTLS=true
• SENTINEL_TRUST_PROXY_CERT_HEADERS=true

Then smoke-check the proxy:

./.venv/bin/python deploy/nginx/smoke_test_proxy.py \
  --base-url https://sentinel.example.com

For more detail, see deploy/nginx/README.md.

8. Enroll endpoint agents

After the control plane is reachable, install the endpoint agent on your managed devices.

Linux agent

Use the agent systemd unit from deploy/systemd/README.md when you want the endpoint installed as a Linux service.

Windows agent

Use the one-step service path in deploy/windows/README.md:

.\deploy\windows\preflight-agent-config.ps1
.\deploy\windows\install-agent-service.ps1

macOS agent

Use the launchd path in deploy/macos/README.md:

./.venv/bin/python -m agent.config --config-path agent/config.json
sudo ./.venv/bin/python deploy/macos/install_agent_launchd.py \
  --install-root "$(pwd)" \
  --python-executable "$(pwd)/.venv/bin/python" \
  --config-path "$(pwd)/agent/config.json" \
  --output-dir /Library/LaunchDaemons \
  --bootstrap \
  --kickstart \
  --smoke-test

9. Optional: publish agent bundles at /downloads/

If you want the landing page and dashboard download links to work in your deployment, publish the built agent bundles under /downloads/.

First build them:

make build-agent-bundles

That creates:

• build/agent-bundles/sentinel-secure-x-agent-linux.tar.gz
• build/agent-bundles/sentinel-secure-x-agent-macos.tar.gz
• build/agent-bundles/sentinel-secure-x-agent-windows.zip
• build/agent-bundles/manifest.json

Then expose them through your reverse proxy. One NGINX pattern is:

location = /downloads {
    return 302 /downloads/;
}

location /downloads/ {
    alias /var/www/securex-downloads/;
    index index.html;
}

Copy the built bundle files plus any generated index.html or checksum metadata into that published directory.

10. Post-install verification checklist

After installation:

1. Open the landing page and dashboard over HTTPS.
2. Confirm GET /api/health/live returns 200.
3. Confirm GET /api/health/ready returns ready: true.
4. Sign in with the configured admin account.
5. Confirm service status shows healthy API and worker heartbeats.
6. Install one test endpoint agent and verify a heartbeat reaches the control plane.
7. Review enrollment and identity approval behavior before you add real production devices.

11. Recommended next steps

After the base install works, tighten the deployment further with:

• CRL and OCSP configuration for device certificates
• multi-admin role separation
• passkey enrollment for operator accounts
• signed update manifests and rollout governance
• signed evidence exports and recovery workflows

Use these references next:

• user_manual.md
• operator_api_workflows.md
• production_profile.md