Sign-in and sharing

One running Akema is one shared bench. Everyone who opens it sees the same sources, traps and Explore canvas, and a change one person makes, such as stopping a source or applying a setting, changes it for everyone.

Akema listens on 127.0.0.1:8080 by default, so only your own machine can reach it, and it doesn’t ask anyone to sign in. When you share it with your team, two things keep the bench in order:

• One editor at a time. Only one browser window can change the bench. The others can watch. This is always on.
• Sign-in, which you turn on yourself. Use one shared passphrase, or give each person a name and PIN, with an editor or viewer role.

One editor at a time

The first browser to open Akema becomes the editor. Next to Clients, at the top of the page, it shows Editing.

Any other browser that opens the same Akema shows Viewing — another window is editing and a Take over button. It still sees everything live, but Akema refuses its changes, such as starting or stopping a source, adding a trap, clearing the table, switching workspace or choosing Apply in Settings. On the Explore canvas it shows Another window is editing, and you can’t add, move or remove charts.

To edit from a viewing window, choose Take over. That window becomes the editor right away, and the previous editor switches to Viewing. Nothing else changes: sources keep running, and the workspace stays as it was.

Tabs in the same browser count as one window, so you can open Akema in several tabs and edit from any of them.

The editor keeps the role while its window is open. If it’s closed, or the computer sleeps, the role is free after 90 seconds, and the next browser to open or reload Akema becomes the editor. Take over works at any time.

This is not a login: without sign-in, anyone who can reach Akema can choose Take over. To decide who may edit, turn on sign-in.

Turn on sign-in

You turn on sign-in from the command line, on the machine that runs Akema. There are two ways:

	Shared passphrase	Named people
Signs in with	One passphrase everyone knows	Their own name and a PIN of 6 to 8 digits
Roles	Everyone is an editor	Each person is an editor or a viewer
Good for	A few people who all need to make changes	A team, where some people only need to look

Both are stored in operator-auth.json in the data folder. Only hashes are stored, never the passphrase or PINs. Akema reads the file when it starts, so restart Akema after any change to sign-in. A running Akema keeps its old settings until then.

Akema reads the passphrase or PIN from the terminal without showing it, or from a pipe. It never takes one as a command-line option or environment variable, where other users could see it.

A shared passphrase

akema -auth-set

Type a passphrase of at least 10 characters. Then restart Akema. Everyone who opens it now sees Sign in and enters the passphrase.

Named people with a PIN

Add each person with a name, a role and a PIN:

akema -auth-user-set -auth-user-name ada -auth-user-role editor
akema -auth-user-set -auth-user-name grace -auth-user-role viewer

Each command asks for that person’s PIN: 6 to 8 digits, and leading zeros count. Then restart Akema. The sign-in page now asks for Name and PIN.

• Names are 1 to 32 characters: lowercase letters, digits and hyphens, starting with a letter.
• The first person is always an editor, whatever role you give, so someone can always edit.
• Later people are viewers unless you add -auth-user-role editor.
• Up to 32 people.
• Adding the first person replaces a shared passphrase, if you had one.

To remove someone:

akema -auth-user-remove grace

Akema won’t remove the last editor. To change someone’s role or PIN, remove them and add them again.

Editors and viewers

	Editor	Viewer
Watch live messages, select rows and use the Record pane	Yes	Yes
Filter the table, follow traps and export trap counts	Yes	Yes
Load Explore, filter charts and run SQL	Yes	Yes
Add, change or delete traps, and clear counters	Yes	No
Add, start, stop or remove sources, and load files	Yes	No
Add, move or remove charts on the Explore canvas	Yes	No
Create, rename, switch or delete workspaces	Yes	No
Apply settings, change redaction, or add a license	Yes	No

A viewer sees View-only next to Clients, and the buttons for changes are hidden. A viewer never becomes the editor, so a viewer’s browser can’t take the role away from anyone.

Editors still share the one-editor rule: if two editors have Akema open, one edits and the other sees Viewing — another window is editing until they choose Take over. With a shared passphrase, everyone is an editor.

Sign in and out

To sign out, open the Display menu and choose Sign out, under Session.

A sign-in lasts until you sign out, until you haven’t used Akema for 12 hours, or until Akema restarts. A laptop that slept overnight shows the sign-in page again.

localhost and 127.0.0.1 count as different sites to your browser, so signing in at one doesn’t sign you in at the other. Use the same address each time. Switching between plain HTTP and HTTPS also means signing in again.

Require sign-in

Add -require-auth to the command that starts Akema, for example in your service file:

akema -addr 127.0.0.1:8080 -require-auth

Akema then refuses to start if sign-in hasn’t been set up, or if operator-auth.json is damaged, instead of starting without a sign-in. It doesn’t create a passphrase for you: run -auth-set or -auth-user-set first.

Turn sign-in off

akema -auth-disable

This deletes operator-auth.json, without asking for the passphrase or a PIN, so it’s also the way back in if you’ve forgotten them. Restart Akema, and it opens without a sign-in. Your workspaces, Kafka settings and license aren’t touched. Remove -require-auth from your start command first, or Akema won’t start.

To switch from named people back to one passphrase, run -auth-disable and then -auth-set.

In Docker

Run the same commands in a container that uses Akema’s volume. -it lets Akema ask for the passphrase or PIN without showing it:

docker run --rm -it -v akema-data:/data -e AKEMA_DATA_DIR=/data \
  "$AKEMA_IMAGE:1.0.0" -auth-user-set -auth-user-name ada -auth-user-role editor

Then restart your Akema container. To require sign-in, add the flags after the image name. To serve the page over HTTPS as well, add the flags in Serve over HTTPS:

docker run --rm -p 127.0.0.1:8080:8080 -v akema-data:/data -e AKEMA_DATA_DIR=/data \
  "$AKEMA_IMAGE:1.0.0" -addr 0.0.0.0:8080 -require-auth

Share on your network

To let teammates reach Akema from their own machines, listen on the network as well as your own machine, for example -addr 0.0.0.0:8080, or publish the Docker port with -p 8080:8080. When Akema listens anywhere but loopback, it prints a warning when it starts. If sign-in is off, the banner on the Settings tab also says that anyone who can reach the port can use your saved Kafka credentials.

Before you do, know what sign-in does and doesn’t protect:

• Akema serves plain HTTP unless you turn on HTTPS. Over plain HTTP, the passphrase, PINs and messages travel unencrypted. HTTPS is optional: see Serve over HTTPS. Otherwise share Akema only on a network you trust, or have teammates reach it through an SSH tunnel to 127.0.0.1:8080.
• Sign-in protects the browser page. It doesn’t encrypt saved Kafka credentials. Anyone who can read the data folder on the Akema machine can read them, and can delete operator-auth.json.
• Only Akema’s own pages can make changes. Another website, or a page on another port of the same machine, can’t change your Akema even while you’re signed in.

If teammates use a host name, such as akema.lab.example.com, rather than an IP address, start Akema with that name:

akema -addr 0.0.0.0:8080 -auth-host akema.lab.example.com

Without it, the page loads, but live updates and every change fail. Repeat -auth-host for each name. localhost and IP addresses don’t need it. To encrypt the connection for a host name, use your own certificate: see Serve over HTTPS.

For separate benches, where people don’t see each other’s sources and traps, run one Akema for each, on its own port with its own -data-dir. Each running Akema needs its own license.

Scripts

A script that calls Akema’s API signs in once and keeps the cookie. With a shared passphrase:

curl -sS -c akema.cookies -H 'Accept: application/json' \
  -d 'passphrase=your passphrase' http://127.0.0.1:8080/api/auth/login
curl -sS -b akema.cookies http://127.0.0.1:8080/api/status

With named people, send the name and PIN instead:

curl -sS -c akema.cookies -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '{"name":"ada","pin":"012345"}' \
  http://127.0.0.1:8080/api/auth/login

Over HTTPS, use the https:// address, and with Akema’s local certificate add --cacert with its CA certificate. Send the passphrase or PIN in the request body, never in the URL. Add the sign-in step to your scripts before you turn sign-in on, or they’ll stop working. A script that changes the bench also needs the editor role: while a browser is editing, its changes are refused.

What sign-in doesn’t do

• No single sign-on. There’s no SSO, LDAP or OAuth. People sign in with Akema’s own passphrase or PIN.
• No per-workspace permissions. A role applies to the whole Akema, every workspace included.
• No audit log of who changed what.
• People are managed from the command line, on the Akema machine, and changes need a restart.