freedive/README.md

# Freedive

Dive into FreeBSD

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.

### Develop

Clone the repository:

- `git clone https://brew.bsd.cafe/hiway/freedive.git`
- `cd freedive`

Install dependencies:

- `pkg install -U -y inotify-tools doas`

Setup your own account to run commands as root without password:

- `echo "permit nopass <USERNAME> as root" >> /usr/local/etc/doas.conf`

Start Freedive:

  * Run `mix setup` to install and setup dependencies
  * Start Freedive with `mix phx.server` or inside IEx with `iex -S mix phx.server`

Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.

> Registering accounts via browser is enabled in dev envronment.

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.


### Deploy

Create FreeBSD package:

- `mix package`

Copy package to target machine:

- `scp freedive-0.1.0.pkg hostname:`

SSH to the tagret machine, 
use `doas -S` (or `sudo -s`) if required 
to gain admin privileges and then run:

- `pkg install -U -y freedive-0.1.0.pkg`

Configure Freedive

- `$EDITOR /usr/local/etc/freedive/freedive.env`

Set preferences in freedive.env

- `HOST="hostname"`
- `BIND="ip-to-bind"`
- `PORT=3443`

Ensure that the host is set to whatever hostname you'll use
to access the service from browser.
For example, if you bind to the Tailscale/Wireguard IP,
use the hostname that'll point 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.