Headless setup

dassie setup sets a node up from your recovery phrase, kept in a file on the node's server, with no browser. It does what the wallet's setup does, then joins the testnet's XRP hub, or the settlement hubs you name, and it is safe to run at every start.

When to use it

Most owners set their node up in the browser, at the link sudo dassie init prints. Use dassie setup when nobody will open that link: a server a script sets up, the node a market maker trades through, or a node you want set up the same way every time it starts.

It means keeping your phrase on the server. The phrase is your node, and the key to everything it holds: whoever can read the file can take both. Keep it only where you would keep the node's own keys.

Why it works this way: the phrase stays on your server, and only the node key reaches the node.

Before you start

• Dassie is installed and running, as in the Quick Start or on NixOS.
• If the node has a domain name, configure it first, without questions:

  $sudo dassie init --hostname node.example.com --email you@example.com --agree-tos

  It gets the certificate and prints the setup link at the end. Whoever opens that link first claims the node, so run dassie setup right after: once the node is set up, the link no longer works. A node without a domain name skips this step and runs as a periphery node.

• The server's clock is in sync. A phrase says when it was made, and dassie setup refuses one that says it was made more than a day after the server's clock.
• You have a phrase: the 20 words a Dassie wallet makes when it sets up a node. A phrase says which realm it is for, and the node is set up in that realm for good. See Your recovery phrase.

Phrases come from the wallet or the desktop app: there is no command that makes one on the server. A phrase from a 0.2 release doesn't work any more, since the testnet was reset: make a new one, and set the node up from a fresh database (A node from the 0.2 releases).

The phrase file

The file holds the phrase alone: the 20 words, separated by spaces, and nothing else. Make it readable by root only, and keep the phrase out of your shell's history by typing it into cat:

$sudo install -d -m 700 /etc/dassie
$sudo sh -c 'umask 077; cat > /etc/dassie/phrase'
# type or paste the phrase, press Enter, then Ctrl-D

dassie setup reads the file once, wipes the phrase from memory as soon as it has the node key, and never prints the phrase, not even in an error. It refuses:

• a phrase that reads only once some of its words are corrected, naming their positions: fix those words in the file;
• a phrase that says it was made more than a day after the server's clock, naming its date: check the clock;
• a BIP-39 phrase of 12 to 24 words, such as one a 0.2 release made, which Dassie no longer reads;
• a phrase of the live realm, which a node refuses.

Run it

$sudo dassie setup --passphrase-file /etc/dassie/phrase
The passphrase in /etc/dassie/phrase is node 454ml6lg4tjfcz4kaedcmpb5u4mos7af5r2fqui, of the test realm.
Set the node up as 454ml6lg4tjfcz4kaedcmpb5u4mos7af5r2fqui, in the test realm.
The node's engine is running.
Added the settlement scheme xrpl-testnet-xrp.
Added the settlement scheme hub-xrpl-testnet-xrp.

Each step prints a line:

1. It reads the phrase and works out the node key, as the wallet does.
2. It sets the node up with that key, through the same setup the wallet uses, on the node's own address on this server. Only the key reaches the node, never the phrase.
3. It waits, at most a minute, until the node's engine runs.
4. It joins the testnet's XRP hub, which boot1 to boot4, four of the bootstrap nodes, keep: first the node's XRP Ledger testnet book, xrpl-testnet-xrp, which the hub is funded from, then the hub's scheme, hub-xrpl-testnet-xrp.

Nodes settle with each other only through a hub they share, so this is what gets your node its peers. From here the node looks after the money itself: it gets test XRP from the testnet's faucet, and moves about 2.5 of it into the hub to open its account there. dassie hub shows how far it is, and Your hubs covers the wallet's side.

Joining another hub

A node is in one hub per asset. To join a hub other than the one built in, name it by its rules, a long hex string that whoever founded it gives you. Add the XRP book the hub is funded from, which settles with nobody, and then the hub's scheme, with the rules as its config:

$sudo dassie setup --passphrase-file /etc/dassie/phrase \
    --scheme xrpl-testnet-xrp \
    --scheme 'hub-xrpl-testnet-xrp={"rules":"…"}'
…
Added the settlement scheme xrpl-testnet-xrp.
Added the settlement scheme hub-xrpl-testnet-xrp.
The settlement scheme hub-xrpl-testnet-xrp is active already.

A DSUSD hub, hub-xrpl-testnet-dsusd, takes both xrpl-testnet-xrp, which pays the hub's fees, and xrpl-testnet-dsusd first. Setup adds these before it joins any hub, so a new node is in your hub of that asset, not the built-in one. Without --hub, setup still joins the built-in XRP hub as well; add --hub none to stay out of it. A node that is in the built-in hub already stays there: its scheme is active, and setup leaves it as it is. The node keeps the rules you gave it, so it stays in your hub whatever a later release builds in. Run the same command again and each scheme the node runs already is left as it is.

Choosing hubs

--hub says which hubs to join, by the settlement scheme over each, the name dassie hub and dassie status show. Give it once for each hub. It joins the hub of that scheme built into the release, after the books the table names:

• Without --hub, a test phrase joins hub-xrpl-testnet-xrp.
• To be in both of the testnet's hubs, as a market maker's node is, name both: --hub hub-xrpl-testnet-xrp --hub hub-xrpl-testnet-dsusd.
• A hub the node is in already is left as it is, so --hub accepts a hub you joined with --scheme.
• The live realm's hubs, hub-xrpl-xrp and hub-xrpl-rlusd, are refused with a test phrase, before anything changes. No mainnet hub is built in yet.

Hubs are explained in Settlement hubs, and every scheme in Schemes and hubs.

Ledger settings and other schemes

Two more flags, each repeatable, are for setups that need more than a hub:

• --asset <id>=<config> sets the JSON config of one of the node's ledger accounts before it adds any scheme or joins a hub, such as the XRP Ledger server of the testnet account: --asset 'xrpl-testnet-account/0={"server":"wss://xrpl.example.net"}'. The server must serve the proofs the node checks, as a proof server does. For an account the node already uses, the new config takes effect when the node next starts (sudo systemctl restart dassie).
• --scheme <id>[=<config>] adds a settlement scheme the node does not run yet, with its JSON config if it takes one.

Running it again

dassie setup changes only what is missing, so you can run it as often as you like. On a node set up with the same phrase, it says The node is set up already and goes on to the settings and hubs. Its exit code tells a script what happened:

A node set up in another realm than the phrase's is refused too, with nothing changed: a node's realm never changes.

Running it from a unit

To set the node up the same way at every boot, run dassie setup from a systemd unit that starts once the node is ready and the clock is in sync:

[Unit]
Description=Set up the Dassie node from its phrase
Requires=dassie.service
After=dassie.service time-sync.target
Wants=time-sync.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/dassie setup --passphrase-file /etc/dassie/phrase

[Install]
WantedBy=multi-user.target

$sudo systemctl daemon-reload
$sudo systemctl enable --now dassie-setup.service
$journalctl -u dassie-setup

time-sync.target waits for a synced clock only where a service holds it back until then: with systemd-timesyncd, enable systemd-time-wait-sync.service; with chrony, chrony-wait.service.

On NixOS

The same unit, in your configuration:

systemd.services.dassie-setup = {
  description = "Set up the Dassie node from its phrase";
  wantedBy = [ "multi-user.target" ];
  requires = [ "dassie.service" ];
  wants = [ "time-sync.target" ];
  after = [ "dassie.service" "time-sync.target" ];
  serviceConfig = {
    Type = "oneshot";
    ExecStart = "${config.services.dassie.package}/bin/dassie setup --passphrase-file /etc/dassie/phrase";
  };
};