stroblmeandClaude Opus 5
11e032386b
A zensical site under docs/, served by a new `docs` compose service behind Traefik, built with --strict in CI. Same pattern the sibling n3xd workspace uses. Getting started splits the way the landing page does — one path is `pip install fluksio` and a training script, the other is a Docker stack and an afternoon in the browser — because the two audiences will not spend the same amount of time. Everything after that is shared: the concepts, the web interface (app and portal), the CLI and the API, and a reference for node types, payload types and configuration. The three flow guides move here from the docs submodule rather than being copied, so there is one version of them. Styling mirrors DESIGN-GUIDELINES.md: the app's token palette remapped onto Material's variables in both schemes, Inter, the 16px panel radius, and the one terracotta accent spent on the facility lane of the audience split. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M7Xv3cJEW5c8AXxn2hoojV
132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# Secrets, modules and alerts
|
|
|
|
Three screens that have nothing to do with each other except that an
|
|
installation you actually depend on needs all of them.
|
|
|
|
## Secrets
|
|
|
|
A node never holds a credential. A parameter written as
|
|
|
|
```json
|
|
{"$secret": "influx-token"}
|
|
```
|
|
|
|
is replaced with the stored value when the node is built, and the editor
|
|
renders any field a node type marks as a credential as a picker over what you
|
|
have stored.
|
|
|
|
**Secrets** is where the values live. Add a name and a value; the value is
|
|
never shown again, and the list only ever shows names.
|
|
|
|
They are encrypted at rest with a key derived from the installation's
|
|
`SECRET_KEY`, and kept **outside** the flow repository. That matters because
|
|
flows are a git repository you may well push somewhere: what gets committed and
|
|
shared never contains a password.
|
|
|
|
A name that no longer resolves is a clear error on the node that wanted it —
|
|
"No secret named 'x' — add it under Secrets" — rather than a mysterious
|
|
authentication failure.
|
|
|
|
!!! warning "Rotating `SECRET_KEY`"
|
|
|
|
The secrets store is encrypted with a key derived from it. Change
|
|
`SECRET_KEY` and the store no longer decrypts. Re-enter the secrets, or
|
|
plan the rotation properly.
|
|
|
|
## Modules
|
|
|
|
Node code runs in a virtual environment of its own, on the installation's data
|
|
volume — separate from the packages Fluksio itself runs on. A pin of yours can
|
|
never shadow one of ours, and vice versa.
|
|
|
|
**Modules** is a pip manifest and an **Apply** button. It is installed with
|
|
`uv pip sync`, so a line you delete is uninstalled rather than left behind.
|
|
The manifest is versioned alongside your flows, so what a deployment installed
|
|
is recorded with what uses it.
|
|
|
|
The page shows what is currently installed, the interpreter's Python version,
|
|
and whether the manifest and the environment agree. A failed resolve comes back
|
|
as `uv`'s own output, in the pane, because that is the only thing anyone can
|
|
act on.
|
|
|
|
An install takes effect immediately — the worker processes pick up the new
|
|
interpreter state without the engine restarting.
|
|
|
|
!!! note "Big scientific stacks"
|
|
|
|
Installing torch into this venv works and is often the simplest thing. The
|
|
alternative, when you already have an environment you would rather not
|
|
duplicate, is to attach it as a worker: `fluksio-worker --python
|
|
/path/to/venv/bin/python`. See [Remote workers](../code/workers.md).
|
|
|
|
## Alerts
|
|
|
|
Everything that goes wrong already travels the engine's event bus. Alerts is
|
|
where you say who hears about it.
|
|
|
|
### Channels
|
|
|
|
| Kind | Settings |
|
|
|---|---|
|
|
| **ntfy** | server, topic, and a token for a protected topic |
|
|
| **SMTP** | an address to send to (the installation's mail settings do the rest) |
|
|
| **Webhook** | a URL to POST to |
|
|
| **Dashboard** | a message name a notification widget reads |
|
|
|
|
Any channel setting may hold a `{"$secret": "name"}` reference instead of a
|
|
literal, so a webhook URL with a token in it does not sit in the config.
|
|
|
|
### Rules
|
|
|
|
A rule is a set of events and the channels they go to. **A rule with no events
|
|
ticked covers all of them**, including ones added in later versions — which is
|
|
usually what you want for the first rule you write.
|
|
|
|
| Event | Fires when |
|
|
|---|---|
|
|
| `node_error` | a node failed |
|
|
| `node_health` | a connection dropped |
|
|
| `flow_quarantined` | a flow crashed often enough that the engine stopped restarting it |
|
|
| `task_crashed` | a background task crashed |
|
|
| `engine_degraded` | the engine is struggling |
|
|
| `cascade_dropped` | work was given up on |
|
|
| `queue_unavailable` | the work queue is unreachable |
|
|
|
|
**Test** sends one message through a channel so you find out it is misconfigured
|
|
now rather than at three in the morning.
|
|
|
|
### What it mostly does is not send
|
|
|
|
This is the part worth knowing before you decide it is broken:
|
|
|
|
- the same fault repeating is **one** alert, with a cooldown (15 minutes by
|
|
default per rule)
|
|
- a connection flapping is one story, not one alert per transition
|
|
- however bad it gets, **ten alerts an hour** is the ceiling
|
|
|
|
An engine that is genuinely on fire produces a handful of messages, not
|
|
thirty-six thousand.
|
|
|
|
## Admin: users
|
|
|
|
Superusers get an **Admin** screen: add, edit and remove accounts, and see who
|
|
is a superuser.
|
|
|
|
Accounts that arrived through a portal are badged *Portal*. They have no
|
|
password — they sign in at the portal, not here — and they are never
|
|
superusers. Deleting one cuts their access immediately and independently of the
|
|
portal, so it works even if the portal cannot be reached. See
|
|
[Accounts and the portal](portal.md).
|
|
|
|
The same screen manages OAuth clients, which is how [agents](../code/agents.md)
|
|
are registered.
|
|
|
|
## Settings
|
|
|
|
Your own account: name, email, password, and appearance (light, dark, or
|
|
follow the system).
|
|
|
|
**Remote access** is where an installation is paired with a portal, remote
|
|
users are admitted, and the link is cut again. That has [its own
|
|
page](portal.md).
|