From cc497c480381f27afdffb9b491a3afe3a9cca23f Mon Sep 17 00:00:00 2001 From: Harshad Sharma Date: Fri, 21 Jun 2024 02:05:14 +0530 Subject: [PATCH] Reorganize and update Readme for clarity --- README.md | 169 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 101 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index fbd362d..b87d128 100644 --- a/README.md +++ b/README.md @@ -68,80 +68,24 @@ Freedive works in immediate mode: ## 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 -#### 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. +### Get pre-built package -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 -``` - -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 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. +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] + * 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] -### Usage (compile) -After building, you can directly start Freedive. Freedive can be started by running `mix` or inside `IEx` by executing: +### Install package -``` -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: ``` 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" @@ -149,10 +93,10 @@ 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 the 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. +use the hostname that points to this IP. Port can be anything suitable in your environmet that's open and accessible from your mobile/laptop. @@ -180,11 +124,100 @@ Check logs - `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. +--- + +## 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 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 -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 -You can also join by simply clicking the following link: https://matrix.to/#/#BSDCafe:bsd.cafe \ No newline at end of file +You can join by clicking: https://matrix.to/#/#BSDCafe:bsd.cafe