stroblme
e9c3d0944d
Not ?token= in the tunnel URL, which access logs keep. The hub has to be upgraded first; websockets>=14 for additional_headers on the asyncio client.
143 lines
6.2 KiB
Markdown
143 lines
6.2 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: 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 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 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.
|
|
|
|
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}`.
|
|
|
|
**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.
|
|
|
|
## 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 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.
|
|
|
|
### Share a link
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## 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
|