hubl/README.md

<h1 align="center">
  <br>
  <a href="http://hubl.world"><img src="https://cdn.startinblox.com/logos/hubl-logo.png" alt="Hubl" width="200"></a>
  <br>
</h1>

<h4 align="center">A magic tool that allows the Freelance Network to thrive in a decentralized way, built on top of <a href="https://startinblox.com/" target="_blank">Startin'blox</a>.</h4>

<hr>

<p align="center">
    <a href="https://git.startinblox.com/management/product-owners-sync/issues/"><img alt="create a feature request" src="https://img.shields.io/badge/%2B-feature%20request-blue" /></a>
    <a href="https://git.startinblox.com/applications/hubl/issues/"><img alt="create an issue" src="https://img.shields.io/badge/%2B-issue-orange" /></a>
    <a href="https://git.startinblox.com/applications/hubl/commits/master"><img alt="pipeline status" src="https://git.startinblox.com/applications/hubl/badges/master/pipeline.svg" /></a>
</p>

## Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

### Prerequisites

To install Hubl, you'll need:

* A [Hubl Server](https://git.startinblox.com/djangoldp-packages/server-manager/) (djangoldp>1)
* A [Prosody Server](https://prosody.im/) (with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/))
* A SMTP Server (optional)
* NodeJS on your machine

Before diving in you have to check your Hubl Server supports the following LDP packages:

* djangoldp_account
* djangoldp_community
* djangoldp_notification
* djangoldp_profile
* djangoldp_skill
* djangoldp_uploader
* oidc_provider: django-webidoidc-provider

Those packages are given with the last stable version tested.

Refer to the [documentation to install a Hubl Server](https://docs.startinblox.com/import_documentation/install-sib-server.html) with this configuration.

## Build the application

In order to find your server(s) the client application needs to be assembled with the proper configuration.

Get the code of the Hubl on your machine:

```bash
git clone ...
cd hubl
npm install
```

Then create a `config.json` based on your needs, see Mandatory and Optional Modules on this page. For convienence a `config.sample.json` exists in the source.

Then build your new Hubl:

```bash
npm run build
```

The application bundle is in the `dist` folder, ready to be deployed everywhere as a static file.

## Developpers

Serve, watch files & rebuild on change with this command:

```bash
npm run watch
```

### Multiple config.json

You can have as many `config.*.json` as you need.

Watch on a custom config file:

```bash
CONFIG_PATH='config.customName.json' npm run watch
```

Build with a custom config file:

```bash
CONFIG_PATH='config.customName.json' npm run build
```

## Mandatory modules

By default, a Hubl includes only individual chat modules.

On Server: `djangoldp_account`, `djangoldp_profile`, `djangoldp_notification`, `djangoldp_skill`, `djangoldp_upload`, `oidc_provider` packages

On `config.json`:

```json
{
  "xmppWebsocket": "wss://jabber.happy-dev.fr/xmpp-websocket",
  "clientName": "My local Hubl",
  "clientLogo": "/images/logo.webp",
  "authority": "http://localhost:8000/",
  "endpoints": {
    "get": {
      "skills": "http://server.url/skills/",
      "users": "http://server.url/users/"
    },
    "post": {
      "uploads": "http://server.url/upload/"
    }
  }
}
```

Where:

* `clientName` is the name of your Hubl
* `clientLogo` is an URL to an image file
* `xmppWebsocket` is your [Prosody](https://prosody.im/) with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/) configured on.
* `authority` is the OpenID Provider. Usually, if you use `djangoldp-account` it's the same as your djangoldp server.
* `endpoints.*.users` is the API endpoints for Users on your djangoldp server. (djangoldp-account)
* `endpoints.*.skills` is the API endpoints for Skills on your djangoldp server. (djangoldp-skill)
* `endpoints.*.uploads` is the API endpoints for Uploads on your djangoldp server. (djangoldp-upload)

### Communities

Communities are mandatory to have an Hubl. If you're upgrading an existion Hubl, you can assign all your local users to a community this way:

```bash
./manage.py create_community --name="My community"
```

Don't forget to set some users as admin from the Django Admin if you want to allow them to create new users from app.

### Optional personalisation

On `config.json`:

```json
  "clientFavicon": "/images/favicon.webp",
  "clientLogoHeight": "32px",
  "clientCSS": "/path/to/custom.css",
  "authorityName": "djangoldp-server-name"
```

Where:

* `clientFavicon` is an URL to a distant favicon
* `clientLogoHeight` allow a quick fix to manage different height logos
* `clientCSS` is an URL to a distant CSS that'll be the last one loaded by the Hubl
* `authorityName` is a visual name of your OpenID Provider

## Optional modules

### Analytics

Hubl support Google or Matomo as analytics trackers. To use them, add to your `config.json`:

```json
  "analytics": [
    {
      "type": "matomo", //Or "google"
      "url": "https://my-personal.matomo.cloud/",
      "id": "1"
    }
  ]
```

### Circles

Circles are a public group chat. To activate them, you need:

On Server: `djangoldp_circle` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "circle": "http://server.url/circles/"
    },
    "post": {
      "circle": "http://server.url/circles/"
    },
  }
```

### Dashboard

Dashboard includes card generation from HTML. To activate them, you need:

On Server: `djangoldp_dashboard` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "dashboard": "http://server.url/dashboard/"
    }
  }
```

A [sample fixture](https://git.startinblox.com/djangoldp-packages/djangoldp-dashboard/blob/master/djangoldp_dashboard/fixtures/sample.json) can be loaded with `./manage.py loaddata sample`.

### Job Offers

Job Offers includes a job board with conversation. To activate them, you need:

On Server: `djangoldp_joboffer`, `djangoldp_skill`, `djangoldp_upload`, `djangoldp_conversation` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "joboffers": "http://server.url/job-offers/"
    }
  }
```

### Project

Project are a private group chat including Customer and Business Provider management. To activate them, you need:

On Server: `djangoldp_project` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "projects": "http://server.url/projects/"
    },
    "post": {
      "projects": "http://server.url/projects/"
    }
  }
```

### Users Directory

Directory includes a listing of each users of your app and editable individual profile. To activate them, you need:

On Server: `djangoldp_skill`, `djangoldp_upload` packages

On `config.json`:

```json
  "publicDirectory": true
```

## Optional community modules

### Events

The events module includes a listing of upcoming events and the capability to create new ones. 
This module will also work inside the circles.
To activate it, you need:

On Server: `djangoldp_event`, `djangoldp_upload` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "events":"http://server.url/events/",
      "typeevents":"http://server.url/typeevents/"
    },
    "post": {
      "events":"http://server.url/events/",
      "typeevents":"http://server.url/typeevents/"
    }
  }
```

### Resources

The resources module includes a listing of indexed resources and the capability to index new ones. 
This module will also work inside the circles.
To activate it, you need:

On Server: `djangoldp_resource`, `djangoldp_upload`, `djangoldp_conversation` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "resources":"http://server.url/resources/",
      "resourceskeywords":"http://server.url/keywords/",
      "resourcestypes":"http://server.url/types/"
    },
    "post": {
      "resources":"http://server.url/resources/",
      "resourceskeywords":"http://server.url/keywords/",
      "resourcestypes":"http://server.url/types/"
    }
  }
```

### Polls

The polls module allows user to create polls related (or not) to circles. To activate it, you need:

On Server: `djangoldp_polls`, `djangoldp_upload`, `djangoldp_conversation` packages

On `config.json`:

```json
  "endpoints": {
    "get": {
      "polls":"http://server.url/polls/"
    },
    "post": {
      "polls":"http://server.url/polls/"
    }
  }
```

## Use with docker

### Multi services

Run with a local binding on localhost:

```bash
docker-compose build
docker-compose up -d client server
```

Use in CI context:

```bash
docker-compose -f docker-compose.yml build
docker-compose -f docker-compose.yml up -d client server
docker-compose -f docker-compose.yml run --rm e2e
```

Build and push the server to registry:

```bash
docker build -f docker/djangoldp.docker --build-arg serve="http://localhost:8000" -t registry.startinblox.com/applications/hubl/server:0.1 .
docker push registry.startinblox.com/applications/hubl/server:0.1
```

Note: within a Kubernetes pod all services are bound to `localhost`.

## Troubleshooting

### Circles or Projects are missing the @user list

Did you properly created subscriptions on your DjangoLDP's server? You can quickly create them with `./manage.py create_subscriptions`

## Built With

* [Sib-Core](https://git.startinblox.com/framework/sib-core/) - A SOLID-Compliant framework