378 lines
10 KiB
Markdown
378 lines
10 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
|
|
```
|
|
|
|
### Theme checker
|
|
|
|
The [Hubl theme manager](https://cdn.startinblox.com/hubl/theme/) is very handy for customer to easily customize the main colors they want to use.
|
|
But developers should verify that their development use those colors to fit the customer wishes. The theme checker make this task easier :
|
|
just add `"themeChecker": true` to the config.json to display the color picker tool in the header bar. Changing the color will set them on the
|
|
whole app so that you can verify that your development take them into account correctly.
|
|
|
|
## 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": {
|
|
"communities": "http://server.url/open-communities/",
|
|
"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.*.communities` is the API endpoints for Open Communities on your djangoldp server. (djangoldp-community)
|
|
* `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.
|
|
|
|
If you set `allow_self_registration` on your community, it'll disable the auto-login feature of Hubl and allow your users to self register on your application.
|
|
|
|
### 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/"
|
|
}
|
|
}
|
|
```
|
|
|
|
You can get only future events by using
|
|
```json
|
|
"get": {
|
|
"events":"http://server.url/events/future/",
|
|
}
|
|
```
|
|
|
|
### 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
|