Serve over HTTPS

Akema serves its web page over plain HTTP by default, on 127.0.0.1:8080. On your own machine that’s all you need: the page never leaves the computer.

HTTPS is optional. It’s there for when teammates reach Akema over the network, or when your policy says every web page must be encrypted. Turning it on changes only how browsers reach Akema. Your sources, traps, workspaces and license stay the same, and you can turn it off again by restarting without the flags.

Choose a certificate

	Local certificate	Your own certificate
Start with	`-tls`	`-tls-cert` and `-tls-key`
Who makes the certificate	Akema, with its own small certificate authority (CA)	Your company CA, or another authority you use
Addresses it covers	`localhost`, loopback and private IP addresses	Whatever names are on your certificate, including host names
Browsers trust it after	You trust Akema’s CA on each machine that opens the page	Nothing, if your machines already trust that authority
Good for	One machine, or a small team reaching Akema by IP address	A team that reaches Akema by a host name such as `akema.lab.example.com`

If you’d rather not run HTTPS in Akema at all, you can keep it on plain HTTP on loopback and put something in front that encrypts the connection: an SSH tunnel to 127.0.0.1:8080, a reverse proxy you already run, or Tailscale Serve. See Behind a proxy or Tailscale.

A local certificate

Add -tls to the command that starts Akema:

akema -addr 127.0.0.1:8080 -tls

Then open https://127.0.0.1:8080. The first time, Akema creates a certificate authority and a server certificate in the tls folder inside its data folder, and prints the CA’s fingerprint and where its certificate is:

local CA sha256 3f9a…
browsers will warn until this CA is trusted: /home/you/.config/akema/tls/ca.crt

Until you trust that CA, your browser warns that the connection isn’t private. That’s expected: Akema made the certificate itself, and your browser hasn’t heard of it.

The certificate covers https://127.0.0.1, https://localhost and https://[::1] on the port you chose.

Trust the certificate

On the machine where you open the browser, run:

akema -tls-trust

This adds Akema’s CA certificate to your own user’s trust store and exits. It doesn’t start Akema, and it can’t be combined with the flags that do, such as -addr or -tls. It never runs sudo and never touches the store for the whole machine. When it’s done it prints the certificate’s SHA-256 and browser-trust: unverified: the command succeeded, but only your browser can confirm it now trusts the certificate. Reload the page to check.

What it runs:

System	Command
macOS	`security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db <ca.crt>`
Windows	`certutil -user -addstore Root <ca.crt>`
Linux	`certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Akema Local CA" -i <ca.crt>`, when `certutil` is installed

Some browsers need more:

Firefox ignores the system’s trust store until you set security.enterprise_roots.enabled to true in about:config. Akema doesn’t change that setting for you.
To trust the CA for every user on the machine, -tls-trust prints the command for the machine-wide store, but doesn’t run it. Run it yourself with administrator rights if you want that. A machine-wide store trusts the CA for every program on the machine, not just your browser.

To trust a copy of the certificate somewhere else, such as one you’ve copied from the Akema server, name the file with -tls-ca:

akema -tls-ca ./akema-ca.crt -tls-trust

What the CA can vouch for

Akema’s CA is limited to local names. It can only issue certificates for localhost and for loopback and private addresses, so trusting it doesn’t let it, or anyone who copies it, impersonate a real website. The limit is written into the CA certificate itself, and browsers enforce it.

The addresses it accepts:

localhost, 127.0.0.0/8 and ::1
Private networks: 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16
Link-local addresses, 169.254.0.0/16 and fe80::/10, except the cloud metadata address 169.254.169.254
Carrier-grade NAT and Tailscale addresses, 100.64.0.0/10
IPv6 unique local addresses, fc00::/7

Host names other than localhost, including your own internal DNS names and *.ts.net, are refused. For a host name, use your own certificate.

To let teammates open Akema from their machines, listen on the network and name the address they’ll use with -tls-host:

akema -addr 0.0.0.0:8080 -tls -tls-host 192.168.1.20

Repeat -tls-host for each address. When Akema listens on a specific address, such as -addr 192.168.1.20:8080, that address is added for you.

Each teammate then trusts the CA on their own machine. Send them ca.crt from the tls folder, and have them run akema -tls-ca ./akema-ca.crt -tls-trust, or import it with the commands above.

An address teammates use that isn’t on the certificate still gets a browser warning, even after they trust the CA. Trusting the CA doesn’t change which names the certificate covers. Add the address with -tls-host and restart.

Renewal and the tls folder

File	What it is
`ca.crt`	The CA certificate. This is the file you trust and share
`ca.key`	The CA’s private key. Keep it on the Akema machine
`leaf.crt`, `leaf.key`	The server certificate Akema presents to browsers
`meta.json`	Which addresses the server certificate covers

The CA is valid for 10 years. The server certificate is valid for 397 days, and Akema replaces it on its own when fewer than 30 days remain, or when you change the addresses with -tls-host. You don’t need to trust anything again: the CA stays the same.

If ca.crt is there but ca.key is missing, Akema refuses to start with -tls rather than make a new CA your browsers don’t know. Restore the key, or start over as described in Turn HTTPS off.

Your own certificate

If your machines already trust a company CA, or you reach Akema by a host name, give Akema a certificate and key in PEM format:

akema -addr 0.0.0.0:8443 \
  -tls-cert /etc/akema/akema.crt \
  -tls-key /etc/akema/akema.key \
  -auth-host akema.lab.example.com

Set both files. One without the other is an error. With -tls-cert and -tls-key, Akema doesn’t create a local CA, even if you also pass -tls.
Renew without a restart. Akema reads the files again for each new connection, so replacing them with a renewed certificate takes effect right away.
Keep the key private. On Linux and macOS, Akema warns at startup if anyone but its own user can read the key file.
Name the host with -auth-host. A host name still needs -auth-host, as on plain HTTP, or the page loads but live updates and changes fail. See Share on your network.

With your own certificate, -tls-host doesn’t change the certificate. It only adds that address to the list Akema prints at startup.

In Docker

The image serves plain HTTP unless you add the flags. Put them after the image name, and name the host’s address with -tls-host: inside the container, Akema can’t see the address teammates use.

docker run -d --name akema -p 8080:8080 \
  -v akema-data:/data -e AKEMA_DATA_DIR=/data \
  "$AKEMA_IMAGE:1.0.0" -addr 0.0.0.0:8080 -tls -tls-host 192.168.1.20

For your own machine only, publish the port to loopback instead, with -p 127.0.0.1:8080:8080, and leave out -tls-host.

To trust the CA, copy its certificate out of the container, then trust that copy on the host:

docker cp akema:/data/tls/ca.crt ./akema-ca.crt
akema -tls-ca ./akema-ca.crt -tls-trust

If you don’t have the akema binary on the host, import akema-ca.crt with the commands in Trust the certificate. Running -tls-trust inside the container can’t reach your browser’s trust store, so there it only prints these instructions.

To use your own certificate in Docker, mount the files into the container and point -tls-cert and -tls-key at them.

Require HTTPS

To make sure Akema never starts on plain HTTP by mistake, for example in a service file, add -require-tls:

akema -addr 0.0.0.0:8080 -tls -tls-host 192.168.1.20 -require-tls

Akema then refuses to start unless -tls, or both -tls-cert and -tls-key, are set. It doesn’t create a certificate on its own.

Sign-in works the same over HTTPS. A few things change:

Sign in again after you switch. Over HTTPS, Akema’s cookies get new names and are sent only over encrypted connections, so a sign-in from plain HTTP doesn’t carry over. The same happens when you switch back.
localhost and 127.0.0.1 are still different sites to your browser. Use the same address each time.
Scripts use the https:// address. With a local certificate, tell curl about the CA:

curl -sS --cacert ./akema-ca.crt -c akema.cookies -H 'Accept: application/json' \
  -d 'passphrase=your passphrase' https://127.0.0.1:8080/api/auth/login

Behind a proxy or Tailscale

If you’d rather encrypt in front of Akema, keep Akema on plain HTTP on loopback and point your proxy at http://127.0.0.1:8080. Pass -auth-host with the name people use.

Akema decides whether a connection is encrypted from its own connection, not from a proxy’s X-Forwarded-Proto header. Behind a proxy, it treats the browser’s connection as plain HTTP, which is what it is from Akema’s side.

For Tailscale:

Tailscale Serve to http://127.0.0.1:8080, with -auth-host and your *.ts.net name, is the simplest. Tailscale handles the certificate.
Or get a certificate with tailscale cert and pass its files with -tls-cert and -tls-key.

Akema’s local CA won’t issue a certificate for a *.ts.net name.

Turn HTTPS off

Start Akema again without -tls, -tls-cert and -tls-key (and without -require-tls). It serves plain HTTP, and everyone signs in again.

To remove Akema’s CA from your trust store:

akema -tls-untrust

It removes only what -tls-trust added to your user’s store, and prints the command for the machine-wide store if you added it there. Run it before you delete or move the tls folder: it needs ca.crt to know which certificate to remove. If you’ve already moved it, point -tls-ca at a saved copy.

To start over with a new CA, untrust the old one, then move the tls folder aside. The next start with -tls creates a new CA, which everyone trusts again.

Flags

Flag	What it does
`-tls`	Serve HTTPS on `-addr` with a local certificate. Off unless you set it
`-tls-host NAME`	With `-tls`, another address the certificate covers: `localhost` or a loopback or private IP. Repeat for each. With your own certificate, an address to print at startup
`-tls-cert PATH`	Your certificate, in PEM format. Use with `-tls-key`
`-tls-key PATH`	The private key for `-tls-cert`
`-require-tls`	Refuse to start unless HTTPS is set up
`-tls-trust`	Trust Akema’s CA in your user’s trust store, and exit
`-tls-untrust`	Remove it from your user’s trust store, and exit
`-tls-ca PATH`	The CA certificate for `-tls-trust` and `-tls-untrust`. Defaults to `tls/ca.crt` in the data folder

Troubleshooting

What you see	Why	What to do
The browser warns that the connection isn’t private	The browser doesn’t trust Akema’s CA yet	Trust the certificate on that machine. In Firefox, also set `security.enterprise_roots.enabled`
The warning stays after trusting the CA	The address isn’t on the certificate	Add it with `-tls-host` and restart
`… is not a local name; Akema will not ACME it`	`-tls-host` named a host name, which the local CA can’t cover	Use an IP address, or your own certificate
`… is a Tailscale name`	`-tls-host` named a `*.ts.net` address	Use Tailscale Serve, or `tailscale cert` files with `-tls-cert` and `-tls-key`
`require-tls: pass -tls or -tls-cert and -tls-key`	Akema was started with `-require-tls` and no HTTPS flags	Add `-tls`, or both certificate flags
`-tls-cert and -tls-key must be set together`	Only one of the two was set	Pass both
`ca.crt present but ca.key missing`	The CA’s key was removed or not copied	Restore `ca.key`, or start over as in Turn HTTPS off
Signed out after turning HTTPS on or off	Cookies over HTTPS have different names	Sign in again
Live updates and changes fail, but the page loads	A host name isn’t listed with `-auth-host`	Add `-auth-host NAME` and restart