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` (aka `amd64`)
- `aarch64` (aka `arm64`)
- `i686`

(`i686` has not been tested.)

More OSs and architectures coming soon!

## Install isle

How isle gets installed depends on which Linux distribution you are using.

### Archlinux (also Manjaro)

Download the latest `.pkg.tar.zst` package file for your platform from
[this link][latest].

Install the package using pacman:

```
sudo pacman -U /path/to/isle-*.pkg.tar.zst
```

### Other Distributions

If a package file is not available for your distribution you can still install
an AppImage directly. It is assumed that all commands below are run as root.

Download the latest `.AppImage` binary for your platform from
[this link][latest], and place it in your `/usr/bin` directory.

Create a `daemon.yml` file using default values by doing:
```
mkdir -p /etc/isle/
isle daemon --dump-config > /etc/isle/daemon.yml
```

Create a system user for the isle daemon to run as:
```
useradd -r -s /bin/false -C "isle Daemon" isle
```

If your distro uses systemd, download [the latest systemd service
file][serviceFile] and place it in `/etc/systemd/system`. Run `systemctl
daemon-reload` to ensure systemd has seen the new service file.

If your distro uses an init system other than systemd then you will need to
configure that yourself. You can use the systemd service file linked above as a
reference.

[serviceFile]: https://code.betamike.com/micropelago/isle/src/branch/main/dist/linux/isle.service

### From Source

(TODO probably move these instructions into the Dev docs section).

Building from source requires [nix][nix].

You can build your own AppImage by running the following from the project's
root:

```
nix-build -A appImageBin
```

(*NOTE* The first time you run this a lot of things will be built from scratch.
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 under `result/bin`. From here you can continue
with the instructions under the "AppImage" section above.

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

## Add Users to the `isle` Group (Optional)

If you wish to run isle commands as a user other than root, you can add that
user to the `isle` group:

```
sudo usermod -aG isle username
```

## Start the isle Service

Once installed and bootstrapped you can enable and start the isle service by
doing:

```
sudo systemctl enable --now isle
```

(NOTE If your distro uses an init system other than systemd then you will need
to instead start isle according to that system's requirements.)

## Join a Network

This section will guide you through the process of joining an existing network
of isle hosts. If instead you wish to create a new network for others to join
then see the [Creating a New Network][creating-a-new-network] page.

To join an existing network you will need to first obtain a `bootstrap.json`
file. The `bootstrap.json` 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.

Once obtained, you can join the network by doing:

```
isle network join --bootstrap-path /path/to/bootstrap.json
```

After a few moments you will have successfully joined the network!

[creating-a-new-network]: ../admin/creating-a-new-network.md

[latest]: https://code.betamike.com/micropelago/isle/releases/latest