725 lines
18 KiB
Markdown
725 lines
18 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 orchestrator 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>2)
|
|
* A [Prosody Server](https://prosody.im/) (with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/)) (optional)
|
|
* 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_uploader
|
|
* an oidc_provider (eg: [django-webidoidc-provider](https://git.startinblox.com/djangoldp-packages/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-djangoldp-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
|
|
```
|
|
|
|
Notice that you may have to restart the watcher for the config.json and for locales files.
|
|
|
|
### 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_upload`, `django-webidoidc-provider` packages
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
{
|
|
"client": {
|
|
"name": "Localhost",
|
|
"logo": "/images/logo.webp"
|
|
},
|
|
"components": []
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `client.name` is the name of your Hubl
|
|
* `client.logo` is an URL to an image file
|
|
* `components` is your modules declaration registry
|
|
|
|
### Optional personalisation
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
{
|
|
"client": {
|
|
"favicon": "/images/favicon.webp",
|
|
"css": "/path/to/custom.css",
|
|
"i18n": {
|
|
"lang": "fr",
|
|
"force": "false"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `client.favicon` is an URL to a distant favicon
|
|
* `client.css` is an URL to a distant CSS that'll be the last one loaded by the Hubl
|
|
* `client.i18n.lang` is the fallback langage in case the visitor's browser one does not contain the string
|
|
* `client.i18n.force` allows to ignore the visitor's browser langage and force the `client.i18n.lang` one
|
|
|
|
### Allow to login to your application
|
|
|
|
Most of other modules will need to have an user logged in, if you want to use communities, then scroll back to the User Registration module, else you'll need to activate the Auto Login module:
|
|
|
|
```json
|
|
{
|
|
"type": "autoLogin",
|
|
"parameters": {
|
|
"authority": "http://server.url/"
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `authority` is the OpenID Provider. Usually, if you use `djangoldp_account` it's the same as your djangoldp server.
|
|
|
|
## Optional modules
|
|
|
|
### Adding modules
|
|
|
|
You can append any module listed bellow to your `components` entry on your `config.json`
|
|
|
|
Eg. to add the `notification` module:
|
|
|
|
```json
|
|
{
|
|
"components": [
|
|
{
|
|
"type": "notification",
|
|
"route": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### About
|
|
|
|
About is a short page about the technology behind Hubl.
|
|
|
|
To activate about on Hubl, add this module declaration your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "about",
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
### Administration
|
|
|
|
Administration is a minimal modulable admin module for all other ones.
|
|
|
|
To activate administration on Hubl, add this module declaration your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "admin",
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
### Analytics
|
|
|
|
Hubl support Google or Matomo as analytics trackers. To use them, add to your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "analytics",
|
|
"parameters": {
|
|
"type": "matomo",
|
|
"url": "https://my-personal.matomo.cloud/",
|
|
"id": "1"
|
|
},
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
### Circles
|
|
|
|
Circles define group of users that can chat & share documents togethers.
|
|
|
|
Community module is mandatory.
|
|
|
|
To activate them, you need:
|
|
|
|
On Server: `djangoldp_circle`, `djangoldp_communities`, `djangoldp_notifications` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "circles",
|
|
"endpoints": {
|
|
"get": "http://server.url/circles/",
|
|
"post": "http://server.url/circles/",
|
|
"owners": "http://server.url/users/",
|
|
"users": "http://server.url/users/",
|
|
"xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `owners`: is your users container which contains valid owners
|
|
* `users`: is your users container
|
|
* `xmpp` is your [Prosody](https://prosody.im/) with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/) configured on.
|
|
|
|
#### Circles extensions
|
|
|
|
You can extend circles with other components, the same way you would add them to your modules.
|
|
|
|
Actually it support: Events, Resources & Polls.
|
|
|
|
Eg.:
|
|
|
|
```json
|
|
{
|
|
"type": "circles",
|
|
"endpoints": {
|
|
"get": "http://server.url/circles/",
|
|
"post": "http://server.url/circles/",
|
|
"owners": "http://server.url/users/",
|
|
"users": "http://server.url/users/",
|
|
"xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
|
|
},
|
|
"extensions": [
|
|
{
|
|
"type": "events",
|
|
"endpoints": {
|
|
"get": "http://server.url/events/",
|
|
"post": "http://server.url/events/",
|
|
"typeevents": "http://server.url/typeevents/",
|
|
"postTypeevents": "http://server.url/typeevents/",
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Communities
|
|
|
|
Communities are an optional layer to add on an Hubl. They add a SOLID representation of one to many group of users on your data server.
|
|
|
|
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 of the community from the Django Admin if you want to allow them to create new users from app.
|
|
|
|
To activate community on Hubl, add this module declaration your `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "communities",
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
#### Activate the community directory
|
|
|
|
When you work with a federated application, you may want a directory for communities.
|
|
|
|
You can activate it by changing the route to anything else than false. Some endpoints will also get needed:
|
|
|
|
```json
|
|
{
|
|
"type": "communities",
|
|
"endpoints": {
|
|
"get": "http://server/communities/",
|
|
"addresses": "http://server/community-addresses/",
|
|
"uploads": "http://server/upload/"
|
|
},
|
|
"route": "communities"
|
|
}
|
|
```
|
|
|
|
### Dashboard
|
|
|
|
Dashboard includes card generation from HTML. To activate them, you need:
|
|
|
|
On Server: `djangoldp_dashboard` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "dashboard",
|
|
"endpoints": {
|
|
"get": "http://server.url/dashboards/"
|
|
},
|
|
"parameters": {
|
|
"target": "default"
|
|
}
|
|
}
|
|
```
|
|
|
|
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`.
|
|
|
|
You can have multiple dashboard module, see the [related documentation](https://git.startinblox.com/components/solid-dashboard#having-multiple-dashboard).
|
|
|
|
### Events
|
|
|
|
The events module includes a listing of upcoming events and the capability to create new ones.
|
|
To activate it, you need:
|
|
|
|
On Server: `djangoldp_event` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "events",
|
|
"endpoints": {
|
|
"get": "http://server.url/events/",
|
|
"post": "http://server.url/events/",
|
|
"typeevents": "http://server.url/typeevents/",
|
|
"postTypeevents": "http://server.url/typeevents/",
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
```
|
|
|
|
You can get only future events by using:
|
|
|
|
```json
|
|
"get": "http://server.url/events/future/",
|
|
```
|
|
|
|
### Internationalization
|
|
|
|
Each client can overwrite langs files with their own or even create custom langs.
|
|
|
|
#### Overwrite langs
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "lang",
|
|
"parameters": {
|
|
"name": "fr",
|
|
"file": "/path/to/fr.json"
|
|
},
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `parameters.name` allows to use custom client lang file.
|
|
* `parameters.file` is the path the the json lang file
|
|
|
|
#### Custom langs
|
|
|
|
Needs `client.i18n.force` to `true` and `client.i18n.lang` to the custom lang name.
|
|
|
|
Your custom JSON file **must** contain every keys, from the template and from every bloxes, prefixed by the blox namespace. See example on `src/locales/fr.json`.
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
"client": {
|
|
"i18n": {
|
|
"lang": "pirate",
|
|
"force": "true"
|
|
}
|
|
},
|
|
"components": [
|
|
{
|
|
"type": "i18n",
|
|
"parameters": {
|
|
"name": "pirate",
|
|
"file": "/path/to/yarr.json"
|
|
},
|
|
"route": false
|
|
}
|
|
]
|
|
```
|
|
|
|
Where:
|
|
|
|
* `parameters.name` allows to use custom client lang file.
|
|
* `parameters.file` is the path the the json lang file
|
|
|
|
Setting custom langs will not allow user to choose their own lang.
|
|
|
|
### Invoices
|
|
|
|
Invoices allow your Projects to manage invoices
|
|
|
|
Project is mandatory.
|
|
|
|
You'll need:
|
|
|
|
On Server: `djangoldp_invoice` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "projects",
|
|
"extensions": [
|
|
{
|
|
"type": "invoices",
|
|
"endpoints": {
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
|
|
### Job Offers
|
|
|
|
Job Offers includes a job board with conversation. To activate them
|
|
|
|
Community module is mandatory.
|
|
|
|
You'll need:
|
|
|
|
On Server: `djangoldp_joboffer`, `djangoldp_skill`, `djangoldp_upload`, `djangoldp_conversation` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "jobBoard",
|
|
"endpoints": {
|
|
"get": "http://server.url/job-offers/",
|
|
"post": "http://server.url/job-offers/",
|
|
"skills": "http://server.url/skills/"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Notifications
|
|
|
|
The notification module adds a bell with user's notification list and a badge on each menus with how much notifications are related to this resource. You'll need:
|
|
|
|
On Server: `djangoldp_notifications` packages
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "notification",
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
### One-to-one chat
|
|
|
|
One-to-one chat allow your users to chat together on a private channel.
|
|
|
|
Community & User Directory modules are mandatory.
|
|
|
|
You'll need:
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "chat",
|
|
"endpoints": {
|
|
"xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `xmpp` is your [Prosody](https://prosody.im/) with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/) configured on.
|
|
|
|
### Polls
|
|
|
|
The polls module allows user to create polls. To activate it, you need:
|
|
|
|
On Server: `djangoldp_polls`, `djangoldp_conversation` packages
|
|
|
|
On `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "polls",
|
|
"endpoints": {
|
|
"get": "http://server.url/polls/",
|
|
"post": "http://server.url/polls/",
|
|
"pollRangeTags": "http://server.url/tags/",
|
|
"pollRangeCircles": "http://server.url/circles/",
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Project
|
|
|
|
Project are a private group chat including Customer and Business Provider management.
|
|
|
|
Community module is mandatory.
|
|
|
|
To activate them, you need:
|
|
|
|
On Server: `djangoldp_project` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "projects",
|
|
"endpoints": {
|
|
"get": "http://server.url/projects/",
|
|
"post": "http://server.url/projects/",
|
|
"captains": "http://server.url/users/",
|
|
"xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `captains`: is your users container which contains valid captains
|
|
* `xmpp` is your [Prosody](https://prosody.im/) with [appropriate modules](https://git.startinblox.com/infra/prosody-modules/) configured on.
|
|
|
|
### Resources
|
|
|
|
The resources module includes a listing of indexed resources and the capability to index new ones.
|
|
To activate it, you need:
|
|
|
|
On Server: `djangoldp_resource`, `djangoldp_conversation` packages
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "resources",
|
|
"endpoints": {
|
|
"get": "http://server.url/resources/",
|
|
"post": "http://server.url/resources/",
|
|
"types": "http://server.url/types/",
|
|
"keywords": "http://server.url/keywords/",
|
|
"postTypes": "http://server.url/types/",
|
|
"postKeywords": "http://server.url/keywords/",
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
```
|
|
|
|
### User registration
|
|
|
|
The user registration module allows users to self-register.
|
|
|
|
Community module is mandatory.
|
|
|
|
If you set `allow_self_registration` on a community, it'll disable the auto-login feature of Hubl and allow your users to self register on your application.
|
|
|
|
To activate it, you need:
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "registering",
|
|
"parameters": {
|
|
"authority": "http://server.url/",
|
|
"authorityName": "your-authority-indentifier"
|
|
},
|
|
"endpoints": {
|
|
"get": "http://server.url/open-communities/"
|
|
}
|
|
}
|
|
```
|
|
|
|
Where:
|
|
|
|
* `authority` is the OpenID Provider. Usually, if you use `djangoldp_account` it's the same as your djangoldp server.
|
|
* `authorityName` is a visual name of your OpenID Provider
|
|
|
|
### 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.
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "themeChecker",
|
|
"route": false
|
|
}
|
|
```
|
|
|
|
Then you'll find 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.
|
|
|
|
### 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` packages
|
|
|
|
Community module is mandatory.
|
|
|
|
Module declaration, on `config.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "profileDirectory",
|
|
"endpoints": {
|
|
"get": "http://server.url/users/",
|
|
"skills": "http://server.url/skills/",
|
|
"uploads": "http://server.url/upload/"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Route generation
|
|
|
|
Hubl will, by default, generate an unique route for every of your module. You can customize this route by setting a `route` attribute on your module declaration.
|
|
|
|
Eg. for the Users Directory:
|
|
|
|
```json
|
|
{
|
|
"type": "profileDirectory",
|
|
"endpoints": {
|
|
"get": "http://server.url/users/",
|
|
"skills": "http://server.url/skills/",
|
|
"uploads": "http://server.url/upload/"
|
|
},
|
|
"route": "directory"
|
|
}
|
|
```
|
|
|
|
Will lead to `http://client.url/directory` as URL to reach the module instead of the default `http://client.url/profileDirectory`.
|
|
|
|
If you provide no `route`, then Hubl will use the `type` as route view name. If two modules share the same `route`, they'll get suffixed with a random unique id.
|
|
|
|
Some module don't need any route to be active, set `route` to `false` so.
|
|
|
|
Components can get the route of a module with `window.hubl.getRoute('componentName')`.
|
|
|
|
#### Change the default route
|
|
|
|
By default, Hubl will take a Dashboard as a default route.
|
|
|
|
You can enforce a component to be the default one by adding `defaultRoute` to its parameters.
|
|
|
|
Eg.:
|
|
|
|
```json
|
|
{
|
|
"type": "profileDirectory",
|
|
"endpoints": {
|
|
"get": "http://server.url/users/",
|
|
"skills": "http://server.url/skills/",
|
|
"uploads": "http://server.url/upload/"
|
|
},
|
|
"route": "directory",
|
|
"defaultRoute": true
|
|
}
|
|
```
|
|
|
|
If there is more than one component with this parameter, it'll be ignored.
|
|
|
|
## 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`
|
|
|
|
### I see some technical strings instead of my fallback language strings
|
|
|
|
By default, the template fallback to `fr` lang, which is the most complete. If you're using your own fallback lang within your configuration, please ensure that this lang is completly translated.
|
|
|
|
### I see some technical strings instead of my custom language
|
|
|
|
Using a custom language file does not allow to use the default fallback language.
|
|
|
|
## Built With
|
|
|
|
* [Sib-Core](https://git.startinblox.com/framework/sib-core/) - A SOLID-Compliant framework
|