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

Reorganize and update Readme for clarity

Browse source
This commit is contained in:
Harshad Sharma 2024-06-21 02:05:14 +05:30
parent 2c92fde5a4
commit cc497c4803
1 changed files with 101 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

169
README.md
View file

@ -68,80 +68,24 @@ Freedive works in immediate mode:
## Quick Steps ## 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]
### Build & Deploy ### Get pre-built package
#### 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.
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: 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]
mkdir -p /usr/local/etc/pkg/repos * 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]
echo "FreeBSD: { url: \"pkg+http://pkg.freebsd.org/\${ABI}/latest\" }" > /usr/local/etc/pkg/repos/FreeBSD.conf
pkg -y upgrade -f
```
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
```
You may also want to setup your own doas account (passwordless) by running:
```
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
```
#### 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
```
#### 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) ### Install package
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.
### Usage (pkg)
Another solution directly leads into using the built package. This can be installed by running: Another solution directly leads into using the built package. This can be installed by running:
``` ```
pkg install -U -y freedive-0.1.0.pkg pkg install -U -y freedive-0.1.0.pkg
``` ```
Afterwards, the configuration should be adjusted in `/usr/local/etc/freedive/freedive.env` where the following settings should be defined: Next, edit the configuration at `/usr/local/etc/freedive/freedive.env`
and define following settings:
``` ```
HOST="hostname" HOST="hostname"
@ -149,10 +93,10 @@ BIND="ip-to-bind"
PORT=3443 PORT=3443
``` ```
Ensure that the host is set to whatever hostname you'll use Ensure that the host is set to the hostname you'll use
to access the service from browser. to access the service from browser.
For example, if you bind to the Tailscale/Wireguard IP, For example, if you bind to the Tailscale/Wireguard IP,
use the hostname that'll point to this IP. use the hostname that points to this IP.
Port can be anything suitable in your environmet Port can be anything suitable in your environmet
that's open and accessible from your mobile/laptop. that's open and accessible from your mobile/laptop.
@ -180,11 +124,100 @@ 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.
---
## 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 <USERNAME> 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 ## Chat / Community
The chat and community is based in the Matrix channel hosted at the BSD.cafe:
The chat and community are on Matrix hosted at the BSD.cafe:
* #BSDCafe:bsd.cafe * #BSDCafe:bsd.cafe
You can also join by simply clicking the following link: https://matrix.to/#/#BSDCafe:bsd.cafe You can join by clicking: https://matrix.to/#/#BSDCafe:bsd.cafe