# Getting Started

## System Requirements

As of the latest release, Sylve requires **FreeBSD 15.0-RELEASE or later**. You will also need to have a **ZFS pool** available if you intend to use Sylve for managing Virtual Machines or Jails. If you are using Sylve just for things like WireGuard or the built-in firewall, you can use any filesystem, but ZFS is still recommended for its advanced features and reliability.

:::note
Although we list support for FreeBSD **15.0-RELEASE**, we **strongly recommend** using **-STABLE** with pkgbase, **-CURRENT** is also supported, but remember to disable any debug features in the config if you're using it in production!

Since both Sylve and Bhyve are under pretty active development, using a more recent version of FreeBSD will ensure you have the latest features and bug fixes. That said, if your use case requires maximum stability and you do not need the latest features or bug fixes, **15.0-RELEASE** should work perfectly fine.
:::

:::caution[Configure a hostname before signing in]
Every node must have a hostname. It identifies the system throughout Sylve, and login attempts will be refused if one is not configured.

On FreeBSD, set a persistent hostname before starting Sylve:

```bash
sysrc hostname="sylve-node.lan"
hostname sylve-node.lan
```
:::

## TL;DR

If you want to get going right away, run `pkg install sylve` on a FreeBSD >= 15 machine and open `https://<host>:8181` in your browser. For more details, continue reading.

## Software Dependencies

Sylve is designed to run using only **base FreeBSD dependencies** if you prefer. However, we recommend installing the following packages:

| Capability | Packages | What they enable | Requirement |
| --- | --- | --- | --- |
| **Bhyve virtualization** | `libvirt`, `bhyve-firmware`, `swtpm`, `qemu-tools` | Virtual-machine creation and management, firmware support, virtual TPMs, and disk-image tooling. | Required to use the virtualization subsystem. |
| **SMB file sharing** | `samba4XX` | SMB shares for guests and Jails, including basic share management and audit logging. | Optional; required for SMB features. |
| **DHCP and DNS** | `dnsmasq` | Managed DHCP ranges, leases, and DNS services from within Sylve. | Optional; required for managed DHCP and DNS. |

Install all recommended dependencies at once:

```bash
pkg install -y libvirt bhyve-firmware swtpm qemu-tools samba423 dnsmasq
```

If you install Sylve with `pkg install sylve`, these dependencies are pulled in **automatically**; the command above is only needed when installing Sylve manually or building it from source.

## Hardware Requirements

Use this estimator as a conservative starting point for a Sylve host running a mix of Jails, Bhyve virtual machines, and replicated workloads. Enter the resources assigned across your VMs rather than relying on a VM count. Jails use a modest mixed-services baseline; applications with known requirements should be sized separately.

<HardwareEstimator />

Replica capacity is shown separately because it is consumed on the destination host or backup target. For active replication, prefer at least a **1 Gbps** link and leave additional ZFS headroom for snapshots and changed blocks.

:::note
If you are going to test out Sylve on providers like Hetzner, know that many of them **do not** support nested virtualization, so they cannot run Bhyve guests. Jails do not require nested virtualization and remain available on those hosts, along with all other features of Sylve.
:::

## Installing Sylve

### From pkg

As mentioned before, the easiest way to install Sylve is via the FreeBSD package manager. Run the following command:

```bash
pkg install sylve
```

It will pull in all the required dependencies and install Sylve on your system. Once the installation is complete, you can enable and start the service using:

```bash
service sylve enable && service sylve start
```

### Installing from GitHub Releases

:::note
The releases are built using GitHub actions and does **NOT** involve any manual intervention, so you can be assured that the binaries are built from the source code in the repository.
:::

We recommend first getting your system up and running with a `pkg` installation, and then replacing the binary with the latest release from GitHub if you want to stay on the bleeding edge. This is because the `pkg` version may lag behind the latest nightly release, and you may want to take advantage of new features or bug fixes (which we do support and recommend).

Before replacing the packaged binary, lock the Sylve package:

```bash
pkg lock -y sylve
```

The package database still considers `/usr/local/sbin/sylve` part of the installed Sylve package. Locking it prevents a later `pkg upgrade` from silently replacing your GitHub release with the repository version. Other system packages can continue to update normally.

You can visit the [releases page](https://github.com/AlchemillaHQ/Sylve/releases) and download the latest release for your architecture. Once downloaded, you can move the `sylve` binary to a location in your `PATH`, such as `/usr/local/bin`. The below commands will do this for you:

```bash
# Replace amd64 with arm64 if you're on an ARM64 system
fetch https://github.com/AlchemillaHQ/Sylve/releases/download/tip/sylve-amd64 -o sylve
chmod +x sylve
mv sylve /usr/local/sbin/
```

Should get you the absolute latest release, but if you want to get a specific version, just replace `tip` with the version tag you want to install for instance `v0.3.0`.

Keep the package locked while managing the binary from GitHub Releases. To return to the FreeBSD package version, unlock and reinstall it explicitly:

```bash
pkg unlock -y sylve
pkg install -f sylve
```

### Building from Source

Building Sylve is actually insanely simple. You obviously need the `Go` toolchain and `Node.js` installed on your system, but other than that you can just clone the repository and run the build command. If you don't have Go or Node.js installed, you can install them via `pkg`:

```bash
pkg install go node npm git-lite
```

Once that's done, you can clone the repository, navigate to the project directory, and run the build command:

```bash
git clone https://github.com/AlchemillaHQ/Sylve.git
cd Sylve
make
```

That should build both the backend and frontend, and place the `sylve` binary in the `bin/` directory. You can then move it to a location in your `PATH`:

```bash
mv bin/sylve /usr/local/sbin/
```

### Setting up Sylve

:::note
This section is primarily a **configuration reference for manual installations** from GitHub Releases or source. If you installed Sylve with `pkg install sylve`, the package provides the service integration and expected filesystem layout; you only need to review the configuration and enable the service.
:::

#### Configuration file

Sylve reads its runtime configuration from `/usr/local/etc/sylve/config.json`. Start with the following production-oriented example and replace the administrator password before the first launch:

```json
{
  "environment": "production",
  "proxyToVite": false,
  "profile": false,
  "ip": "0.0.0.0",
  "port": 8181,
  "httpPort": 8182,
  "logLevel": 3,
  "dataPath": "/var/db/sylve",
  "auth": {
    "enablePAM": false
  },
  "admin": {
    "email": "admin@sylve.local",
    "password": "replace-this-with-something-strong",
    "forcePasswordReset": false
  },
  "raft": {
    "reset": false
  },
  "btt": {
    "rpc": {
      "enabled": false,
      "address": "127.0.0.1",
      "port": 6890
    },
    "dht": {
      "enabled": true,
      "port": 7246
    }
  },
  "jails": {
    "disableDevFS": false
  },
  "zfs": {
    "tune": true
  },
  "uploads": {
    "maxFileBytes": 68719476736,
    "maxConcurrentTransfers": 2
  },
  "trustedProxies": []
}
```

#### Configuration reference

<ConfigurationReference />

Create the configuration directory and place the completed file there:

```bash
mkdir -p /usr/local/etc/sylve
mv config.json /usr/local/etc/sylve/
```

Sylve creates `dataPath` and its required subdirectories automatically. Place it on storage with enough capacity for databases, Raft state, uploads, ISO images, base archives, and other downloads.

#### Service integration

The `pkg` and ports installations provide the rc.d service automatically. For manual GitHub Release or source installations, use the maintained [FreeBSD ports rc.d template](https://github.com/freebsd/freebsd-ports/blob/main/sysutils/sylve/files/sylve.in) as the reference implementation instead of copying a script from this guide. Ports placeholders such as `%%PREFIX%%` and `%%ETCDIR%%` are substituted during packaging and must resolve to the paths used by your manual installation.

Sylve loads its required kernel modules during operational startup. If you enable Jails while RACCT is disabled, Sylve adds `kern.racct.enable=1` to `/boot/loader.conf`; reboot once after that automatic change so the boot-time setting can take effect.

Once the service script and configuration are in place, enable Sylve at boot:

```bash
sysrc sylve_enable=YES
```

Start it immediately unless you still need to reboot for loader settings:

```bash
service sylve start
```

Open `https://<your-server-ip>:8181` and sign in with the administrator credentials from `config.json`.

### Default Network Ports

<NetworkPortsTable />