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 for registered users (Single Page Application).
Administrator interface - managing users and order types.
REST API - operations with orders and users.

Requirements:

PostgreSQL 9.4.x+

Resources:

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

Installation

There are 2 ways to install HOMS.

The prefered way to install HOMS is to use Docker

Using docker

In production

Install docker-compose.
Download docker-compose.yml:

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

For OS X users: make path to folder with HOMS shared in Docker -> Preferences... -> File Sharing.
Copy your (or default) .env file to your project's directory:

cp .env.sample .env

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

Add SECRET_KEY_BASE variable to your .env with uniq id as value. Generate it any way you like. For example:

SECRET_KEY_BASE=0750fd0eac13032778f0a42e2ab450003eaece477ea881501be0cc438f870a2f498dbbc00ffb7c8379c30c960568a402d315496bb7bc2b3ee324401ba788a

Make sure this key is secret and don't share it with anyone.

Change Minio credentials in .env file.
Be sure to update secret key in /etc/hydra/homs/secrets.yml. You can generate key with this command:

openssl rand -hex 64

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.
Navigate to Camunda Admin and create admin user with credentials equal to BPM_USER:BPM_PASSWORD values from .env file.
(Optional) If you want to use demo processes navigate to Camunda and create user with user@example.com email.
Login at HydraOMS with user@example.com/changeme.

In development

If you don't want to use Oracle as source for your HOMS instance:

Without Oracle Instant Client

Follow the same steps as for In production installation, but with certain changes:

Clone HOMS git repository:

git clone https://github.com/latera/homs.git

4.1. Create your own configs from samples:

find config -name '*.sample' | xargs -I{} sh -c 'cp $1 ${1%.*}' -- {}

Skip this step
Add test environment to config/database.yml:

development:
  adapter: postgresql
  encoding: unicode
  pool: 5
  host: <%= ENV['HOMS_DB_HOST'] %>
  port: <%= ENV['HOMS_DB_PORT'] %>
  database: <%= ENV['HOMS_DB_NAME'] %>
  username: <%= ENV['HOMS_DB_USER'] %>
  password: <%= ENV['HOMS_DB_PASSWORD'] %>

Run docker-compose: with custom config:

docker-compose -f docker-compose.dev.yml up -d

Or if you want to use Oracle as source for your HOMS instance:

With Oracle Instant Client

Follow the same steps as for without Oracle Instant Client installation, but with certain changes:

Download the Oracle Instant Client 11.2 archives from OTN:

http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html

The following three ZIPs are required:

instantclient-basic-linux.x64-11.2.0.4.0.zip
instantclient-sdk-linux.x64-11.2.0.4.0.zip
instantclient-sqlplus-linux.x64-11.2.0.4.0.zip

5.1. Place the downloaded Oracle Instant Client RPMs in the same directory as the Dockerfile and run:

docker build -t latera/homs-with-oracle -f Dockerfile.oracle .

5.2. Create config/sources.yml file with database credentials

sources:
  billing:
    type: sql/oracle
    tns_name: dbname
    username: user
    password: password

5.3. Add environment variable $TNSNAMES_PATH to .env file with path to your tnsnames.ora file:

TNSNAMES_PATH=/dir/with/tnsnames.ora

for access to host machine OS X users can use special DNS name host.docker.internal as host in tnsnames.ora (details)

Run docker-compose: with custom config:

docker-compose -f docker-compose.dev.oracle.yml up -d

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

zanchetmachado/homs