Install the control plane
This guide takes you from an empty server to a signed-in dashboard.
1. Choose your options
You make two choices before you start: how the dashboard gets its HTTPS certificate, and whether users sign in with single sign-on.
| CERTIFICATE | CHOOSE IT WHEN | YOU NEED |
|---|---|---|
| acme Recommended | The server has a DNS name, for example nile.example.com. | A DNS A record pointing at the server. Ports 80 and 443 reachable from the internet. |
| files | You already have a certificate, for example from your company CA. | The certificate (PEM, leaf first) and its private key. |
| internal | Testing on a private machine only. | Nothing. Browsers show a certificate warning. |
| acme-ip | The server has only a public IPv4 address. | Ports 80 and 443 reachable. Not verified yet; avoid it for now. |
With acme, the certificate comes from Let’s Encrypt and renews automatically.
Sign-in. By default each user signs in with an email and password. If you add bundled single sign-on, PerkBridge installs its own Keycloak identity provider, and password accounts keep working too. Single sign-on needs a second host name, for example id.example.com, pointing at the same server. It can never be the dashboard’s own name.
2. Prepare the server
- Ubuntu 24.04 LTS, 64-bit (amd64), with root access.
- Docker Engine and the Docker Compose plugin. If the server has no Docker, the installer can install it from Docker’s official signed repository. It never changes a Docker that is already installed.
- DNS records for the dashboard name, and for the single sign-on name if you use it.
- Ports 80 and 443 open to your users. Port 8443, the agent gateway, open only to your trading servers. With single sign-on, port 8081 stays closed: the admin console listens on the server’s loopback only.
- Nothing else listening on 80, 443 or 8443 (or 8081 with single sign-on).
A firewall file looks like this. Replace the example addresses with your trading servers:
After you change the file later, run sudo systemctl restart nile-gateway-firewall.service. Even without a firewall, the control plane refuses agent connections from addresses that are not servers you added.
3. Check the download
Check the bundle before you run anything in it. The installer is part of the download, so it cannot vouch for itself.
- Download nile-<version>-linux-amd64.tar.gz and extract it.
- Get the release key from the PerkBridge documentation, never from the bundle, and save it as allowed_signers outside the extracted folder.
- Check the signature, then every file in the bundle.
If the signature check prints anything else, stop, delete the download and run nothing from it. The preflight ends with preflight passed.
4. Run the guided installer
The installer walks you through six steps. Press Enter to accept a default shown in brackets. It asks for:
- Dashboard address: the name users open in the browser.
- HTTPS certificate: the option from step 1, and your certificate files if you chose files.
- Single sign-on: whether to install it, and its address.
- Organization: its ID and name.
- First administrator: their email and name.
- Bundle check: with your allowed_signers file, or as a development bundle.
On a server without Docker, a seventh step, Docker, asks whether to install it. The installer checks each answer, shows a summary and the complete install command, and installs only when you type yes. It never asks for a password.
Keep the command it shows. If the install stops part way, fix the reported problem and run the same command again: it resumes where it stopped. The install takes a few minutes.
You can also skip the questions and run nile-install install –mode compose with the options directly, for example:
Leave out the –idp-host line for password sign-in only. Add –install-docker on a server without Docker.
5. Sign in for the first time
- Read the first administrator’s password: sudo cat /var/lib/nile/initial-admin-password.
- Open your dashboard address, for example https://nile.example.com/, and sign in with the admin email and that password.
- Keep the password safe, or delete the file after you have signed in.
With single sign-on, you also create users in the identity provider. See Users and single sign-on.
6. After the install
- Status: sudo /var/lib/nile/nile-install status
- Backup: sudo /var/lib/nile/nile-install backup. The archive holds private keys, so store it as carefully as the server. See Backup and restore.
- Stop and start: run docker compose stop and docker compose up -d in /var/lib/nile/compose.
The installer also turns on Add server in the dashboard and sets up alert notifications. Two optional settings live in /var/lib/nile/compose/.env:
- Remembered credentials. Set NILE_VAULT_KEY_FILE=/var/lib/nile/control-plane-vault/vault.key and run sudo docker compose up -d control-plane. The control plane creates its vault key on the next start, and Add server then offers Remember credentials on the server. See Broker credentials.
- Webhook notifications. List the hosts webhooks may post to in NILE_NOTIFIER_WEBHOOK_HOSTS. Telegram, Slack and email work without it. See Alert notifications.
Not supported yet: in-place upgrade, rollback, uninstall, switching modes and native (non-Docker) install. If the installer says upgrade is phase P4, use the bundle of the version you have installed.
Next: Prepare your servers, then Add a server. If something fails, see Troubleshooting.