Requirements
Overview
This page lists what you need before you install the UnoLock Federated Node. The standard installation runs the packaged container on a Linux server with Docker Engine, behind a permanent hostname with automatic HTTPS.
You need to be able to sign in to your server, run terminal commands, and change DNS and firewall settings with your hosting provider.
What you need
| You need | What it means |
|---|---|
| A Linux server | A 64-bit Intel/AMD (amd64/x86_64) machine with persistent local storage. It must stay on whenever you want to access your Safes. A rented virtual server can provide this. |
| A permanent hostname | A name you control, such as node.example.com. Use a DNS A record pointing to the server's public IPv4 address. If you also publish an AAAA record, its IPv6 address must reach this server too. |
| Open ports | Allow inbound TCP 80 and 443 in both the provider's firewall and the server's firewall, plus TCP 9001 for the default non-exit Tor relay. At home, you also need router port forwarding and a reachable public address. |
| Docker Engine | Docker runs the packaged node software. Follow the Docker Engine installation instructions for your Linux distribution, then start Docker. Confirm sudo docker info succeeds. The setup script checks Docker access; it does not install Docker. |
Git and dig |
Needed for the guided setup from a clone and its DNS check. Install dig from dnsutils on Debian/Ubuntu or bind-utils on Fedora. |
| A browser and passkey | A current Chromium-family desktop browser, such as Chrome or Edge, on your own computer, with a working device passkey or hardware security key to register the administrator. |
| TPM (optional) | TPM 2.0 with tpm2-tools when unattended hardware sealing is configured. Without it, an admin unlocks the node after each restart. |
Server and storage
The host is 64-bit Linux on amd64, with local persistent storage that supports file locking, atomic rename, and durable file and directory sync.
Reserve space for archives, queues, database/WAL growth, upgrades and independent backups. Measure process memory, CPU, free volume space and transfer volume under your expected workload.
The release container includes and controls its Node.js, Tor, Caddy and native dependency versions. You do not need Node.js, npm, Tor or a web server installed on the host. Do not replace those components inside a released image; apply an updated image instead. See Upgrading.
Hostname
Choose the hostname carefully. The default WebAuthn relying party ID is this hostname, so your admin and Safe passkeys depend on it.
Keep the hostname: passkeys depend on it
Keep the hostname for the lifetime of the installation. Do not start with an IP address or a temporary hostname and plan to rename it later. Changing it later is not a supported way to move the node. You can move to a different server while keeping the same hostname using the backup and recovery procedure.
For the standard direct installation, DNS must route to the server. Additional CDN or proxy configurations need their own routing and TLS setup.
Network and ports
- TCP 80: the bundled Caddy proxy uses it for HTTP-to-HTTPS redirects and HTTP certificate validation.
- TCP 443: HTTPS access to the admin app and Safes.
- TCP 9001: the default non-exit Tor relay. It contributes up to 10 Mbps in each direction and publishes the server IP as a relay. See Tor for the bandwidth, privacy implications and disable option.
The standard setup uses the server's ports 80 and 443 itself. If another website already uses those ports, use a separate server for this installation. Do not expose internal node or lookup listeners.
For a home server, check router forwarding and whether your provider uses carrier-grade NAT (CGNAT).
Container engine
Docker Engine with the supplied run-node.sh launcher is the standard engine. The launcher falls back to Podman when Docker is unavailable, and you can select it with --engine podman. Rootless Podman may require host configuration to bind ports 80 and 443. Run setup and later maintenance under the same engine and user so they see the same containers and volumes.
Browser
Use a current Chromium-family desktop browser with WebAuthn/passkey support, such as Chrome or Edge, and a working device passkey or hardware security key.
FAQs
Do I need to install Node.js or Tor on the server?
No. Docker builds or runs the runtime, browser app, service worker and Tor together. You only need Docker Engine, plus Git and dig for the guided setup from a clone.
Can I use an IP address instead of a hostname?
No. Admin and Safe passkeys are tied to the hostname. Choose a permanent hostname you control and register credentials only through that hostname once HTTPS is trusted.
Do I need a TPM?
No. A TPM is optional. TPM 2.0 with tpm2-tools enables unattended hardware sealing. Without it, an admin signs in and unlocks the node after each restart.
Why does the node need port 9001?
TCP 9001 is used by the default non-exit Tor relay. You can review its bandwidth and privacy implications, and how to disable it, in Tor.
Can I run the node alongside another website on the same server?
The standard setup uses ports 80 and 443 itself. If another website already uses those ports, use a separate server for this installation.