{"id":13990586,"url":"https://github.com/hydra-billing/homs","last_synced_at":"2025-07-22T12:33:18.529Z","repository":{"id":37091997,"uuid":"57213848","full_name":"hydra-billing/homs","owner":"hydra-billing","description":"Hydra Order Management System","archived":false,"fork":false,"pushed_at":"2024-04-07T20:30:44.000Z","size":6442,"stargazers_count":280,"open_issues_count":11,"forks_count":86,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-04-07T21:30:13.489Z","etag":null,"topics":["bss","latera","oms"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hydra-billing.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-04-27T13:03:22.000Z","updated_at":"2024-04-14T21:33:56.500Z","dependencies_parsed_at":"2023-10-30T15:48:09.523Z","dependency_job_id":"381557f5-3e74-409c-b4e6-958f02e60e45","html_url":"https://github.com/hydra-billing/homs","commit_stats":null,"previous_names":[],"tags_count":106,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydra-billing%2Fhoms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydra-billing%2Fhoms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydra-billing%2Fhoms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydra-billing%2Fhoms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hydra-billing","download_url":"https://codeload.github.com/hydra-billing/homs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227098863,"owners_count":17730651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bss","latera","oms"],"created_at":"2024-08-09T13:02:57.778Z","updated_at":"2024-11-29T10:31:00.135Z","avatar_url":"https://github.com/hydra-billing.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Hydra Order Management System (HOMS)\n\n*HOMS* is an open source web application for order and business process management.\n\nApplication consists of three parts:\n\n* User interface - managing orders and tasks for registered users (Single Page Application).\n* Administrator interface - managing users and order types.\n* REST API - operations with orders and users.\n\nRequirements:\n\n* [Docker](https://docker.com/)\n* [docker-compose](https://docs.docker.com/compose/install/)\n\nCompatibility:\n\n* [Camunda 7.9.0 compatible](https://docs.camunda.org/manual/7.9/introduction/supported-environments/#supported-database-products) with PostgreSQL 9.1 / 9.3 / 9.4 / 9.6\n* Minio [latest release](https://github.com/minio/minio/releases)\n\nResources:\n\n* Documentation: [http://hydra-oms.com/docs](http://hydra-oms.com/docs)\n* Demo: [http://demo.hydra-oms.com](http://demo.hydra-oms.com)\n* Tickets/Issues: [https://github.com/latera/homs/issues](https://github.com/latera/homs/issues)\n\n## Installation\n\nThe preferred way to install HOMS is to use [Docker](https://www.docker.com/).\n\n### In production\n\n1. Download `docker-compose.yml` and default `.env` config file:\n\n    ```bash\n    wget https://raw.githubusercontent.com/latera/homs/master/docker-compose.yml\n    wget https://raw.githubusercontent.com/latera/homs/master/.env.sample -O .env\n    ```\n\n    :pushpin: All variables are set in `.env` file. There you can change them, if you want to.\n\n1. For OS X users: make path to folder with config shared in `Docker -\u003e Preferences... -\u003e File Sharing`.\n\n1. 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:\n\n    ```bash\n    SECRET_KEY_BASE=0750fd0eac13032778f0a42e2ab450003eaece477ea881501be0cc438f870a2f498dbbc00ffb7c8379c30c960568a402d315496bb7bc2b3ee324401ba788a\n    ```\n\n    :warning: Make sure this key is secret and don't share it with anyone.\n\n1. Change [Minio](https://github.com/minio/minio) credentials in `.env` file. Generate `MINIO_ACCESS_KEY` and `MINIO_SECRET_KEY` values with any credentials generator, e.g. `pwgen 32 2`.\n\n1. Run `docker-compose`:\n\n    ```bash\n    docker-compose up -d\n    ```\n\n1. Navigate to [Minio control panel](http://localhost:9000) and create a bucket with name equal to `MINIO_BUCKET_NAME` value from `.env` file.\n\n1. Login to [HydraOMS](http://localhost:3000) with *`user@example.com`*/*`changeme`*. Now you are able to start Pizza Order demo process.\n\nYou can login to [Camunda Admin interface](http://localhost:8766/camunda) with credentials equal to `BPM_USER:BPM_PASSWORD` values from `.env` file (`user/changeme` if these variables aren't set).\n\n### In development\n1. Follow the instructions below:\n    * [With Oracle Instant Client](https://github.com/latera/homs/blob/master/WITH_ORACLE.md).\n\n    * [Without Oracle Instant Client](https://github.com/latera/homs/blob/master/WITHOUT_ORACLE.md) (default way).\n\n1. Navigate to [Minio control panel](http://localhost:9000) and create a bucket with name equal to `MINIO_BUCKET_NAME` value from `.env` file.\n1. Export all variables from .env file\n   ```\n   export $(cat .env | xargs)\n   ```\n1. Change in bpm.yml value of development.base_url from `http://camunda:8080/engine-rest/` to `http://localhost:8766/engine-rest/`\n1. In database.yml change value of development.host from `\u003c%= ENV['HOMS_DB_HOST'] %\u003e` to `localhost`\n1. Install [Yarn](https://github.com/yarnpkg/yarn#installing-yarn) and run:\n   ```\n   yarn install\n   ```\n\n1. Compile assets:\n    ```bash\n    yarn dev\n    ```\n1. Start HOMS application in another console tab:\n    ```bash\n    rails s\n    ```\n1. Create and populate the database (adds an admin user, initial order types, and orders):\n    ```bash\n    rails db:migrate\n    export SEED_DB=true\n    rails db:seed\n    ```\n1. Log in at [HydraOMS](http://localhost:3000) with *`user@example.com`*/*`changeme`*.\n\n### Updating dependencies\n* Update gems:\n    ```\n    bundle update\n    ```\n* Update js packages:\n    ```\n    yarn upgrade-interactive --latest\n    ```\n    Do not update:\n    * bootstrap and related packages\n    * jquery and related packages\n\n### Work with SSO\nRequirements:\n* [Keycloak](https://www.keycloak.org/)\n\nFor using SSO with HOMS:\n1. Add [user roles](https://www.keycloak.org/docs/latest/server_admin/index.html#con-client-roles_server_administration_guide). HOMS use \"admin\" and \"user\" client level roles. Only one role could be assigned to user.\n2. Add [user attributes](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-configuring-user-attributes_server_administration_guide) in Keycloak: `company`, `department`.\n3. Add [mappers](https://www.keycloak.org/docs/latest/server_admin/index.html#_protocol-mappers) in Keycloak without prefix:\n\nName | 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\n--- | --- | --- | --- | --- | --- | --- | --- | --- | ---\n`company` | `User Attribute` | `company` | `company` | string | On | On | On | Off | Off\n`department` | `User Attribute` | `department` | `department` | string | On | On | On | Off | Off\n\n3. Add to HOMS config file `homs_configuration.yml`:\n```\nsso:\n  enabled: true\n  use_regular_login: true\n  keycloak:\n    auth_server_url: \"http://keycloak_host:keycloak_port/auth/\"\n    realm: hydra\n    client_id: homs\n    redirect_uri: \"http://homs_host:homs_port/authenticate_by_keycloak\"\n    secret: \"af9504fc-b030-405e-97b6-813220c07a7e\"\n    logout_redirect: \"http://homs_host:homs_port\"\n    scope:\n      - homs\n```\n\n### Filter business processes by user\n\nSet `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.\n\n## Contributing/Development\n\nThe general development process is:\n\n1. Fork this repo and clone it to your workstation.\n1. Create a feature branch for your change.\n1. Write code and tests.\n1. Push your feature branch to github and open a pull request against master.\n\n## Reporting Issues\n\nIssues can be reported by using [GitHub Issues](https://github.com/latera/homs/issues).\n\n## Testing\n\nHOMS uses RSpec for unit/spec tests. You need to set up different testing database. Otherwise your development DB would be erased.\n\n```bash\n# Run all tests\nbundle exec rspec spec\n\n# Run a single test file\nbundle exec rspec spec/PATH/TO/FILE_spec.rb\n\n# Run a subset of tests\nbundle exec rspec spec/PATH/TO/DIR\n```\nHBW Widget uses jest and [snapshots](https://jestjs.io/docs/snapshot-testing#snapshot-testing-with-jest) for tests. \n```bash\n# Run frontend tests\njest\n# Update snapshots after intentionally changing implementation elements\njest --updateSnapshot\n```\n\n## Upgrade PostgreSQL\nTo upgrade PostgreSQL (HOMS database) to the 15.4 version, we recommend using the `pg_dumpall` utility:\n1. Copy service `db_homs` as `db_homs_new` in `docker-compose.yml`\n2. 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`\n3. Run `db_homs_new` and `db_homs` services `docker-compose up db_homs db_homs_new`. Wait for postgres instances to start up\n4. Dump `db_homs` data to file: `docker exec -it postgres-homs /usr/bin/pg_dumpall -U homs \u003e dumpfile`\n5. Upload data to `db_homs_new`: `docker exec -i postgres-homs-new psql -U homs \u003c dumpfile`\n6. Stop `db_homs_new` and `db_homs` containers. Replace old volume: `rm -rf ./data/homs \u0026\u0026 mv ./data/homs_new ./data/homs`\n7. In `db_homs` set `image: postgres:15.4`, remove `db_homs_new` in `docker-compose.yml`\n8. Re-hash password for `HOMS_DB_USER`: `source .env \u0026\u0026 docker exec -it postgres-homs psql -U $HOMS_DB_USER`, `\\password`, enter twice value of `HOMS_DB_PASSWORD` from `.env` file and enter `quit;`\n\n## Links\n\n1. [Repo with helper classes for BPMN development](https://github.com/latera/camunda-ext).\n\n1. [Example of creating a demo business process](https://github.com/latera/camunda-ext/tree/master/demo_processes).\n\n## License\n\nCopyright (c) 2019 Latera LLC under the [Apache License](https://github.com/latera/homs/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydra-billing%2Fhoms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhydra-billing%2Fhoms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydra-billing%2Fhoms/lists"}