stroblmeandClaude Opus 5
d01a8dad37
Follows the portal: the noun is "instance" everywhere the app says it — UI strings, CLI output, error details, docs and comments. The wire keys (`instance_id`, `instance_token`) and the hub route this calls move with it. An existing cloud.json is adopted rather than refused: without the key alias the dataclass fails to parse, which the caller swallows and reads as "never enrolled" instead of "reconnect". `instance_key` on a node type becomes `target_key`. It means the outside thing a node points at, which is a different sense of the word, and keeping both would put two meanings of "instance" in one codebase. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015YrQnKV3bnQd4K342y8tKj
118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
# Accounts and the portal
|
|
|
|
Fluksio is self-hosted by default. An instance runs offline, keeps its data
|
|
on its own disk, and never contacts anything unless you tell it to.
|
|
|
|
The **portal** is optional, and it exists to solve two specific problems:
|
|
|
|
1. **Your machine has no inbound route.** A homelab behind CGNAT, a cluster
|
|
node with no open ports, a laptop. Opening one is work, and often not
|
|
allowed.
|
|
2. **You want a browser on it anyway.** A `pip install fluksio` instance
|
|
has no web server for the dashboard at all.
|
|
|
|
An enrolled instance dials *out* to the portal and holds one websocket
|
|
open. The portal serves the dashboard from its own side, and only the API calls
|
|
travel down the tunnel — so the interface loads at portal speed and your
|
|
machine stays unreachable from the internet.
|
|
|
|
## Enrolling
|
|
|
|
Two halves, deliberately: whoever performs the second step decides what the
|
|
instance's owner gets.
|
|
|
|
**On the portal** (`hub.${DOMAIN}`, or [fluksio.com](https://fluksio.com) for
|
|
the hosted one): **Instances → Add instance**, give it a name, and copy
|
|
the code.
|
|
|
|
**On the instance**, either from the dashboard:
|
|
|
|
> **Settings → Remote access**, enter the portal URL and the code, press
|
|
> **Connect**.
|
|
|
|
or from the command line, which is the path for an instance with no web
|
|
interface of its own:
|
|
|
|
```sh
|
|
fluksio enroll ABCD-1234 --portal https://hub.fluksio.com
|
|
```
|
|
|
|
The code is single-use and expires in fifteen minutes.
|
|
|
|
A portal session then arrives as *that local account* — the settings screen
|
|
states this plainly, because it is the whole security model in one sentence.
|
|
Use `--as someone@example.com` to enrol as a specific local account when the
|
|
instance has several superusers.
|
|
|
|
Once enrolled, the instance appears under **Instances** with its
|
|
status, when it was last seen and its version. **Open** takes you to its
|
|
dashboard at `${DOMAIN}/i/{instance-id}`.
|
|
|
|
## What the portal can and cannot do
|
|
|
|
The portal holds one credential for your instance and proxies requests down
|
|
the tunnel. What those requests may do is decided **on the instance**, by
|
|
the same checks a local session passes.
|
|
|
|
The trust anchor is a signing keypair on the portal. Every instance pins
|
|
its public half at enrolment and rejects anything else — which is what stops a
|
|
hijacked DNS entry or a mis-issued certificate from impersonating the portal.
|
|
|
|
## Letting someone else in
|
|
|
|
Anyone else on the portal reaches your instance only if a superuser there
|
|
admits them, and they arrive as a local user of their own rather than as you.
|
|
|
|
1. **They**: **Instances → Join an instance**, and copy the code. It is
|
|
bound to their portal account and expires in fifteen minutes.
|
|
2. **You**, on the instance: **Settings → Remote access → Add remote
|
|
user**, and enter the code.
|
|
3. They now see the instance under **Instances**, marked *Shared by*,
|
|
with **Open** and nothing else. Renaming, re-keying and removing stay with
|
|
you.
|
|
|
|
The instance redeems that code against the portal using its own credential.
|
|
A portal session cannot do this — which is what stops somebody you let in from
|
|
letting others in.
|
|
|
|
On the instance they appear under **Admin → Users**, badged *Portal*, never
|
|
a superuser and with no password.
|
|
|
|
## Cutting it off
|
|
|
|
| From | Action | Effect |
|
|
|---|---|---|
|
|
| The portal | **New code** | rotates the credential and drops the current link |
|
|
| The portal | **Remove** | deletes the registration and cuts the connection |
|
|
| The instance | **Disconnect** | unilateral and immediate — the portal's tokens stop verifying here whatever the portal still has on file |
|
|
| The instance | delete a user under **Admin → Users** | that one person, immediately, independent of the portal |
|
|
|
|
**New code** also cuts every credential the portal minted for this instance,
|
|
including [wall panels paired through it](dashboards.md#a-screen-somewhere-you-cannot-reach).
|
|
|
|
The instance's own **Disconnect** is the one to reach for if you are ever
|
|
unsure: it does not need the portal's cooperation.
|
|
|
|
## Running your own portal
|
|
|
|
The portal is the `index` stack's `hub` service — accounts, the registry of
|
|
connected instances, and the websocket each one dials in on. Two things
|
|
about it are load-bearing:
|
|
|
|
- **It runs a single process.** It keeps its attached instances in the
|
|
memory of the process holding their sockets, so a second worker would answer
|
|
for links it does not hold. Scaling out needs a routing layer first.
|
|
- **Back up the signing keypair with the database.** Replacing it forces every
|
|
instance to be enrolled again.
|
|
|
|
Websocket upgrades must be enabled on the `hub` hostname in whatever proxy
|
|
fronts it. Without them every instance sits in a reconnect loop and the
|
|
portal shows them all offline.
|
|
|
|
## See also
|
|
|
|
- [The `fluksio` command](../code/cli.md) — `fluksio enroll`, and what it writes
|
|
- [Dashboards and panels](dashboards.md) — pairing a wall screen through the portal
|
|
- [Getting started: data science](../getting-started/data-science.md) — the
|
|
shortest path from a pip install to a browser
|