Skip to content
Open vault
Documentation

Install Your Node

Overview

There are two ways to install the UnoLock Federated Node on a Linux server:

  • Guided setup from a Git clone. The run-node.sh --setup --build script walks through DNS, builds the checkout as a local image and launches it without a registry pull.
  • Prebuilt release image. Download the launcher from a published release and run it with the exact image reference from that release's notes.

Both routes create the same installation: a container named unolock-node, a persistent volume named unolock-node-data mounted at /data, automatic HTTPS, and automatic container restart. Run the commands on the Linux server that will host the node. Open the admin and Safe pages in your own computer's browser.

Before you start, check the Requirements, point your hostname's DNS at the server and secure the host. See Host security.

Keep the hostname: passkeys depend on it

The default WebAuthn domain and HTTPS origin follow your hostname. Admin and Safe passkeys depend on it, so keep it for the lifetime of the installation.

Install with the guided setup

  1. Install and start Docker Engine, then install Git and dig. Confirm Docker works:

    sudo docker info

  2. Clone the repository and run the guided setup:

    git clone https://github.com/TechSologic/unolock-federated-node.git
cd unolock-federated-node
sudo sh packaging/docker/run-node.sh --setup --build

  3. Enter your hostname when asked, for example node.example.com. The script shows its DNS addresses, checks local port conflicts, and walks through the firewall and passkey requirements.

  4. Compare every displayed address with the public addresses assigned to this server.
  5. Type the hostname again to confirm the settings. The script builds the checkout as unolock-node:local and starts it without pulling an image from the registry.
  6. Note the admin URL and the private one-time setup code that the script prints. Continue with First setup.

Public base-image and package downloads still need internet access. A first build can take several minutes. It uses the files currently in the checkout, so avoid unrelated edits when preparing an installation.

Check without building

To check configuration, engine, DNS and local port conflicts without building or starting anything:

sudo sh packaging/docker/run-node.sh --domain node.example.com --check

These checks use the server's configured DNS resolver. They cannot prove that other networks see the same DNS records or that inbound firewall rules, router forwarding and HTTPS work. Check DNS from the network where you will use your browser too, and allow time for old DNS records to expire. For example, on a computer with dig:

dig +short node.example.com A
dig +short node.example.com AAAA

Use an existing local image

To use an image you have already built locally instead of building again:

sudo sh packaging/docker/run-node.sh --setup --image unolock-node:local --pull never

Install from a release image

1. Get the launcher

  1. Open the public releases page.
  2. Choose a release for linux/amd64, read its notes and download its launcher archive and SHA256SUMS.

  3. Verify the archive:

    sha256sum --check --ignore-missing SHA256SUMS

  4. Confirm that the launcher archive reports OK. Review the checksums from the same trusted release page; checksums detect changed files but do not establish publisher identity.

  5. Extract the archive and open a terminal in its directory, which contains packaging/.

2. Select the image

Copy the complete immutable image reference from that release's notes, in the form IMAGE@sha256:.... Do not use the literal example. Set it once in your terminal so the commands below use the exact selected image:

read -r -p 'Image reference from release notes: ' UNOLOCK_IMAGE

The launcher defaults to the latest tag if no image is supplied. Supplying the exact reference means a development tag cannot silently change the image you install. Starting an existing container keeps its installed image.

3. Start the node

Enter your hostname at the prompt, for example node.example.com. Enter only the name, without https://, a port, or a path:

read -r -p 'Permanent node hostname: ' UNOLOCK_DOMAIN
sudo sh packaging/docker/run-node.sh --domain "$UNOLOCK_DOMAIN" --image "$UNOLOCK_IMAGE" --engine docker

The launcher creates:

  • a Docker container named unolock-node, which runs the software;
  • a persistent Docker volume named unolock-node-data, which holds the node's data and survives container replacement;
  • an HTTPS site at your hostname, using an automatically renewed certificate.

It then prints the admin URL, such as https://node.example.com/admin, and a one-time admin setup code. Keep the code private and continue to First setup immediately: it expires after 30 minutes.

If any command reports an error, stop at that step and resolve it before continuing. See Common installation problems.

Optional settings

These options apply when creating a container. Rerunning the launcher does not change an existing container. Record custom settings so you can reapply them during upgrades.

An email address for automatic certificate issuance is optional:

sudo env \
  UNOLOCK_EMAIL=operator@example.com \
  sh packaging/docker/run-node.sh --domain node.example.com

The launcher creates or reuses the unolock-node-data volume and stores the validated domain, so ordinary restarts do not require the environment variable again.

Docker is the default engine; the script falls back to Podman when Docker is unavailable. Use --engine podman explicitly when needed. For rootless Podman, run:

UNOLOCK_CONTAINER_ENGINE=podman \
  sh packaging/docker/run-node.sh --domain node.example.com

The host must permit the rootless user to bind ports 80 and 443. Otherwise use rootful Podman or configure the host's unprivileged-port policy before running the launcher. Run setup and later maintenance under the same engine and user.

The launcher also accepts --name for the container name (default unolock-node) and --volume for the persistent volume (default unolock-node-data). For other settings, including your own HTTPS certificate, see Configuration.

Stop, start and view logs

These commands use the default names.

To stop the node:

sudo docker stop unolock-node

To start an existing installation again and print its admin URL, run the launcher without --build:

sudo sh packaging/docker/run-node.sh

Starting an existing container keeps its hostname, data and image. It does not reinstall the node or apply an upgrade. Sign in to admin and choose Unlock Node after starting. See Restarts and unlocking.

To check status or read recent logs:

sudo docker ps -a --filter name=unolock-node
sudo docker logs --since 10m --tail 200 unolock-node

Logs can contain private setup codes and operational information. Do not post raw logs publicly.

Note

--build deliberately refuses an existing container. To replace a container while preserving its volume and identity, follow Upgrading. Never delete the volume as a troubleshooting shortcut.

Common installation problems

What you see What to check next
Docker or Podman is required, or Docker cannot connect Check that Docker Engine is installed and running on the server and that sudo docker info succeeds.
Docker cannot pull the image Check the server's internet connection and the registry error. Check the exact image reference copied from the release notes.
host port 80/443 is already in use Another service is using the web ports. Use a separate host or resolve the port conflict before rerunning the launcher.
The admin page will not open or HTTPS fails Check the hostname's DNS records, provider firewall, server firewall, and router forwarding if applicable. Read the container logs for the actual certificate or startup error.
The setup code is missing Read the original startup log with sudo docker logs unolock-node. It is usable only until its original expiry.
The setup code has expired or cannot be recovered See Troubleshooting. Restarting does not issue a new code. Preserve the data volume.

Build and pull failures do not create a container or volume. If launch fails after creating the volume, it is retained. Read the actual engine error and preserve existing state.

The full reference is in the repository: First setup from a clone and Install and upgrade.

FAQs

Which install route should I choose?

Use the guided setup if you are building from a Git clone; it walks through DNS and builds the local image. Use the release-image route if you want to run a prebuilt image from a published release, using the launcher and exact image reference from that same release.

Does the guided setup install Docker for me?

No. The setup script checks Docker access; it does not install Docker. Install and start Docker Engine first and confirm sudo docker info succeeds.

How long does the first build take?

A first build needs internet access for public dependencies and can take several minutes.

Does starting an existing container upgrade it?

No. Starting an existing container keeps its hostname, data and image. To move to a new release, follow Upgrading.

Where is my node's data stored?

In the persistent volume unolock-node-data, mounted at /data inside the container. It survives container replacement. Do not delete it as a troubleshooting step.

Back to Self-Hosted Overview