RUN IT IN PRODUCTION
Running an Enclave on a server¶
An Enclave on a server is the same Enclave you ran on your laptop, handed to a service manager so it comes back after a crash and after a reboot.
This page is for whoever owns the machine your agents will run on.
The difference that matters is not the software, it is the answer to one question: is it running? On a laptop you can see the terminal. On a server the only honest answer comes from the service manager and from EKKA, and this page sets up both so they can disagree out loud.
Five steps, about five minutes.
Ask whether an agent can work on this machine, and what is missing:
Use a service manager, not a background shell
nohup, &, screen and tmux all look like they solve this. Each one
survives your ssh session and nothing else. A reboot, an out-of-memory kill,
or a crash at 3am ends the Enclave silently, and the only sign is that your
plans stop running.
Use your operating system's service manager instead. On Linux that is
systemd, and ekka enclave install-service sets it up in one command.
To watch it run for five minutes before committing to a service,
tmux new -d -s ekka 'ekka enclave start' is fine. Do not leave a server
that way: run tmux kill-session -t ekka when you are done, then come back
and do step 4.
What you need¶
- A Linux server you can
sudoon. - The Enclave id. Run
ekka enclave listfrom your own machine, or ask whoever runs your organization. It looks like2055d4a5-4e55-4292-9f8e-64166f14871d. - About five minutes.
1 · Install the binary¶
curl -fsSL https://get.ekka.ai/install.sh | sudo sh -s -- --install-dir /usr/local/bin
ekka --version
One binary, in one place
--install-dir matters on a server. Without it the installer writes to
~/.local/bin when it cannot write /usr/local/bin, and you end up with
two ekka binaries: yours, and the one the service runs. They start
identical and drift apart at the first upgrade, and the symptom is "I
upgraded and nothing changed".
/usr/local/bin is the right home here because the Enclave runs as its own
account, which cannot read your home directory.
ekka --version prints the file it ran from, so you can always check which
one answered:
2 · Make a user for it¶
The Enclave does not need to be root, so do not run it as root. Give it its own user and its own folder.
sudo useradd --system --no-create-home --shell /usr/sbin/nologin --home-dir /var/lib/ekka ekka
sudo install -d -o ekka -g ekka -m 0700 /var/lib/ekka
/var/lib/ekka is that account's home, so its Enclave lives in
/var/lib/ekka/.ekka: the same ~/.ekka every EKKA user has. The vault, the
receipts and the config are all in there.
Why --home-dir earns its place
It is the reason none of the commands below need EKKA_HOME=… in front of
them. sudo -u ekka gives that account its own HOME, and ekka finds its
state the same way it does for you. The server stops being a special case.
The home lives outside /home and /root
The service file we ship hides those two folders from the Enclave, as one
of its safety settings, so the home has to be a path outside them.
/var/lib/ekka is the one the unit file already names.
3 · Sign in and claim the machine, once¶
Wait for this line:
Then press Ctrl-C to stop it.
That felt like an ordinary start, but it did the important part: it claimed
this machine for that Enclave, created the vault, and wrote a complete
config file at /var/lib/ekka/enclave.env. You only ever do this once. From
here on, ekka enclave start needs no id and no arguments.
No keychain questions on a server
On a Mac the Enclave keeps its vault key in the OS keychain, which asks
you to approve access. A Linux server has no keychain, so the key is
sealed into a protected file next to the vault instead. Nothing pops up
and there is nothing to approve. You do not need to pass --custody.
4 · Hand it to systemd¶
That writes /etc/systemd/system/ekka.service, then enables and starts it. The
unit is generated from this machine: the Enclave home you enrolled in step
3, the account that owns it, and the path of the binary you installed in step 1.
Nothing to substitute.
The service runs the Enclave as the account that owns the Enclave home, with no extra privileges, restricted to that directory, and restarts it if it stops.
sudo ekka enclave install-service --dry-run # print the unit, write nothing
sudo ekka enclave install-service --no-start # write the unit, start it later
If your Enclave lives under a home directory
systemd's ProtectHome=true makes /home and /root invisible to a
service, so a unit with it turned on starts and then finds no enrolled
machine at all.
install-service notices, turns it off for you, tells you on screen, and
writes the reason into the unit. Moving the Enclave to /var/lib/ekka (step
2) is the stronger posture; re-run the command afterwards and it goes back
on.
5 · Check it two ways¶
One command asks the operating system whether the process is up. The other asks the Enclave whether it is actually working.
Then, from anywhere signed in to your organization:
Your server should show as online. That is the answer that counts, because it is govern saying it can reach the machine and give it work.
BUILD is which version that machine is running. ekka enclave status only
ever answers about the machine you are typing on, so for a server this row is
where you read it. A dash means the Enclave has not reported one, which means it
has never connected. On a machine that is offline, the build shown is the last
one govern saw, which tells you what it was running when it stopped.
Where are the logs?¶
systemd captures everything the Enclave prints, so you never need to have been watching.
sudo journalctl -u ekka -f # follow, like tail -f
sudo journalctl -u ekka -S -1h # the last hour
sudo journalctl -u ekka -n 50 # the last 50 lines
Day to day¶
| What you want | Command |
|---|---|
| Restart it, after upgrading the binary | sudo systemctl restart ekka |
| Stop it, keeping the enrollment | sudo systemctl stop ekka |
| Stop it and keep it off after a reboot | sudo systemctl disable --now ekka |
| Stop giving it work, but leave it running | ekka enclave pause <id> |
| Give it work again | ekka enclave resume <id> |
The last two are worth understanding, because they answer different
questions. Use systemctl stop when you are working on the machine.
Use ekka enclave pause when you are working on the workload and want
the process left alone.
How do I upgrade it?¶
curl -fsSL https://get.ekka.ai/install.sh | sudo sh -s -- --install-dir /usr/local/bin
sudo systemctl restart ekka
Your enrollment, vault and receipts are all in /var/lib/ekka and are not
touched by replacing the binary.
Upgrade the same path you installed to. If a different ekka is found earlier
on your PATH, the installer stops and tells you, rather than installing a
binary you would never run.
Two commands answer "did that work", and they answer different questions:
ekka --version # which file your shell runs, and which build it is
ekka doctor # every ekka on this machine, and whether they differ
The restart is not optional. The running process keeps serving the binary it
started with, so until you restart it, ekka enclave list reports the old build
for this machine.
What if it will not start?¶
The Enclave never fails quietly. Every refusal starts with FATAL: and
names what is wrong, and systemd kept all of it:
One command answers most of them, by printing every setting the Enclave is actually using and where each value came from:
Two common ones:
FATAL: this Enclave has no vault. Step 3 did not finish. Run theekka enclave start <enclave-id>line again and wait forauthenticated; entering run loopbefore stopping it.- The unit starts, then stops, then starts again. Read the journal. The service is set to keep retrying, so a config problem shows up as a loop rather than a single failure.
Can I run it in a container?¶
If the machine's disk is not yours to write to, skip step 3. Supply every
setting from outside instead, through environment variables. The release
tarball ships a template at share/templates/ekka.env.template listing
every required key, and share/docs/INSTALL.md covers that path in full.
You still need an Enclave that was enrolled somewhere: the Enclave signs with a private key that lives in its vault, and there is no environment variable for a private key.