isle/docs/user/getting-started.md

124 lines
3.1 KiB
Markdown
Raw Normal View History

# 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
2023-12-23 16:06:16 +00:00
### The Easy Way
2023-12-23 16:06:16 +00:00
Download the latest binary for your platform from
[this link](https://code.betamike.com/micropelago/isle/releases/latest).
2023-12-23 16:06:16 +00:00
### 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
2023-12-23 16:06:16 +00:00
## Obtaining Your Bootstrap File
The `bootstrap.json` file contains all information required for your particular
2023-12-23 16:06:16 +00:00
host to join the network, and must be generated and provided to you by an admin
for the network.
## Running the Daemon
2023-12-23 16:06:16 +00:00
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.json
```
This will start the daemon process, which will keep running until you kill it
with `ctrl-c`. The `--bootstrap-path /path/to/bootstrap.json` argument is only
2023-12-23 16:06:16 +00:00
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
```