diff --git a/docs/poc/CONFIGURATION.md b/docs/poc/CONFIGURATION.md index bd9491a..4351dc3 100644 --- a/docs/poc/CONFIGURATION.md +++ b/docs/poc/CONFIGURATION.md @@ -105,6 +105,22 @@ Runs after `so1` is **healthy**. Uses Alpine, installs `curl` and `jq`, then run **`config.env`** is tracked and holds non-secret settings (`SPLUNK_IMAGE`, `TZ`). **`make up`** loads it after secrets, so a copy of those keys in a secret file does not win. Passwords are not stored there. +### Load order and effective config + +Host entrypoints that need stack secrets (`make up`, `make config`, token minting, S4R registration, NK shell fallback, and MCP auth stats) use the same helper path: + +1. **Secrets first** — `scripts/with-splunk-env.sh` sources **`.env`** when it exists. If **`.env`** is absent, it re-execs the caller under `op run --env-file=tpl.env`. If neither file exists, the command fails with Path A / Path B hints. +2. **Non-secrets second** — `scripts/load-config-env.sh` requires **`config.env`**, exports only `SPLUNK_IMAGE` and `TZ`, and ignores other keys. This is intentional: image and timezone come from the tracked file, not from stale copies in **`.env`** or **`tpl.env`**. +3. **Validation last** — callers that start or render Compose require non-empty `SPLUNK_PASSWORD`, `SPLUNKBASE_USER`, `SPLUNKBASE_PASS`, and `SPLUNK_MCP_PASSWORD`. + +Use **`make config`** before booting or after env edits to inspect the resolved Compose input without printing secret values: + +```bash +make config +``` + +It runs `docker compose config` after the same load path as **`make up`**. Secret fields in the rendered Compose output are shown as **``** when populated and as `""` when empty. `SPLUNKBASE_USER` / `SPLUNKBASE_PASS` appear in Compose as `SPLUNKBASE_USERNAME` / `SPLUNKBASE_PASSWORD`, matching the Splunk image environment names. + ### `tpl.env.example` and `tpl.env` - **`tpl.env.example`** is the **tracked** template (placeholder `op://` paths, safe to commit). @@ -145,7 +161,7 @@ For a **plaintext `.env`** on disk (no 1Password at `make up` time), copy [`.env | Target | Behavior | | ------ | -------- | | `up` | `scripts/compose-up.sh` (`.env` or `op run --env-file=tpl.env`), then `update-all` (`MCP_UPDATE_ON_BOOT`, default `cursor`), then `register-s4r-mcp-tools` | -| `config` | Print `docker compose config` after the same secret and `config.env` load as `up`. `SPLUNK_PASSWORD`, Splunkbase user/password, and `SPLUNK_MCP_PASSWORD` are shown as `` | +| `config` | Print `docker compose config` after the same secret and `config.env` load as `up`. `SPLUNK_PASSWORD`, `SPLUNKBASE_USERNAME`, `SPLUNKBASE_PASSWORD`, and `SPLUNK_MCP_PASSWORD` are redacted as `` when populated; empty values stay `""` | | `down` | `scripts/mcp-client.sh park all` (no secrets), then `docker compose down`. `config.env` must be present so Compose can read `SPLUNK_IMAGE` and `TZ` | | `park-mcp-clients` | `scripts/mcp-client.sh park all` — remove `splunk-mcp-server` from client configs | | `update-mcp-clients` | `scripts/mcp-client.sh update-all` for cursor, goose, claude (one mint) | diff --git a/docs/poc/INSTALLATION.md b/docs/poc/INSTALLATION.md index 0813ecb..ac98c73 100644 --- a/docs/poc/INSTALLATION.md +++ b/docs/poc/INSTALLATION.md @@ -129,6 +129,12 @@ op read "op://YourVault/Splunkbase/username" test -s .env ``` +Confirm the effective Compose input before the first boot. This uses the same secret path as **`make up`**, loads image/timezone from tracked **`config.env`**, and redacts populated secrets as **``**: + +```bash +make config +``` + Network and ports: - The host must reach **splunkbase.splunk.com** and the container registry that serves `SPLUNK_IMAGE`. diff --git a/docs/poc/PRESALES.md b/docs/poc/PRESALES.md index 13bcec9..ac520cc 100644 --- a/docs/poc/PRESALES.md +++ b/docs/poc/PRESALES.md @@ -49,7 +49,7 @@ make demo-prep # Splunkbase pins + status + MCP verify # Cursor: restart after make up (.cursor/mcp.json updated) ``` -Path B and env details: [CONFIGURATION.md](CONFIGURATION.md#tplenv-and-env). Long-form install: [INSTALLATION.md](INSTALLATION.md). +Path B and env details: [CONFIGURATION.md](CONFIGURATION.md#load-order-and-effective-config). Long-form install: [INSTALLATION.md](INSTALLATION.md). **Do not commit:** `tpl.env`, `.env`, or client configs with live tokens ([AGENTS.md](../../AGENTS.md)). @@ -65,7 +65,7 @@ Secrets are **not generated by this repo**; they come from **1Password** (`op:// - **Path A (`tpl.env`, no `.env`):** `make up` runs `op run --env-file=tpl.env -- docker compose up -d`. Vault values are resolved **only for that process**—no plaintext `.env` on disk. - **Path B (`.env`):** Copy **`.env.example` → `.env`**, fill plain values. `make up` uses plain `docker compose`; Compose auto-loads **`.env`**. Use for CI or machines without 1Password. -See [CONFIGURATION.md](CONFIGURATION.md#tplenv-and-env). +See [CONFIGURATION.md](CONFIGURATION.md#load-order-and-effective-config). ## What you are demoing (URLs and roles) diff --git a/docs/poc/TROUBLESHOOTING.md b/docs/poc/TROUBLESHOOTING.md index 9ad136c..2fb178b 100644 --- a/docs/poc/TROUBLESHOOTING.md +++ b/docs/poc/TROUBLESHOOTING.md @@ -306,6 +306,24 @@ Edit **`tpl.env`** with your `op://` paths. **`tpl.env`** is gitignored—do not --- +#### Issue: `make config` fails or shows blank Compose inputs + +**Context**: `make config` is the safe preflight for Compose input. It uses the same secret loader as **`make up`**, then loads tracked **`config.env`**, and redacts populated secret fields as **``**. + +**Common symptoms and fixes**: + +| Symptom | Meaning | Fix | +| ------- | ------- | --- | +| `Error: need .env or tpl.env for Splunk secrets` | Neither Path A nor Path B is configured | Copy **`tpl.env.example`** to **`tpl.env`** and sign in to `op`, or copy **`.env.example`** to **`.env`** and fill plain values | +| `1Password CLI (op) not available` | Path A was selected but `op` cannot run | Install/sign in to **`op`**, or use Path B with a gitignored **`.env`** | +| `Error: missing config.env (SPLUNK_IMAGE and TZ)` | The tracked non-secret config file is absent | Restore **`config.env`** from git; do not move `SPLUNK_IMAGE` / `TZ` into a secret file | +| `SPLUNK_PASSWORD: ""`, `SPLUNKBASE_USERNAME: ""`, `SPLUNKBASE_PASSWORD: ""`, or `SPLUNK_MCP_PASSWORD: ""` | A required secret resolved empty | Fix the matching **`.env`** value or **`tpl.env`** `op://` path, then re-run **`make config`** | +| Image or timezone differs from what you expected in **`.env`** | **`config.env`** wins over stale copies in secret files | Edit **`config.env`** for `SPLUNK_IMAGE` / `TZ`; keep secret files for passwords and Splunkbase credentials only | + +If **`make config`** is clean but **`docker compose up -d`** still fails, make sure you started through **`make up`** or **`./scripts/compose-up.sh`**. Bare **`docker compose up`** does not run the helper path unless a populated **`.env`** already exists. + +--- + #### Issue: Splunk logs show `Invalid Splunkbase credentials` / ansible inventory errors **Cause**: The **`so1`** container was created with **empty** `SPLUNKBASE_USER` / `SPLUNKBASE_PASS` (and often `SPLUNK_PASSWORD`). That happens if you run **`docker compose up -d`** without a **`.env`** file and without **`op run --env-file=tpl.env`**—Compose substitutes blank strings, and Splunk’s entrypoint refuses Splunkbase downloads.