From install to live data in minutes

Install a node

Bare metal or Docker

A node is one program, spacedatanetwork. You can run it directly on a computer you control (“bare metal”: a server, a virtual machine or a desktop, with no container around it) or inside Docker. Both run the same node, join the same network and keep the same kind of identity. Pick the one that fits how you already run software.

Bare metal: download and install

The installer finds the newest node release on GitHub, downloads the bundle for your system, checks it against the release’s published checksums, unpacks it under ~/.spacedatanetwork/bundles, puts the spacedatanetwork command (and its short name, sdn) in ~/.spacedatanetwork/bin, and creates the node’s identity. It needs no administrator rights.

curl -fsSL https://spacedatanetwork.org/install.sh | bash

irm https://spacedatanetwork.org/install.ps1 | iex

• If the installer says ~/.spacedatanetwork/bin is not on your PATH, add it: export PATH="$HOME/.spacedatanetwork/bin:$PATH".
• To install a particular release instead of the newest, set SDN_VERSION, for example SDN_VERSION=v1.0.5-beta.70. SDN_INSTALL_DIR and SDN_BUNDLE_DIR move the command links and the bundles.
• The installer runs the node once before it reports success. On a Linux system too old for the build (its C library, glibc, is older than the one the node was built against) it says so, leaves nothing running, and points you to the Docker image instead.
• The same bundles (spacedatanetwork-<version>-<system>-<cpu>.tar.gz, .zip for Windows) and spacedatanetwork-checksums.txt are on every release page; the download section links the current ones.

First run

spacedatanetwork start     # install and start the background service
spacedatanetwork status    # is the node up?
spacedatanetwork open      # print the dashboard address, http://127.0.0.1:5001/

For a session in the foreground instead, with the log in your terminal, run spacedatanetwork daemon. Run the node as an ordinary user, never as root.

The background service

spacedatanetwork start installs a service for the user who runs it and starts it; the service restarts the node if it stops.

spacedatanetwork stop                # stop and disable the service
spacedatanetwork restart
spacedatanetwork service status      # the operating system's view of the service
spacedatanetwork service uninstall   # remove the service
spacedatanetwork remove              # remove this install; keeps the identity and data
                                     # (add --purge-data to delete those too)

On a Linux server you log out of, a user service stops with your last session unless systemd keeps the user’s services running. That is a systemd setting, not a node setting: sudo loginctl enable-linger $USER. Read the node’s log with journalctl --user -u spacedatanetwork -f.

Configuration and keys

The first run writes the configuration to ~/.spacedatanetwork/config.yaml; the records go to ~/.spacedatanetwork/data and the keys beside them in ~/.spacedatanetwork/keys. Every command takes --config <file> (or the SDN_CONFIG variable) to use another file. The settings to check before you open the node to the internet are listed in INSTALL.md: where the records are stored and how much space they may use, and keeping the dashboard on this computer only (127.0.0.1:5001) unless it has TLS and sign-in turned on.

The node’s identity is a recovery phrase sealed to this computer. Export a backup once and keep it somewhere other than this computer: spacedatanetwork key export --format backup.

Ports

No port has to be open for the node to work. Opening 4001, 8080 and 4003 to incoming connections is what makes it a full node; see full nodes and NAT nodes below.

Linux packages

Each release also carries Debian and RPM packages for Linux x86-64 (spacedatanetwork-full_<version>_amd64.deb and spacedatanetwork-full-<version>-1.x86_64.rpm; the version is written with dots, such as 1.0.5.beta.70). They install the node under /opt/spacedatanetwork, a configuration at /etc/spacedatanetwork/config.yaml that keeps records under /var/lib/spacedatanetwork, and a system-wide service, /etc/systemd/system/spacedatanetwork.service, that runs as a user named sdn. The packages create neither that user nor /var/lib/spacedatanetwork, so create both before starting the service. For a single server, the installer above is simpler.

Docker

The image is dockerdigitalarsenal/space-data-network, tagged by release (v1.0.5-beta.70) and with a moving beta tag for the newest beta. It carries the node, its storage engine, IPFS (Kubo) and the sign-in pages, and runs as an ordinary user inside the container.

docker run -d --name sdn --hostname sdn --restart unless-stopped \
  -v sdn-data:/app/data \
  -p 127.0.0.1:5001:5001 -p 4001:4001 -p 4001:4001/udp \
  dockerdigitalarsenal/space-data-network:v1.0.5-beta.70

services:
  sdn:
    image: dockerdigitalarsenal/space-data-network:v1.0.5-beta.70
    container_name: sdn
    hostname: sdn
    restart: unless-stopped
    ports:
      - "127.0.0.1:5001:5001"
      - "4001:4001"
      - "4001:4001/udp"
    volumes:
      - sdn-data:/app/data
volumes:
  sdn-data:

• The volume. Everything the node owns is in /app/data: records, keys and sign-in records. Keep the volume and you keep the node.
• The hostname is required. Unless you give the node a key password, it seals its keys with a password derived from the container’s hostname, and Docker invents a new hostname every time a container is created. A first start without --hostname refuses and prints what to do. Any fixed name works; it is not a secret. To use a password instead, mount a file and point SDN_KEY_PASSWORD_FILE at it.
• Ports. The command keeps the dashboard on this computer (127.0.0.1:5001) and opens 4001 for other nodes. For a full node that browsers can reach too, also publish -p 8080:8080 -p 4003:4003/udp.
• First start is slower. The node compiles its storage engine for this computer’s processor and keeps the result in the volume.
• Dashboard: http://127.0.0.1:5001/. The recovery phrase: docker exec sdn /app/spacedatanetwork show-identity --config /app/config/full-docker.yaml --show-mnemonic.
• Your own configuration. The image starts with daemon --config /app/config/full-docker.yaml. Mount your own file and pass daemon --config <file> as the command to replace it.
• No Docker Hub? Every release carries the image as an archive for docker load, for example spacedatanetwork-container-1.0.5.beta.70-linux-amd64.tar.gz (the version is written with dots).

Full nodes and NAT nodes

Can other nodes reach yours?

Every node runs the same software. What differs is whether other computers on the internet can open a connection to it. That depends on your network, not on a setting you have to choose: the node checks for itself and adjusts.

NAT (network address translation) is how most home and office routers share one public internet address among many computers. Computers behind it can connect out, but nothing outside can connect in unless the router forwards a port to them. Many mobile and some home internet providers add a second layer of it (carrier-grade NAT), and company firewalls often block incoming connections the same way.

• A full node is publicly reachable: any node can connect to it directly.
• A NAT node sits behind NAT or a firewall. It connects out to other nodes, and they reach it through those connections or through a relay.
• A relay is a full node that passes traffic between two nodes that cannot connect to each other directly.

How a node finds out

Shortly after it starts, the node asks nodes it has connected to whether they can connect back to it (a check called AutoNAT). While the answer is yes, it acts as a full node. While it is no, it acts as a NAT node and tries, on its own, to become reachable:

• it asks the router to forward its ports (UPnP or NAT-PMP, where the router allows it), and asks again if the router restarts and forgets;
• it books a place on a relay, so others can reach it through the relay;
• when another node connects through a relay, the two try to open a direct connection through both routers at the same moment (hole punching), which often works.

What each can do

Which to run

• A NAT node is fine for a laptop, a desktop or an office server that subscribes to data, analyses it and publishes small streams. There is nothing to set up.
• Run a full node to publish datasets other nodes download, to offer software and services, or to help carry the network: an always-on server with a public address and ports 4001 (TCP and UDP), 8080 (TCP) and 4003 (UDP) open to incoming connections, either directly, on a cloud server’s firewall, or forwarded by your router.

Settings

The defaults suit almost everyone. These three, in the network part of config.yaml, change the behavior:

network:
  enable_relay: auto   # auto: relay while reachable (default); always; never
  dht_server: auto     # auto: serve the directory while reachable (default); always; never
  announce: []         # extra public addresses to advertise, as multiaddrs

• enable_relay: never keeps a reachable node from relaying for others; it can still reach others through relays. always relays whether or not the node is reachable. dht_server takes the same three values.
• announce is for a node reached at an address it cannot see itself, such as a DNS name or a port your router or load balancer forwards, for example /dns4/node.example.org/tcp/4001.
• Signed in as the operator, GET /api/v1/status/reachability on the local API gives the node’s own answer: direct (a full node), relayed (a NAT node reachable through a relay), unconfirmed or unreachable.