Fluksio/app
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
stroblme
2026-10-13 10:02:20 +02:00
parent a93f865e91
commit 80e595c02e
24 changed files with 2210 additions and 4310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/interface/portal.md
+59 -115
View File
@@ -1,142 +1,86 @@
# 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 optional portal lets you open an instance from [fluksio.com](https://fluksio.com),
including a pip installation with no local dashboard. The instance connects
outward over a WebSocket, so you do not need to open an inbound port.
The **portal** is optional, and it exists to solve two specific problems:
Flows still run on your instance. The portal serves the interface and carries
API requests, responses and live updates through the connection.
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.
## Connect an instance
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.
1. Sign up or sign in at **fluksio.com**.
2. Open **Instances → Add instance** and copy the code.
3. On the machine running Fluksio, open another terminal in the same directory
as `fluksio serve` and run:
## Enrolling
```sh
fluksio enroll <code>
```
Two halves: whoever performs the second step decides what the instance's owner
gets.
The CLI uses `https://hub.fluksio.com` by default. If you started the engine
with `--data-dir` or `--global`, use the same option when enrolling. A running
engine picks up the connection automatically; otherwise start it with
`fluksio serve`.
**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.
From a local dashboard, you can instead use **Settings → Remote access**:
leave the default portal URL, paste the code, and press **Connect**.
Enrollment requires a superuser account.
**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:
The portal owner's sessions use the local account that enrolled the instance.
Check **Acting as** under Remote access. With several local superusers, the
CLI can choose one explicitly:
```sh
fluksio enroll ABCD-1234 --portal https://hub.fluksio.com
fluksio enroll <code> --as someone@example.com
```
The code is single-use and expires in fifteen minutes. A fresh code on an
instance that is already paired replaces the pairing, so moving an instance to
another portal is one command rather than a disconnect and a reconnect.
A new valid code replaces an existing connection. An expired or invalid code
leaves the current connection intact. Once connected, open the instance from
the portal's **Instances** list.
A portal session then arrives as *that local account*, which the settings screen
states plainly. Use `--as someone@example.com` to enrol as a specific local
account when the instance has several superusers.
## Let someone else in
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}`.
Each person gets an ordinary local account, with no superuser rights. You can
admit them in either of these ways:
**Upgrade a self-hosted portal before its instances.** An instance dials the
tunnel with its credential in an `Authorization` header, where it stays out of
access logs, and a portal from before that reads it only from the URL. The
portal still takes the old `?token=` for one release, so older instances keep
attaching meanwhile.
- Share an invitation link from the portal's **Instances** list.
- Ask them for a code from **Instances → Join an instance**. Enter it on your
local instance under **Settings → Remote access → Add remote user**.
## What the portal can and cannot do
Their account appears under **Admin → Users** with a *Portal* badge. They
sign in through the portal rather than with a local password. Invitations are
time-limited; generate a fresh one if it expires.
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.
## Manage or end remote access
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.
**Settings → Remote access** shows the connection status and the latest
connection error. The instance needs outbound access to the portal, and any
proxy on that route must support WebSockets.
## Letting someone else in
- To remove a person's access, remove them from the portal's sharing dialog
or edit their account under **Admin → Users** and clear **Is active?**.
- To end all portal access from the instance, press **Disconnect**. This stops
the connection and invalidates portal credentials locally, without requiring
the portal to be online.
- To replace the pairing, use **Connect with a new code**. Remote users and
panels may need to pair again.
Anyone else on the portal reaches your instance only if you let them, and they
arrive as a local user of their own rather than as you. There are two ways,
and the difference is who starts.
Local sign-in and flows continue after disconnecting. Portal requests follow
the instance's normal account permissions, and the instance verifies portal
tokens against the public signing key pinned during enrollment.
### Share a link
## Custom portals
On the portal, the share icon on your instance's row gives a QR code and a URL.
Whoever opens it, signed in to Fluksio on that device, joins. It works once and
expires in fifteen minutes; **New link** replaces it, which is also how a link
you would rather not have sent is cancelled.
The CLI accepts another compatible portal with `--portal https://<portal-host>`;
the dashboard has the same URL field. HTTPS is required except for a portal on
loopback.
Nothing has to be entered on the instance. It learns of the new member when
they first arrive and asks the portal who they are, then gives them their local
account.
### Take a code
For a machine whose owner would rather admit people at the machine itself.
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.
Either way 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 the 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 | share dialog → **Remove** | that member stops reaching it from the portal; their user on the machine stays until it is deleted there |
| The portal | **Leave**, on a row shared with you | gives up your own access to somebody else's instance |
| 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.
This public repository contains the instance and its connector. The portal
service is not included, so the Docker stack does not start one.
## 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
- [The fluksio command](../code/cli.md): data directories and enrollment options.
- [Dashboards and panels](dashboards.md): pair a wall screen through the portal.
- [Getting started](../getting-started/index.md): install and open your first instance.