forked from hiway/freedive
feature(doc): Update README.md file for requirement instructions
This commit is contained in:
parent
3bbf8a8172
commit
c6f8ce1029
1 changed files with 73 additions and 42 deletions
113
README.md
113
README.md
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
@ -128,3 +153,9 @@ Check logs
|
||||||
|
|
||||||
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
|
||||||
Loading…
Reference in a new issue