Installing piqueld

This page installs the piqueld daemon and the piquelctl CLI on a Linux host, and sets up the address you open the dashboard at.

Before you start

You need:

An x86_64 Linux host. NixOS is the supported way to install piqueld. On other distributions, you install it with Cargo.
Docker Engine on that host, dedicated to piqueld. piqueld runs your applications as Docker Swarm services and manages the engine’s services, networks and volumes. If the engine isn’t part of a Swarm yet, piqueld makes it a single-node Swarm when it starts.

Anyone who controls the host also controls piqueld: they can read its database and drive its Docker engine. piqueld calls them the host operator and lets them use piquelctl on the host without signing in.

Install on NixOS

Add piqueld to your flake’s inputs:

inputs.piqueld.url = "github:sourceorigin-dev/piqueld";

Import its module and enable the service:
```
{ inputs, ... }:
{
  imports = [ inputs.piqueld.nixosModules.default ];
  services.piqueld.enable = true;
  # Lets alice use piquelctl on this host.
  users.users.alice.extraGroups = [ "piqueld" ];
}
```
The module enables Docker, creates a piqueld system user, runs the daemon as the piqueld systemd service, and installs piquelctl. It doesn’t open any firewall port.
Choose how to reach the dashboard, and add the matching settings.
Rebuild the system:
```
sudo nixos-rebuild switch
```
Log out and back in, so that your new group membership applies.

The NixOS module reference describes every option.

Choose how to reach the dashboard

At first, piqueld only listens on a Unix socket on the host, so the dashboard isn’t reachable from a browser. Pick one of the addresses below before you create your account: the passkey you sign in with only works at the address it was created on.

piqueld’s own tailnet node

If you use Tailscale, this is the simplest option. piqueld joins your tailnet as its own device and serves the dashboard over HTTPS at https://piqueld.<tailnet>.ts.net, with no proxy or certificate to manage.

In the Tailscale admin console, enable MagicDNS and HTTPS certificates for your tailnet, then create an auth key.
Save the auth key in a file only root can read, such as an agenix or sops-nix secret.

Add to your configuration:

services.piqueld.settings.tailscale = {
  enabled = true;
  hostname = "piqueld";
  auth_key_file = "/run/secrets/piqueld-ts-auth-key";
};

The key is only used the first time the node logs in. See the tailnet node for the other settings.

Localhost

piqueld serves the dashboard on http://localhost:7845 of the host:

services.piqueld.settings.server.listen_mode = "localhost";

Browsers allow passkeys on localhost without HTTPS. To open the dashboard from another machine, forward the port over SSH, then open http://localhost:7845 there:

ssh -L 7845:localhost:7845 <host>

Always use localhost, not 127.0.0.1: it is a different address to the browser, and your passkey won’t work there.

Your own reverse proxy

Run an HTTPS reverse proxy on the host, forwarding to piqueld’s localhost listener, and tell piqueld its address:

services.piqueld.settings = {
  server.listen_mode = "localhost";
  # The proxy forwards requests for this hostname.
  server.allowed_hosts = [ "piqueld.example.com" ];
  auth.public_url = "https://piqueld.example.com";
};

Keep the proxy reachable only from networks you trust, such as your LAN or tailnet. Never expose piqueld to the internet, even through a proxy.

Other Linux distributions

piqueld has no packages for other distributions yet, and the NixOS module is the only tested setup. To run it elsewhere, install it from crates.io with Cargo, then set it up the way the NixOS module does:

Install Rust with rustup, then the musl target, a C compiler, pkg-config and OpenSSL’s development files. On Debian and Ubuntu:
```
rustup target add x86_64-unknown-linux-musl
sudo apt install build-essential pkg-config libssl-dev
```
The daemon embeds a small static program built for the musl target, which runs the HTTP health checks inside your containers.
Build the daemon and piquelctl, and copy them to /usr/local/bin:
```
cargo install --locked piqueld piquelctl
sudo install ~/.cargo/bin/piqueld ~/.cargo/bin/piquelctl /usr/local/bin/
```
The build takes several minutes. --locked builds with the dependency versions the release was tested with. The daemon includes the dashboard. To run a version that isn’t released yet, build it from a checkout with just build-embedded instead, as the developer guide describes, and copy target/release/piqueld and target/release/piquelctl.

Create a piqueld system user and group, and add the user to the docker group:

sudo useradd --system --user-group --groups docker \
  --home-dir /var/lib/piqueld --no-create-home piqueld

Write the daemon’s configuration to /etc/piqueld/config.toml, with the settings from the previous section. Each services.piqueld.settings option is the same setting in the file: settings.server.listen_mode = "localhost" becomes
```
[server]
listen_mode = "localhost"
```
The configuration reference lists every setting.

Save this unit as /etc/systemd/system/piqueld.service:

[Unit]
Description=piqueld application control plane
After=docker.service
Wants=docker.service

[Service]
ExecStart=/usr/local/bin/piqueld --config /etc/piqueld/config.toml
User=piqueld
Group=piqueld
SupplementaryGroups=docker
StateDirectory=piqueld
StateDirectoryMode=0700
RuntimeDirectory=piqueld
RuntimeDirectoryMode=0750
UMask=0077
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemd creates the data directory, /var/lib/piqueld, and the runtime directory holding the API socket, /run/piqueld. The daemon also needs git, ssh and docker on its PATH, which includes /usr/bin.

If piqueld joins your tailnet as its own node, it also needs tailscale and tailscaled on its PATH. Store the auth key in a file only root can read, such as /etc/piqueld/ts-auth-key, and pass it to the service by adding to the unit’s [Service] section:
```
LoadCredential=ts-auth-key:/etc/piqueld/ts-auth-key
```
Then refer to it by that name in config.toml:
```
[tailscale]
enabled = true
auth_key_file = "ts-auth-key"
```

Start the daemon, and have it start at boot:

sudo systemctl daemon-reload
sudo systemctl enable --now piqueld

Add the users who should run piquelctl on the host to the piqueld group.

Check that it works

sudo piquelctl status

It prints the daemon’s version and how piquelctl reached it:

daemon running (version 0.1.0, API v1, instance instance-01a16b10b8307c61b5ac3d27d4bf7937)
Transport: Unix socket /run/piqueld/piqueld.sock

Run as root, piquelctl acts as the host operator, so it works before any account exists. Then check the installation:

sudo piquelctl doctor

It checks what the daemon can verify about its own setup, such as Docker, its public URL and its secret key, and gives a next step for each check that needs action. Once you’ve signed in, System status on the dashboard’s Overview also shows whether Docker and its Swarm are ready, and the Daemon status page runs the same checks.

Next, create your account.

Troubleshooting

piquelctl can’t connect to the socket. Check that the service runs with systemctl status piqueld, and read its logs with journalctl -u piqueld. Without sudo, you need to be in the piqueld group, and logged in again since you were added.
Docker isn’t ready. piqueld keeps serving while Docker is down, and starts deploying once it’s back. System status, on the dashboard’s Overview, shows whether it reaches Docker and whether the engine is a Swarm manager.

Keyboard shortcuts

piqueld