223 lines
6.1 KiB
Markdown
223 lines
6.1 KiB
Markdown
# Freedive
|
|
Dive into FreeBSD with `Freedive`!
|
|
|
|
Freedive emerges as an innovative standalone tool for FreeBSD,
|
|
offering a graphical user interface (GUI) that revolutionizes
|
|
the way systems are managed,
|
|
enabling both newcomers and experienced users
|
|
to administer their FreeBSD installations with ease.
|
|
|
|
This GUI, accessible through a mobile-friendly web interface,
|
|
democratizes the use of FreeBSD by allowing beginners
|
|
to engage with the operating system
|
|
without the need to delve into the complexities of the command-line shell.
|
|
Designed with responsiveness in mind,
|
|
Freedive's interface adapts seamlessly to various screen sizes,
|
|
ensuring that system administrators can perform essential tasks
|
|
from virtually any device, be it a smartphone, tablet, or desktop.
|
|
|
|
The intuitive design of Freedive's web interface lowers
|
|
the barrier to entry for managing FreeBSD systems,
|
|
making it more approachable for users
|
|
who may not be familiar with Unix-like environments.
|
|
By providing a full spectrum of
|
|
system management capabilities through its GUI,
|
|
Freedive empowers users to perform tasks
|
|
ranging from user account management to service configuration,
|
|
all without writing a single line of shell code.
|
|
|
|
Freedive stands as a testament to the versatility of FreeBSD,
|
|
extending its appeal beyond the traditional tech-savvy audience
|
|
to a broader range of users who can now leverage
|
|
the power of FreeBSD
|
|
with the convenience of a modern web-based interface.
|
|
|
|
## Features
|
|
Made by and for users of FreeBSD as their:
|
|
|
|
- Home lab
|
|
- Tailscale / Wireguard VPN
|
|
- Manage PF rules (firewall)
|
|
- Manage Jails via Bastille
|
|
- Network attached storage
|
|
- Samba shares
|
|
- Backups via Restic
|
|
- Manage ZFS datasets, snapshots and backups
|
|
- Personal/ public web server
|
|
- Manage domains and TLS certificates
|
|
- Host static sites
|
|
- Reverse proxy to any jail:port
|
|
|
|
Freedive works in immediate mode:
|
|
|
|
- Queries host, caches some results in memory
|
|
- No database except for acounts
|
|
- Executes commands when actions taken in UI
|
|
|
|
> Status: planning/alpha.
|
|
You can use Freedive to manage system services.
|
|
Package management coming soon.
|
|
Other features will be developed as time/help is available.
|
|
This is currently a hobby project and makes no guarantees
|
|
about what features will be implemented and when.
|
|
|
|
## Screenshots
|
|
|
|
|
|
|
|
|
|
|
|
## Quick Steps
|
|
|
|
### Get pre-built package
|
|
|
|
Try Freedive on FreeBSD 14.0-RELEASE and newer:
|
|
* amd64: [freedive-0.1.0.pkg](https://cdn.gyptazy.ch/files/amd64/freebsd/freedive/freedive-0.1.0.pkg) [hosted at gyptazy.ch]
|
|
* arm64: [freedive-0.1.0_arm64.pkg](https://cdn.gyptazy.ch/files/arm64/freebsd/freedive/freedive-0.1.0_arm64.pkg) [hosted at gyptazy.ch]
|
|
|
|
|
|
### Install package
|
|
|
|
Another solution directly leads into using the built package. This can be installed by running:
|
|
|
|
```
|
|
pkg install -U -y freedive-0.1.0.pkg
|
|
```
|
|
|
|
Next, edit the configuration at `/usr/local/etc/freedive/freedive.env`
|
|
and define following settings:
|
|
|
|
```
|
|
HOST="hostname"
|
|
BIND="ip-to-bind"
|
|
PORT=3443
|
|
```
|
|
|
|
Ensure that the host is set to the hostname you'll use
|
|
to access the service from browser.
|
|
For example, if you bind to the Tailscale/Wireguard IP,
|
|
use the hostname that points to this IP.
|
|
Port can be anything suitable in your environmet
|
|
that's open and accessible from your mobile/laptop.
|
|
|
|
Enable Freedive
|
|
|
|
- `service freedive enable`
|
|
|
|
Initialize Freedive
|
|
|
|
- `service freedive init`
|
|
|
|
Create an account for yourself
|
|
|
|
- `service freedive account_create`
|
|
|
|
> Accounts have full access to every part of the system via Freedive,
|
|
do NOT create accounts for people you do not trust to have root access
|
|
on this machine.
|
|
|
|
Start Freedive
|
|
|
|
- `service freedive start`
|
|
|
|
Check logs
|
|
|
|
- `tail -f /var/log/freedive/freedive.log`
|
|
|
|
|
|
Visit `https://hostname:port` from your browser and
|
|
log in with the account created above.
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### Requirements
|
|
|
|
If you have `ports` active on your system, this step can be skipped.
|
|
If you have not installed `ports` (the `/usr/ports` directory is missing)
|
|
then you need to copy a file which is referenced and used
|
|
by Freedive when building its own package.
|
|
|
|
Run the following commands:
|
|
|
|
```
|
|
mkdir -p /usr/ports/Keywords/
|
|
curl -O /usr/ports/Keywords/ https://raw.githubusercontent.com/freebsd/freebsd-ports/main/Keywords/sample.ucl
|
|
```
|
|
|
|
You also want to setup your own doas account (passwordless) by running:
|
|
|
|
```
|
|
echo "permit nopass <USERNAME> as root" >> /usr/local/etc/doas.conf
|
|
```
|
|
|
|
Freedive will only function as expected if `doas` is installed
|
|
and configured to allow the user running the server
|
|
to execute commands as root without requiring a password.
|
|
|
|
|
|
### Development Environment
|
|
|
|
Install build tools and depedencies
|
|
```
|
|
pkg install -y ca_root_nss doas elixir gcc git gmake inotify-tools
|
|
```
|
|
|
|
Get code
|
|
```
|
|
git clone https://brew.bsd.cafe/hiway/freedive.git
|
|
cd freedive
|
|
```
|
|
|
|
Setup dev environment
|
|
```
|
|
mix setup
|
|
```
|
|
|
|
> It is safe to ignore warning about `mix_freebsd_pkg` requiring Elixir 1.6, it will go away
|
|
> when Elixir 1.6 becomes available in quarterly packages.
|
|
|
|
|
|
### Development Server
|
|
|
|
Freedive dev server can be started by running `mix` or inside `IEx` by executing:
|
|
|
|
```
|
|
mix phx.server
|
|
|
|
# or
|
|
|
|
iex -S mix phx.server
|
|
```
|
|
|
|
Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
|
|
|
|
> Note:
|
|
> Registering accounts via browser is enabled in dev environment.
|
|
|
|
Visit [/users/register](http://localhost:4000/users/register) to create an account.
|
|
Then visit [/dev/mailbox](http://localhost:4000/dev/mailbox) to confirm the account.
|
|
|
|
Now, you can ue these credentials to log in and explore Freedive.
|
|
|
|
|
|
### Packaging
|
|
|
|
Create and build a distributable `.pkg` file that can be installed on target machines.
|
|
|
|
Run the following command in `freedive` directory:
|
|
|
|
```
|
|
mix package
|
|
```
|
|
|
|
This creates the file `freedive-0.x.x.pkg` within your project directory.
|
|
|
|
|
|
## Chat / Community
|
|
|
|
The chat and community are on Matrix hosted at the BSD.cafe:
|
|
* #BSDCafe:bsd.cafe
|
|
|
|
You can join by clicking: https://matrix.to/#/#BSDCafe:bsd.cafe
|