130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
# 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
|