{"id":29272008,"url":"https://github.com/jrjoacir/cerberus","last_synced_at":"2025-07-05T00:10:22.621Z","repository":{"id":40012289,"uuid":"283360184","full_name":"jrjoacir/cerberus","owner":"jrjoacir","description":"This project is an API whose purpose is to authorize or revoke access to product features. Every structure created involves the relationship of several entities: Clients, Users, Products, Contracts, Roles and Functionalities. ","archived":false,"fork":false,"pushed_at":"2023-01-19T20:54:30.000Z","size":244,"stargazers_count":8,"open_issues_count":16,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2023-03-03T12:35:51.446Z","etag":null,"topics":["access","acesso","funcionalidades","funcionalities"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jrjoacir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-29T00:42:48.000Z","updated_at":"2021-05-08T23:34:15.000Z","dependencies_parsed_at":"2023-01-28T23:15:17.395Z","dependency_job_id":null,"html_url":"https://github.com/jrjoacir/cerberus","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/jrjoacir/cerberus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrjoacir%2Fcerberus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrjoacir%2Fcerberus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrjoacir%2Fcerberus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrjoacir%2Fcerberus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrjoacir","download_url":"https://codeload.github.com/jrjoacir/cerberus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrjoacir%2Fcerberus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263636825,"owners_count":23492312,"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":["access","acesso","funcionalidades","funcionalities"],"created_at":"2025-07-05T00:10:21.756Z","updated_at":"2025-07-05T00:10:22.589Z","avatar_url":"https://github.com/jrjoacir.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e Está documentação também está disponível em [Português do Brasil](README_pt-br.md).\n# Cerberus Project\nThis project is an API whose purpose is to authorize or revoke access to product features. Every structure created involves the relationship of several entities: Clients, Users, Products, Contracts, Roles and Functionalities. Read [Entity Documentation](entity_documentation.md) to get more details about entities, theirs relations and objectives.\n\nThe **Cerberus** project was created with the English language in mind, not because it has more \"scope\" or more \"acceptance\" in one or another community, but the English language was chosen only to contribute to the learning of the project's creator in this language in technical projects. There are other projects by this author that are in Brazilian Portuguese either for the convenience of the creator or for the intention of being more inclusive with Brazilian Portuguese speakers, my mother language.\n\n## Why was the name Cerberus chosen?\n\u003e In Greek mythology, **Cerberus** (/ˈsɜːrbərəs/;[2] Greek: Κέρβερος Kérberos [ˈkerberos]), often referred to as the hound of Hades, is a multi-headed dog that guards the gates of the Underworld to prevent the dead from leaving. He was the offspring of the monsters Echidna and Typhon, and was usually described as having three heads, a serpent for a tail, and snakes protruding from multiple parts of his body. Cerberus is primarily known for his capture by Heracles, one of Heracles' twelve labours. - [Wikipedia](https://en.wikipedia.org/wiki/Cerberus)\n\nI chose the name **Cerberus**, because it is about keeping something, in this case the \"gates of the Underworld\" which for this project may mean access to some functionality. Therefore, we can say that this project keeps the functionality of a product.\n\n# How to develop\n\n## Dependencies\nThis project was designed with the greatest possible independence from the operating system and its libraries, so I preferred to create it only with dependence on docker containers. Therefore, it is necessary the following resources to develop:\n\n- [Docker](https://docs.docker.com/install/)\n- [Docker Compose](https://docs.docker.com/compose/install/)\n\n## Technological stack\n\n- **Database**: [Postgresql 12](https://www.postgresql.org/)\n- **Programming language**: [Ruby 2.7](https://ruby-doc.org/core-2.7.0/)\n- **API Framework**: [Rails 6](https://guides.rubyonrails.org/)\n\n## Quick start - *See the application working*\n\n1. Build all containers: ```docker-compose build```\n\n2. Starting the application container (*development*): ```docker-compose up development```\n\n3. **Done!**. Now, you can access your application by http://localhost:3000/healthcheck.\n\n## Understanding and using the development environment\n\n### The Containers\n\nThis project provides four docker containers:\n\n- **database**: Container that provides two Postgresql database instances: **postgres_dev** (development) and **postgres_test** (tests)\n- **development**: Container that runs the API. It depends on the *database* container.\n- **test**: Container that runs tests and code analyzer. It depends on the *database* container.\n- **apiblueprint**: Container that runs the API documentation server in Blueprint format.\n\n| Services         | Depends on service | Objectives                                                                               |\n|------------------|--------------------|------------------------------------------------------------------------------------------|\n| **database**     |                    | Make the PostgreSQL database available                                                   |\n| **development**  | database           | Run the API server                                                                       |\n| **test**         | database           | Provide environment to perform the execution of tests and code  analyzer                 |\n| **apiblueprint** |                    | Creates and runs the API documentation server, which can be run to simulate API requests |\n\nMore information about *stop*, *start*, *restart*, *run* and other commands, read [Docker Compose Documentation](https://docs.docker.com/compose/) and [Docker Documentation](https://docs.docker.com/).\n\n### Building containers\n\nTo build all the containers just run the following command:\n\n```bash\ndocker-compose build\n```\n\nIf you want to build only one container, execute:\n\n```bash\ndocker-compose build \u003ccontainer-name\u003e\n```\n\n### Starting the API\n\nTo start the API, you must execute the command:\n```bash\ndocker-compose up development\n```\n\nWhen starting the API, the container (**development**) performs the following actions:\n- Creates the database structure (*migrations*)\n- Runs the Web server\n\n**Done!** Now, you can access your application by http://localhost:3000/healthcheck.\n\n### Running tests and code analyzer\n\nThis project uses an exclusive container to execute tests and code analyzer, which is the **test** container. To build the test container, run:\n\n```bash\ndocker-compose up test\n```\n\nWhen creating the **test** container, the entire database structure (*migrations*) will be created.\n\nRun all tests with the following command:\n\n```bash\ndocker-compose run --rm test rails test\n```\n\nTo run tests to just one file, you must enter the filename at the end of the command.\n\n```bash\ndocker-compose run --rm test rails test test/controllers/clients_controller_test.rb\n```\n\nAnalyze all the code with [Rubocop](https://github.com/rubocop-hq/rubocop) by running:\n\n```bash\ndocker-compose run --rm test rubocop\n```\n\nTo analyze the code for just one file, you must enter the filename at the end of the command.\n\n```bash\ndocker-compose run --rm test rubocop app/controllers/clients_controller.rb\n```\n\n#### Tips\nIn all of the above commands, a new container is created to run the commands and at the end of the run this container is removed.\n\nThere is also the option of using the test container as a local machine, so it would be enough to enter it, perform the executions of interest and leave when you want:\n\n- Enter in the container: ```docker-compose run --rm test sh```\n- Run tests from inside the container: ```rails test```\n- Run code analyzer: ```rails rubocop```\n- Exit from container: ```exit```\n\n### Creating sample data\n\nIf you need to insert some sample data into the database, you can use *rake task* **seed** typing the command below.\n\n```bash\ndocker-compose run --rm development rails db:seed\n```\n\n### Performing database migration\n\nIf you need to perform the database migration, you must use the *rake task* **migrate** of the database typing the command below.\n\n```bash\ndocker-compose run --rm development rails db:migrate\n```\n\n### Using API Blueprint documentation\n\nThis project uses Blueprint format API documentation and you can run the container **apiblueprint** to use it. So, execute:\n\n```bash\ndocker-compose up apiblueprint\n```\n\nand access ```http://localhost:8088/```\n\nThe blueprint container will interpret `doc.apib` file and will generate a html file. Then, when you access it, you will be able to read and interact with this documentation. More about Blueprint, visit [api blueprint](https://apiblueprint.org/).\n\n# How to create and publish a docker image\nWe decided to provided a docker image at [Docker Hub](https://hub.docker.com/) on [Cerberus repository](https://hub.docker.com/repository/docker/jrjoacir/cerberus) to be used on any environment. Then, we have to create a docker image tagged with a correct version and push it to [Cerberus repository](https://hub.docker.com/repository/docker/jrjoacir/cerberus).\n\n1. **Create docker image**\n```sh\ndocker build -f Dockerfile.deploy -t jrjoacir/cerberus:{VERSION} .\n```\n2. **Login to Docker Hub**\n```sh\ndocker login -u \u003cuser-dockerhub-name\u003e\n```\n3. **Publish docker image**\n```sh\ndocker push jrjoacir/cerberus:{VERSION}\n```\n\n# How to deploy\nWe provided a docker image on [Cerberus repository](https://hub.docker.com/repository/docker/jrjoacir/cerberus) to execute a container ready to run on any environment.\n\n## Requirements\n- [Docker](https://docs.docker.com/install/)\n- [Postgresql database](https://www.postgresql.org/)\n- Environment variables:\n\n| Variable       | Description |\n|----------------|-------------|\n| **RAILS_ENV**  | Environment where container will run. Possible options: test, development, staging and production |\n| **DB_HOST**    | Database address |\n| **DB_NAME**    | Database schema name |\n| **DB_USER**    | User database. **Tip**: use database user database to application only for read-write access and only use database administrator to create database objects |\n| **DB_PASS**    | User database password |\n| **DB_ADAPTER** | Adapter database used by Ruby on Rails Framework. At the moment, it is possible use only **postgresql** adapter |\n\n## Execute Cerberus API on a docker container\n1. **Get the docker image from DockerHub**\n```sh\ndocker pull jrjoacir/cerberus:{VERSION}\n```\n2. **Execute migration to synchronize database objects**\n```sh\ndocker run --rm -it -e RAILS_ENV={environment} -e DB_HOST={database_host} -e DB_NAME={database_name} -e DB_USER={database_user} -e DB_PASS={database_user_password} -e DB_ADAPTER=postgresql jrjoacir/cerberus:{VERSION} rails db:migrate\n```\n**Attention**: To execute migration on database, it is necessary that database user has access to create database objects (tables, indexes, constraints).\n\n**Note**: environment variable values can be setted by operational system environment variable. More about run docker with variables, read [Docker Run Documentation](https://docs.docker.com/engine/reference/commandline/run/).\n\n3. **Run container ready to be used**\n```sh\ndocker run --rm -it -e RAILS_ENV={environment} -e DB_HOST={database_host} -e DB_NAME={database_name} -e DB_USER={database_user} -e DB_PASS={database_user_password} -e DB_ADAPTER=postgresql -p {IP}:{Port}:{external port}/tcp jrjoacir/cerberus:{VERSION} rails s -p {port} -b 0.0.0.0\n```\n\n**Attention**: Inform a database user with correct privileges to run API. Probably, only privilegies to read-write data it is necessary.\n\n**Note**: Read [Docker Run Documentation](https://docs.docker.com/engine/reference/commandline/run/) to know more about environment variable use and port configurations.\n\n**Example**:\n```sh\ndocker run --rm -it -e RAILS_ENV=production -e DB_HOST=database -e DB_NAME=postgres_dev -e DB_USER=postgres -e DB_PASS=postgres_password -e DB_ADAPTER=postgresql -p 127.0.0.1:3000:3000/tcp jrjoacir/cerberus:0.1.0 rails s -p 3000 -b 0.0.0.0\n```\n\n## License\nThis project is licensed by **GNU General Public License v3.0**.\n\n\u003e Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.\n\nMore about this license access [GNU General Public License v3.0](LICENSE.md).\n\n## Additional Information\n- The *Dockerfile* containing the Ruby language was obtained from the official repository on [DockerHub](https://hub.docker.com/): [Ruby Dockerfile](https://hub.docker.com/_/ruby/)\n- The *Dockerfile* for PostgreSQL was obtained from the official repository on [DockerHub](https://hub.docker.com/): [Postgresql Dockerfile](https://hub.docker.com/_/postgres/)\n- The script for creating multiple *databases* on PostgreSQL was obtained from the [Github](https://github.com) repository [docker-postgresql-multiple-databases](https://github.com/mrts/docker-postgresql-multiple-databases)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrjoacir%2Fcerberus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrjoacir%2Fcerberus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrjoacir%2Fcerberus/lists"}