124 lines
3.1 KiB
Markdown
124 lines
3.1 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` / `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
|
|
|
|
## Obtain a 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
|
|
```
|