Reorganize and update Readme for clarity
This commit is contained in:
parent
2c92fde5a4
commit
cc497c4803
1 changed files with 101 additions and 68 deletions
169
README.md
169
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 <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.
|
||||
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 <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
|
||||
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
|
||||
You can join by clicking: https://matrix.to/#/#BSDCafe:bsd.cafe
|
||||
|
|
|
|||
Loading…
Reference in a new issue