hubl/README.md
Jean-Baptiste Pasquier a0e3b5bd54 Update README.md
2020-11-24 11:32:17 +00:00

311 lines
8.1 KiB
Markdown

# Hubl
Hubl is the magic tool that allows the Freelance Network to thrive in a decentralized way.
## 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.
Federated Hubl needs to use `config.sample.federated.json` example.
You can quickly update your API URI from the samples:
```
$ sed 's/http:\/\/localhost:8000/https:\/\/api.your-server.startinblox.com/' config.sample.json > config.json
```
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
```
## 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
{
"xmpp": "https://jabber.happy-dev.fr/http-bind/",
"clientName": "My local Hubl",
"clientLogo": "/images/logo.webp",
"authority": "http://localhost:8000/",
"endpoints": {
"skills": "http://server.url/skills/",
"users": "http://server.url/users/",
"uploads": "http://server.url/upload/"
}
}
```
Where:
* `clientName` is the name of your Hubl
* `clientLogo` is an URL to an image file
* `xmpp` 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
"clientName": "Hubl",
"clientFavicon": "/images/favicon.webp",
"clientLogo": "/images/logo.webp",
"clientLogoHeight": "32px",
"clientCSS": "/path/to/custom.css",
"authorityName": "djangoldp-server-name"
```
Where:
* `clientName` is the name of your Hubl.
* `clientFavicon` is an URL to a distant favicon
* `clientLogo` is an URL to a distant logo for your client
* `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": {
"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": {
"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 path/to/djangoldp_dashboard/fixtures/sample.json`.
### 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": {
"projects": "http://server.url/projects/",
"customers": "http://server.url/customers/",
"businessproviders": "http://server.url/businessproviders/",
"skills": "http://server.url/skills/"
}
```
### 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,
"endpoints": {
"groups": "http://server.url/groups/",
"skills": "http://server.url/skills/",
"uploads": "http://server.url/upload/"
}
```
### 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": {
"joboffers": "http://server.url/job-offers/",
"skills": "http://server.url/skills/",
"uploads": "http://server.url/upload/"
}
```
### 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": {
"events":"http://server.url/events/",
"typeevents":"http://server.url/typeevents/",
"uploads": "http://server.url/upload/"
}
```
### 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": {
"resources":"http://server.url/resources/",
"resourceskeywords":"http://server.url/keywords/",
"resourcestypes":"http://server.url/types/",
"uploads": "http://server.url/upload/"
}
```
### 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": {
"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`.
## Built With
* [Sib-Core](https://git.startinblox.com/framework/sib-core/) - An awesome new framework!