From c6f8ce1029b61fcaa6edd3a90c333255e26f1789 Mon Sep 17 00:00:00 2001 From: Florian Paul Azim Hoberg Date: Thu, 23 May 2024 16:59:47 +0200 Subject: [PATCH] feature(doc): Update README.md file for requirement instructions --- README.md | 115 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 73 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index cc77b2a..a74ca4a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # 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: - Home lab @@ -30,70 +32,93 @@ Freedive works in immediate mode: This is currently a hobby project and makes no guarantees about what features will be implemented and when. -### Screenshots - +## 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) -### 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` -- `cd freedive` +### Build & Deploy +#### 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 as root" >> /usr/local/etc/doas.conf +``` -- `echo "permit nopass 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 - * Start Freedive with `mix phx.server` or inside IEx with `iex -S mix phx.server` +#### Packaging +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. > 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. +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` - -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` +``` +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. @@ -127,4 +152,10 @@ Check logs - `tail -f /var/log/freedive/freedive.log` Visit https://hostname:port from your browser and -log in with the account created above. \ No newline at end of file +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 \ No newline at end of file