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](https://code.betamike.com/micropelago/isle/releases/latest).

### 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][tmpdir-gh].))

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

[tmpdir-gh]: https://github.com/NixOS/nix/issues/2098#issuecomment-383243838

## 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
```