hiway/freedive
1
2
Fork 1
Code Issues 8 Pull requests Projects Releases Packages Wiki Activity Actions

feature(doc): Update README.md file for requirement instructions

Browse source
This commit is contained in:
Florian Paul Azim Hoberg 2024-05-23 16:59:47 +02:00
parent 3bbf8a8172
commit c6f8ce1029
1 changed files with 73 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
README.md
View file

@ -1,7 +1,9 @@
# Freedive # Freedive
Dive into FreeBSD with `Freedive`!
Dive into FreeBSD 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 entry barrier 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: Made by and for users of FreeBSD as their:
- Home lab - Home lab
@ -30,70 +32,93 @@ Freedive works in immediate mode:
This is currently a hobby project and makes no guarantees This is currently a hobby project and makes no guarantees
about what features will be implemented and when. about what features will be implemented and when.
### Screenshots ## Screenshots
![Services](https://brew.bsd.cafe/attachments/92821625-db44-41ce-8806-6c361f2160fb) ![Services](https://brew.bsd.cafe/attachments/92821625-db44-41ce-8806-6c361f2160fb)
![Service details](https://brew.bsd.cafe/attachments/d9f27295-c537-42f8-ad08-8c8b3d63393f) ![Service details](https://brew.bsd.cafe/attachments/d9f27295-c537-42f8-ad08-8c8b3d63393f)
![Service commands](https://brew.bsd.cafe/attachments/6cafe055-68fd-41d9-90b7-812146d19e30) ![Service commands](https://brew.bsd.cafe/attachments/6cafe055-68fd-41d9-90b7-812146d19e30)
### Develop
Clone the repository: ## Quick Steps
### Binaries
For a quick test you can just use the generated FreeBSD pkgs to try Freedive:
* [freedive-0.1.0.pkg](https://cdn.gyptazy.ch/files/amd64/freebsd/freedive/freedive-0.1.0.pkg) [hosted at gyptazy.ch]
- `git clone https://brew.bsd.cafe/hiway/freedive.git` ### Build & Deploy
- `cd freedive` #### Requirements
Building Freedive requires some additional packages like gmake, gcc and especially elixir (>= 1.16.0). This also requires you to switch to the latest ports/pkgs branch instead of the quarterly.
Install dependencies: This is not needed when you are already using the `latest` repository. However, switching to the latest ports/pkgs branch can be easily done with the following steps:
```
mkdir -p /usr/local/etc/pkg/repos
echo "FreeBSD: { url: \"pkg+http://pkg.freebsd.org/\${ABI}/latest\" }" > /usr/local/etc/pkg/repos/FreeBSD.conf
pkg -y upgrade -f
```
- `pkg install -U -y inotify-tools doas` If you are fully running on pkg instead of ports you need to copy a file which is referenced and used by Freedive. If you have
ports active on your system, this step can be skipped - if not, simply 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
```
Setup your own account to run commands as root without password: You may also want to setup your own doas account (passwordless) by running:
```
echo "permit nopass <USERNAME> as root" >> /usr/local/etc/doas.conf
```
- `echo "permit nopass <USERNAME> as root" >> /usr/local/etc/doas.conf` Within the last step, the needed dependencies can be installed from the pkg repository:
```
pkg install git inotify-tools gmake elixir gcc doas
```
Start Freedive: #### Building
Freedive can be simply build by running the following commands:
```
pkg install -y git inotify-tools gmake elixir gcc doas
git clone https://brew.bsd.cafe/hiway/freedive.git
mix setup
```
* Run `mix setup` to install and setup dependencies #### Packaging
* Start Freedive with `mix phx.server` or inside IEx with `iex -S mix phx.server` If you also want to create and build a distributable `.pkg` file, simply run the following command afterwards:
```
mix package
```
This creates you the file `freedive-0.1.0.pkg` within your build directory.
### Usage (compile)
After building, you can directly start Freedive. Freedive 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. Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
> Registering accounts via browser is enabled in dev envronment. > Registering accounts via browser is enabled in dev envronment.
Visit [/users/register](http://localhost:4000/users/register) to create an account. 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. 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. Now, you can ue these credentials to log in and explore Freedive.
### Usage (pkg)
Another solution directly leads into using the built package. This can be installed by running:
### Deploy ```
pkg install -U -y freedive-0.1.0.pkg
```
Create FreeBSD package: Afterwards, the configuration should be adjusted in `/usr/local/etc/freedive/freedive.env` where the following settings should be defined:
- `mix package` ```
HOST="hostname"
Copy package to target machine: BIND="ip-to-bind"
PORT=3443
- `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 Ensure that the host is set to whatever hostname you'll use
to access the service from browser. to access the service from browser.
@ -127,4 +152,10 @@ Check logs
- `tail -f /var/log/freedive/freedive.log` - `tail -f /var/log/freedive/freedive.log`
Visit https://hostname:port from your browser and Visit https://hostname:port from your browser and
log in with the account created above. log in with the account created above.
## Chat / Community
The chat and community is based in the Matrix channel hosted at the BSD.cafe:
* #BSDCafe:bsd.cafe
You can also join by simply clicking the following link: https://matrix.to/#/#BSDCafe:bsd.cafe