Skip to content
Open vault
Documentation

First Setup

Overview

After you install your node, finish setup in your browser. You register yourself as the administrator with the one-time setup code, unlock the node, and complete the three Setup checks: Deploy, Client and Health.

Run commands on the Linux server. Open the web pages on your own computer, in a current Chromium-family desktop browser such as Chrome or Edge, with a working device passkey or hardware security key.

Keep the hostname: passkeys depend on it

The default WebAuthn relying party ID is your hostname. Admin and Safe passkeys depend on it. Wait for trusted HTTPS before registering, and register credentials only through that hostname, never through an IP address or a temporary name.

Set up DNS and HTTPS

  1. At your DNS provider, create an A record for the chosen hostname pointing to the server's public IPv4 address. If the provider asks for only the record name within example.com, enter node to create node.example.com.
  2. Publish an AAAA record only if the public IPv6 address reaches this server too. A stale AAAA record can send browsers or certificate validation to the wrong machine even when the A record is correct. Remove it if you are not using IPv6.
  3. Allow inbound TCP 80 and 443 through both the provider firewall and the host firewall. Forward them to the server if it is behind a router. Another web server must not already occupy those ports.
  4. Allow TCP 9001 for the default non-exit Tor relay. See The default Tor relay below.

  5. Check DNS from your own computer as well as the server:

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

The bundled Caddy proxy obtains and renews HTTPS certificates automatically. Email for automatic certificate issuance is optional; no private signing key or managed-service credentials are needed.

Register the admin

  1. Open the printed admin address, such as https://node.example.com/admin, using the exact hostname.
  2. Wait for trusted HTTPS to work. Do not bypass certificate warnings. A printed admin URL or setup code alone does not prove HTTPS is ready.
  3. Choose Register admin and enter the printed one-time setup code.
  4. Register your passkey or security key.
  5. Choose your admin PIN, following the prompts. You choose its length and may repeat keypad symbols.
  6. Choose Unlock Node when prompted.

The setup code expires after 30 minutes

Keep the setup code private and use it promptly. If it is missing, read the original startup log with sudo docker logs unolock-node; it is usable only until its original expiry. Restarting does not issue a new code. For an expired code, see Troubleshooting.

Signing in and unlocking are separate steps: a running but locked node does not serve your Safes.

Complete Setup: Deploy, Client, Health

Complete the three Setup checks in order:

Check What to do
Deploy Confirm the permanent HTTPS address and domain. For the standard installation, keep the hostname you chose.
Client Use the offered Sign Client or Rebuild And Sign Client action. This prepares and signs the browser app your node serves. Keep the page open until it finishes; it can take several minutes.
Health Run the health check. Resolve any failed check before continuing.

Once setup passes, Home is the starting point for normal administration. See Admin console.

Signing the browser client

The word client here means the UnoLock app that runs in your browser. Signing lets browsers check its integrity and continuity with this node's signing key. You do not need to create or handle a signing key manually.

The default Tor relay

The node runs a default non-exit Tor relay on TCP 9001. It contributes up to 10 Mbps in each direction and publishes the server's IP as a Tor relay. Review its bandwidth, privacy implications and disable option in Tor before unlocking the node.

The relay is enabled because self-hosted nodes use Tor and should help sustain the network they depend on. Non-exit relaying supports general Tor traffic while keeping internet exit operation outside the node's role. Administrators can increase the 10 Mbps default or disable relaying to suit their connection, transfer allowance and privacy needs.

Existing containers need the 9001:9001 mapping added when recreated. Changing admin settings does not change Docker port mappings.

Finish your first checks

  1. In Safes, create a Safe registration code. Open the node's main HTTPS page and choose Create Vault to create your first Safe with that code. See Creating Safes.
  2. Save a test note, upload and download a small file, sign out, and reopen the Safe. Save the recovery material.
  3. In Access, register a separate administrator recovery security key. Test a fresh sign-in and node unlock with it. Keep it and its PIN separate from your backups.
  4. Create and verify a backup. See Backup and recovery.

Docker normally restarts the container when the server restarts. With the default setup, you must then sign in to /admin and choose Unlock Node before Safes are available. See Restarts and unlocking.

If setup stops

The setup script reports missing configuration, unusable hostnames, unresolved DNS, local port conflicts, engine access, build/pull errors, and detected container exits.

For a container that has started but whose admin page is unavailable:

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

Check the reported startup or certificate error, DNS A and AAAA records, firewall rules and port forwarding. Logs may contain private setup codes; do not post raw logs publicly. Never delete the volume as a troubleshooting shortcut. See Troubleshooting.

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

FAQs

Why does the admin page show a certificate warning?

HTTPS is not ready yet, or DNS, firewall or port forwarding is not routing correctly. Do not bypass the warning. Check the A and AAAA records, firewall rules and the container logs for the certificate error, then try again.

What rules apply to the admin PIN?

You choose its length and may repeat keypad symbols, following the prompts during registration.

Is the admin setup code the same as a Safe registration code?

No. The admin setup code registers the administrator once. A Safe registration code allows a new Safe to be created. Never give the admin setup code to a Safe user.

Do I have to sign the browser client?

Yes. Complete Client in Setup using Sign Client or Rebuild And Sign Client. Signing lets browsers check the app's integrity and continuity with the node's signing key.

Can I turn off the Tor relay?

Yes. Administrators can increase the default or disable relaying. See Tor.

Why are my Safes unavailable after a restart?

The node starts locked. Open /admin, sign in, and choose Unlock Node.

Back to Self-Hosted Overview