{"id":13902533,"url":"https://github.com/faberNovel/pericles","last_synced_at":"2025-07-18T00:31:37.887Z","repository":{"id":37063346,"uuid":"117111258","full_name":"faberNovel/pericles","owner":"faberNovel","description":"API specification solution","archived":false,"fork":false,"pushed_at":"2023-01-19T21:52:39.000Z","size":4269,"stargazers_count":39,"open_issues_count":44,"forks_count":5,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-08-07T22:34:01.777Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faberNovel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-01-11T14:29:04.000Z","updated_at":"2023-09-08T17:35:03.000Z","dependencies_parsed_at":"2023-01-28T19:46:04.264Z","dependency_job_id":null,"html_url":"https://github.com/faberNovel/pericles","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faberNovel%2Fpericles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faberNovel%2Fpericles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faberNovel%2Fpericles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faberNovel%2Fpericles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faberNovel","download_url":"https://codeload.github.com/faberNovel/pericles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226310617,"owners_count":17604615,"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":[],"created_at":"2024-08-06T22:01:11.566Z","updated_at":"2024-11-25T10:32:14.406Z","avatar_url":"https://github.com/faberNovel.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"Pericles\n\u0026middot;\n![Language](https://img.shields.io/badge/language-Ruby-red.svg)\n![Framework](https://img.shields.io/badge/framework-Rails-red.svg)\n![License](https://img.shields.io/github/license/applidium/Pericles.svg)\n[![Twitter](https://img.shields.io/badge/twitter-@applidium-blue.svg)](https://twitter.com/applidium)\n======\n\n\u003cp align=\"center\" \u003e\n  \u003cimg src=\"banner.jpg\" alt=\"Pericles\"\u003e\n\u003c/p\u003e\n\nPericles was designed to make **API specification** easier.\n\n## Installation\n\nTo run the project locally, you have the choice between using containers or setup your own machine.\n\n### Use docker-compose\n\nCreate your own `docker-compose.yml` based on the [sample](docker-compose.yml.sample), then run:\n\n```sh\ndocker build -t pericles:ruby-2.7 .\ndocker-compose up\n```\n\n### Setup your machine\n\nPericles is a Ruby on Rails project. To get the project up and running, proceed as follows (within the app's directory):\n\n1. Install the version of Ruby specified at the top of the [Gemfile](Gemfile#L2) along with the bundler gem.\n\n2. Install the required gems and dependencies:\n   ```sh\n   bundle install\n   ```\n\n3. This project uses PostgreSQL. Create the local databases for the different environments (development and test):\n   ```sh\n   createdb Pericles_GW_dev\n   createdb Pericles_GW_test\n   ```\n\n4. Run the migrations:\n   ```sh\n   bundle exec rake db:migrate\n   ```\n\n5. Pericles uses [Node.js](https://nodejs.org), and [Yarn](https://yarnpkg.com) to manage packages. We use\n [json-schema-faker](https://github.com/json-schema-faker/json-schema-faker) to generate JSON instances based on JSON Schemas,\n because we could not find a Ruby equivalent. To install the required packages, run:\n   ```sh\n   yarn install\n   ```\n\n6. Pericles uses [dotenv](https://github.com/bkeepers/dotenv) to manage [environment variables](#environment-variables) in the test and development\n environments.\n   * You should create a .env file in the project's directory,\n   * Every environment variable you need (in the test and development environments) should be declared in this file. For instance:\n      ```\n      YOUR_ENVIRONMENT_VARIABLE=your_value\n      ```\n\n7. You should now be able to run the project smoothly on your machine:\n   ```sh\n   bundle exec rails s\n   ```\n\n## Environment variables\n\nName | Description | Example\n--- |--- | ---\n`SECRET_KEY_BASE` | You can use `bundle exec rake secret` in the app's directory to generate this key. | n/a\n`GOOGLE_APP_ID` | Client ID of your OAuth client ID in the Google Developers Console. Check [Google OAuth2](#google-oauth2). | n/a\n`GOOGLE_APP_SECRET` | Client secret of your OAuth client ID in the Google Developers Console. [Google OAuth2](#google-oauth2). | n/a\n`INTERNAL_EMAIL_DOMAIN` | Email domain used for authentication purposes. [Google OAuth2](#google-oauth2). | `@fabernovel.com`\n`MAIL_DEFAULT_URL` | Public URL to Pericles instance used to generate absolute links in emails | `pericles.fabernovel.com`\n`MAIL_SMTP_DOMAIN` | Domain of the from field in your email | `pericles.fabernovel.com`\n`MAIL_SMTP_PASSWORD` | Password to connect to your SMTP server | n/a\n`MAIL_SMTP_USERNAME` | Username to connect to your SMTP server | n/a\n`ANDROID_COMPANY_DOMAIN_NAME` | Pericles allows to generate code in Kotlin. The environment variable corresponds to what you would enter under 'Company Domain' when creating a project in Android Studio. It is then used to generate package names. Defaults to `com.example`. | `com.applidium`\n`RAILS_ENV` | Rails environment. Defauls to `development`.  | `production`\n`PORT` | Port on which the web server will listen. Defaults to `3000`. | `8080`\n`DATABASE_URL` | The URL of your PostgreSQL database. Defaults to [database.yml](config/database.yml). | `postgres://username:password@host/database`\n`RAILS_SERVE_STATIC_FILES` | In case your reverse proxy do not serve static files. Defaults to `false`. | `enabled`\n`RAILS_DISABLE_FORCE_SSL` | In case your reverse proxy do not handle SSL. Defaults to `false`. | `enabled`\n`PROXY_HOST` | The host of your [Elixir proxy](proxy)\n`SLACK_CLIENT_ID` | Client ID of your Slack app. Check [Slack integration](#slack-integration). | `1234567890.1234567890`\n`SLACK_CLIENT_SECRET` | Client secret of your Slack app. Check [Slack integration](#slack-integration). | `abcdef123456789`\n\n### Google OAuth2\n\nPericles uses [Devise](https://github.com/plataformatec/devise) to manage authentication. More specifically, it lets users log\n in using their Google account via OAuth2. To make this work, you need to:\n* Create a project on [Google Developers Console](https://console.developers.google.com),\n* Follow the instructions [here](https://github.com/zquestz/omniauth-google-oauth2#google-api-setup) (in the Google API\n Setup section),\n* On the Google Developers Console (in your project) go to Credentials, and click on the Credentials tab on top. Click on\n \"Create Credentials\", and choose \"OAuth client ID\". Choose \"Web application\" for \"Application type\". Choose a name for your\n OAuth client ID. In \"Authorized JavaScript origins\", add `http://localhost:3000` (the URI of the application when run\n locally). In \"Authorized redirect URIs\", add `http://localhost:3000/users/auth/google_oauth2/callback` (the URI, when the\n application is run locally, which users are redirected to after being authenticated with Google). You can then click on\n \"Save\".\n* Once your OAuth client ID was created, it should appear (in Credentials, in the Credentials tab) under\n \"OAuth 2.0 client IDs\". You can click on it to view its details.\n* The value for `GOOGLE_APP_ID` should be your OAuth client ID's \"Client ID\", and the value for `GOOGLE_APP_SECRET` should be your OAuth\n client ID's \"Client secret\".\n* Pericles will use INTERNAL_EMAIL_DOMAIN environment variable for authentication purposes. The only users that will be able to log in through OAuth2 are the users from the email domain you provided.\n\n### Slack integration\n\nIf you want to post recent news on Slack, you can [create a Slack app](https://api.slack.com/apps). Then:\n\n1. Enable the *Incoming webhooks* feature.\n2. Enable OAuth and whitelist the redirect URL which should looks like `https://YOUR_HOST/projects`.\n3. Set the `SLACK_CLIENT_ID` and `SLACK_CLIENT_SECRET` env variables.\n\nTo automate this posting, use the `audits:slack_post` rake task in a cron/scheduler.\n\n## Deployment\n\nTo make sure that your newly deployed instance of Pericles works correctly, you should set up the [environment variables](#environment-variables). Do not forget to replace `http://localhost:3000` by the URI (using https) of your newly deployed application when reading the instructions.\n\n### Heroku\n\nHeroku automatically set `RAILS_ENV`, `PORT`, `DATABASE_URL` (see [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql)) and `RAILS_SERVE_STATIC_FILES` for you.\n\n[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)\n\n### Container\n\nThe [Dockerfile](Dockerfile) defines a container with a web server listening on the PORT environment variable.\n\n## Tests\n\nTo run tests, simply run (in the project's directory):\n\n```sh\nbundle exec rails test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfaberNovel%2Fpericles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FfaberNovel%2Fpericles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfaberNovel%2Fpericles/lists"}