127 lines
3.4 KiB
Markdown
127 lines
3.4 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`
|
|
- `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
|
|
```
|