isle/docs/user/getting-started.md

Getting Started

This document will guide you through the process of obtaining an isle binary and joining a network.

NOTE currently only linux machines with the following architectures are supported:

• x86_64 / amd64
• aarch64 / arm64
• i686

(Only x86_64 has been tested.)

More OSs and architectures coming soon!

Obtaining an isle Binary

The Easy Way

Download the latest binary for your platform from this link.

The Hard Way

Alternatively, you can build your own binary by running the following from the project's root:

nix-build -A appImage

(NOTE Dependencies of isle seemingly compile all of musl and rust from scratch (it's not clear why, blame garage!). If you have not otherwise configured it, nix might be using a tmpfs as its build directory, and the capacity of this tmpfs will probably be exceeded by this build. You can change your build directory to somewhere on-disk by setting the TMPDIR environment variable for nix-daemon (see this github issue.))

The resulting binary can be found in the result directory which is created.

Obtaining Your Bootstrap File

The bootstrap.yml file contains all information required for your particular host to join the network, and must be generated and provided to you by an admin for the network.

Running the Daemon

Once you have a binary and bootstrap file, you will need to run the daemon sub-command as the root user. This can most easily be done using the sudo command, in a terminal:

sudo /path/to/isle daemon --bootstrap-path /path/to/bootstrap.yml

This will start the daemon process, which will keep running until you kill it with ctrl-c. The --bootstrap-path /path/to/bootstrap.yml argument is only required the first time the daemon is run, it will be ignored on subsequent runs.

You can double check that the daemon is running properly by pinging a private IP from the network in a separate terminal:

ping 10.10.0.1

If the pings are successful then your daemon is working!

Installing the Daemon as a Systemd Service

NOTE in the future we will introduce an install sub-command which will automate most of this section.

Rather than running the daemon manually, you can install it as a systemd service. This way your daemon will automatically start in the background on startup, and will be restarted if it has any issues.

To do so, create a file at /etc/systemd/system/isle.service with the following contents:

[Unit]
Description=isle
Requires=network.target
After=network.target

[Service]
Restart=always
RestartSec=1s
User=root
ExecStart=/path/to/isle daemon

[Install]
WantedBy=multi-user.target

Remember to change the /path/to/isle part to the actual absolute path to your binary!

Once created, perform the following commands in a terminal to enable the service:

sudo systemctl daemon-reload
sudo systemctl enable --now isle

You can check the service's status by doing:

sudo systemctl status isle

and you can view its full logs by doing:

sudo journalctl -lu isle