# 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 ![Services](https://brew.bsd.cafe/attachments/92821625-db44-41ce-8806-6c361f2160fb) ![Service details](https://brew.bsd.cafe/attachments/d9f27295-c537-42f8-ad08-8c8b3d63393f) ![Service commands](https://brew.bsd.cafe/attachments/6cafe055-68fd-41d9-90b7-812146d19e30) ## 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 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