Hydra Order Management System (HOMS)

HOMS is an open source web application for order and business process management.

Application consists of three parts:

User interface - managing orders and tasks for registered users (Single Page Application).
Administrator interface - managing users and order types.
REST API - operations with orders and users.

Requirements:

Compatibility:

Camunda 7.9.0 compatible with PostgreSQL 9.1 / 9.3 / 9.4 / 9.6
Minio latest release

Resources:

Documentation: http://hydra-oms.com/docs
Demo: http://demo.hydra-oms.com
Tickets/Issues: https://github.com/latera/homs/issues

Installation

The preferred way to install HOMS is to use Docker.

In production

Download docker-compose.yml and default .env config file:

wget https://raw.githubusercontent.com/latera/homs/master/docker-compose.yml
wget https://raw.githubusercontent.com/latera/homs/master/.env.sample -O .env

:pushpin: All variables are set in .env file. There you can change them, if you want to.

For OS X users: make path to folder with config shared in Docker -> Preferences... -> File Sharing.
Set SECRET_KEY_BASE variable in your .env with uniq id as value. You can generate key with openssl rand -hex 64 command. For example:
```
SECRET_KEY_BASE=0750fd0eac13032778f0a42e2ab450003eaece477ea881501be0cc438f870a2f498dbbc00ffb7c8379c30c960568a402d315496bb7bc2b3ee324401ba788a
```
:warning: Make sure this key is secret and don't share it with anyone.
Change Minio credentials in .env file. Generate MINIO_ACCESS_KEY and MINIO_SECRET_KEY values with any credentials generator, e.g. pwgen 32 2.
Set MINIO_CONSOLE_PORT in .env file.
Run docker-compose:
```
docker-compose up -d
```
Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.
Login to HydraOMS with user@example.com/changeme. Now you are able to start Pizza Order demo process.

You can login to Camunda Admin interface with credentials equal to BPM_USER:BPM_PASSWORD values from .env file (user/changeme if these variables aren't set).

In development

Follow the instructions below:
- With Oracle Instant Client.
- Without Oracle Instant Client (default way).
Navigate to Minio control panel and create a bucket with name equal to MINIO_BUCKET_NAME value from .env file.
Export all variables from .env file
```
export $(cat .env | xargs)
```
Change in bpm.yml value of development.base_url from http://camunda:8080/engine-rest/ to http://localhost:8766/engine-rest/
In database.yml change value of development.host from <%= ENV['HOMS_DB_HOST'] %> to localhost
Install Yarn and run:
```
yarn install
```
Compile assets:
```
yarn dev
```
Start HOMS application in another console tab:
```
rails s
```
Create and populate the database (adds an admin user, initial order types, and orders):
```
rails db:migrate
export SEED_DB=true
rails db:seed
```
Log in at HydraOMS with user@example.com/changeme.

Updating dependencies

Update gems:
```
bundle update
```
Update js packages:
```
yarn upgrade-interactive --latest
```
Do not update:
- bootstrap and related packages
- jquery and related packages

Work with SSO

Requirements:

Keycloak

For using SSO with HOMS:

Add user roles. HOMS use "admin" and "user" client level roles. Only one role could be assigned to user.
Add user attributes in Keycloak: company, department.
Add mappers in Keycloak without prefix:

Name | Mapper type | User attribute | Token clain name | Claim JSON type | Add to ID token | Add to access token | Add to userinfo | Multivalued | Aggregate attributes values --- | --- | --- | --- | --- | --- | --- | --- | --- | --- company | User Attribute | company | company | string | On | On | On | Off | Off department | User Attribute | department | department | string | On | On | On | Off | Off

Add to HOMS config file homs_configuration.yml:

sso:
  enabled: true
  use_regular_login: true
  keycloak:
    auth_server_url: "http://keycloak_host:keycloak_port/auth/"
    realm: hydra
    client_id: homs
    redirect_uri: "http://homs_host:homs_port/authenticate_by_keycloak"
    secret: "af9504fc-b030-405e-97b6-813220c07a7e"
    logout_redirect: "http://homs_host:homs_port"
    scope:
      - homs

Filter business processes by user

Set cadidate_starters.enabled in hbw.yml to true to send user email to camunda when fetching business processes definition. That way you can allow users to run only certain business processes.

Contributing/Development

The general development process is:

Fork this repo and clone it to your workstation.
Create a feature branch for your change.
Write code and tests.
Push your feature branch to github and open a pull request against master.

Reporting Issues

Issues can be reported by using GitHub Issues.

Testing

HOMS uses RSpec for unit/spec tests. You need to set up different testing database. Otherwise your development DB would be erased.

# Run all tests
bundle exec rspec spec

# Run a single test file
bundle exec rspec spec/PATH/TO/FILE_spec.rb

# Run a subset of tests
bundle exec rspec spec/PATH/TO/DIR

HBW Widget uses jest and snapshots for tests.

# Run frontend tests
jest
# Update snapshots after intentionally changing implementation elements
jest --updateSnapshot

Upgrade PostgreSQL

To upgrade PostgreSQL (HOMS database) to the 15.4 version, we recommend using the pg_dumpall utility:

Copy service db_homs as db_homs_new in docker-compose.yml
In db_homs_new set image: postgres:15.4, change volume to ./data/homs_new/postgresql:$HOMS_DB_PATH, port to 15432:5432, container name to postgres-homs-new
Run db_homs_new and db_homs services docker-compose up db_homs db_homs_new. Wait for postgres instances to start up
Dump db_homs data to file: docker exec -it postgres-homs /usr/bin/pg_dumpall -U homs > dumpfile
Upload data to db_homs_new: docker exec -i postgres-homs-new psql -U homs < dumpfile
Stop db_homs_new and db_homs containers. Replace old volume: rm -rf ./data/homs && mv ./data/homs_new ./data/homs
In db_homs set image: postgres:15.4, remove db_homs_new in docker-compose.yml
Re-hash password for HOMS_DB_USER: source .env && docker exec -it postgres-homs psql -U $HOMS_DB_USER, \password, enter twice value of HOMS_DB_PASSWORD from .env file and enter quit;

Homs

Install / Use

README