hubl/README.md
2020-12-14 14:43:48 +01:00

360 lines
9.2 KiB
Markdown

<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