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`
- `armv7l` (Raspberry Pi)
- `i686`

(Only `x86_64` has been tested.)

More OSs and architectures coming soon!

## Obtaining an isle Binary

Every host can have a binary built for it which has all configuration for that
host embedded directly into it. Such binaries require no extra configuration by
the user to use, and have no dependencies on anything else in the user's system.

The process of obtaining a custom binary for your host is quite simple: ask an
admin of your network to give you one!

Note that if you'd like to join the network on multiple devices, each device
will needs its own binary, so be sure to tell your admin how many you want to
add and their names.

### Obtaining an isle Binary, 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.

In this case you will need an admin to provide you with a `bootstrap.yml` for
your host, rather than a custom binary. When running the daemon in the following
steps you will need to provide the `--bootstrap-path` CLI argument to the daemon
process.

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

## Running the Daemon

Once you have a binary, 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
```

This will start the daemon process, which will keep running until you kill it
with `ctrl-c`.

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