# Rails API Template [![Github Actions CI](https://github.com/rootstrap/rails_api_base/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/rootstrap/rails_api_base/actions) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=rootstrap_rails_api_base&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=rootstrap_rails_api_base) Rails API Base is a boilerplate project for JSON RESTful APIs. It follows the community best practices in terms of standards, security and maintainability, integrating a variety of testing and code quality tools. It's based on Rails 8.1 and Ruby 4.0. Finally, it contains a plug an play Administration console (thanks to [ActiveAdmin](https://github.com/activeadmin/activeadmin)). ## Features This template comes with: - Schema - Users table - Admin users table - Endpoints - Sign up with user credentials - Sign in with user credentials - Sign out - Reset password - Get and update user profile - Administration panel - Feature flags support with a UI for management - Code quality tools - RSpec tests - RSpec API Doc Generator - API documentation following [OpenAPI](https://www.openapis.org/) - Docker support ## How to use 1. Clone this repo 1. Install PostgreSQL in case you don't have it 1. Install node. The expected node version is defined in `.nvmrc` file. 1. Install yarn. You can run `corepack enable` to install the required yarn binaries. Corepack is already included in newest node versions. 1. Run `bootstrap.sh` with the name of your project like `./bin/bootstrap.sh --name=my_awesome_project`. 1. Run `yarn install` and `yarn build --watch`. This bundles the JS assets in the administration site using [esbuild](https://github.com/evanw/esbuild). 1. `bundle exec rspec` and make sure all tests pass (non-headless mode) or `HEADLESS=true bundle exec rspec` (headless mode) 1. Run `bin/dev`. 1. You can now try your REST services! ## How to use with Docker 1. Have `docker` and `docker-compose` installed (You can check this by doing `docker -v` and `docker-compose -v`) 1. Run `bootstrap.sh` with the name of your project and the `-d` or `--for-docker` flag like `./bin/bootstrap.sh --name=my_awesome_project -d` 1. Run `./bin/bootstrap.sh --help` for the full details. 1. (Optional) If you want to deny access to the database from outside of the `docker-compose` network, remove the `ports` key in the `docker-compose.yml` from the `db` service. 1. (Optional) Run the tests to make sure everything is working with: `bin/rspec .`. 1. You can now try your REST services! See [Docker docs](./docs/docker.md) for more info ## Dev scripts This template provides a handful of scripts to make your dev experience better! - bin/bundle to run any `bundle` commands. - `bin/bundle install` - bin/rails to run any `rails` commands - `bin/rails console` - bin/web to run any `bash` commands - `bin/web ls` - bin/rspec to run specs - `bin/rspec .` - bin/dev to run both Rails and JS build processes at the same time in a single terminal tab. - `bin/dev` You don't have to use these but they are designed to run the same when running with Docker or not. To illustrate, `bin/rails console` will run the console in the docker container when running with docker and locally when not. ## Gems - [ActiveAdmin](https://github.com/activeadmin/activeadmin) for easy administration - [Arctic Admin](https://github.com/cprodhomme/arctic_admin) for responsive active admin - [Annotaterb](https://github.com/drwl/annotaterb) for documenting the schema in the classes - [Brakeman](https://github.com/presidentbeef/brakeman) for security static analysis - [Byebug](https://github.com/deivid-rodriguez/byebug) for debugging - [Devise](https://github.com/plataformatec/devise) for basic authentication - [Devise Token Auth](https://github.com/lynndylanhurley/devise_token_auth) for API authentication - [Dotenv](https://github.com/bkeepers/dotenv) for handling environment variables - [Draper](https://github.com/drapergem/draper) for decorators - [Factory Bot](https://github.com/thoughtbot/factory_bot) for testing data - [Faker](https://github.com/stympy/faker) for generating test data - [Flipper](https://github.com/jnunemaker/flipper) for feature flag support - [GoodJob](https://github.com/bensheldon/good_job) for background processing - [Jbuilder](https://github.com/rails/jbuilder) for JSON views - [JS Bundling](https://github.com/rails/jsbundling-rails) for bundling JS assets - [Knapsack](https://github.com/KnapsackPro/knapsack) for splitting tests evenly based on execution time - [Letter Opener](https://github.com/ryanb/letter_opener) for previewing emails in the browser - [New Relic](https://github.com/newrelic/newrelic-ruby-agent) for monitoring and debugging - [Pagy](https://github.com/ddnexus/pagy) for pagination - [Parallel Tests](https://github.com/grosser/parallel_tests) for running the tests in multiple cores - [Prosopite](https://github.com/charkost/prosopite) to detect N+1 queries - [Pry](https://github.com/pry/pry) for enhancing the Ruby shell - [Puma](https://github.com/puma/puma) for the web server - [Pundit](https://github.com/varvet/pundit) for authorization management - [Rack CORS](https://github.com/cyu/rack-cors) for handling CORS - [Rails Best Practices](https://github.com/flyerhzm/rails_best_practices) for Rails linting - [Reek](https://github.com/troessner/reek) for Ruby linting - [RSpec](https://github.com/rspec/rspec) for testing - [RSpec OpenAPI](https://github.com/exoego/rspec-openapi) for generating API documentation - [Rswag](https://github.com/rswag/rswag) for serving the API documentation - [Rubocop](https://github.com/bbatsov/rubocop/) for Ruby linting - [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers) for other testing matchers - [Simplecov](https://github.com/colszowka/simplecov) for code coverage - [Strong Migrations](https://github.com/ankane/strong_migrations) for catching unsafe migrations in development - [Webmock](https://github.com/bblimke/webmock) for stubbing http requests - [YAAF](https://github.com/rootstrap/yaaf) for form objects ## Email support This template includes built-in email delivery support via SendGrid, using Rails' `Action Mailer`. Email sending with SendGrid is enabled by configuring the environment variable: ```bash SENDGRID_API_KEY=your_api_key ``` ## Optional configuration - Set your [frontend URL](https://github.com/cyu/rack-cors#origin) in `config/initializers/rack_cors.rb` - Set your mail sender in `config/initializers/devise.rb` - Config your timezone accordingly in `application.rb` - Config CI parallel execution. See [docs](docs/ci.md) - Fullstack development. See [docs](docs/fullstack.md). ## API Docs - [RSpec API Doc Generator](https://github.com/exoego/rspec-openapi) you can generate the docs after writing requests specs - [Rswag](https://github.com/rswag/rswag) you can expose the generated docs See [API documentation docs](./docs/api_documentation.md) for more info ## Code quality With `bundle exec rails code:analysis` you can run the code analysis tool, you can omit rules with: - [Rubocop](https://github.com/bbatsov/rubocop/blob/master/config/default.yml) Edit `.rubocop.yml` - [Reek](https://github.com/troessner/reek#configuration-file) Edit `config.reek` - [Rails Best Practices](https://github.com/flyerhzm/rails_best_practices#custom-configuration) Edit `config/rails_best_practices.yml` - [Brakeman](https://github.com/presidentbeef/brakeman) Run `brakeman -I` to generate `config/brakeman.ignore` ## Code quality and test coverage The project uses SonarQube Community Edition to ensure code quality and monitor test coverage. The configuration can be found in `sonar-project.properties`. To set up SonarQube: 1. Install SonarQube locally (see [CI documentation](docs/ci.md#setting-up-sonarqube) for details) 2. Configure your environment variables: ```bash export SONAR_TOKEN=your_token export SONAR_HOST_URL=http://localhost:9000 ``` 3. Run the analysis: ```bash bundle exec rspec sonar-scanner ``` For more details about the CI process and SonarQube setup, check the [CI documentation](docs/ci.md). ## More linters - [Hadolint](https://github.com/hadolint/hadolint) Install with `brew install hadolint` and run `hadolint Dockerfile*`. Edit `.hadolint.yml` to omit additional rules. ## Claude Code setup This template ships with project-level [Claude Code](https://www.claude.com/product/claude-code) skills under `.claude/skills/` that auto-activate while Claude edits code in your project: - `ruby-conventions` — triggers on Ruby files; applies Rootstrap's Ruby style guide. - `rails-conventions` — triggers on Rails code (controllers, models, migrations, config); applies Rootstrap's Rails conventions. - `rspec-conventions` — triggers on spec files; applies Rootstrap's RSpec style guide. They are distilled from [rootstrap/tech-guides](https://github.com/rootstrap/tech-guides/tree/master/ruby). No setup required — Claude Code loads them automatically based on the files being edited. If you don't use Claude Code, or want to customize the conventions, simply edit or remove the files under `.claude/skills/`. ## Impersonation The `rails_api_base` incorporates a user impersonation feature, allowing `AdminUser`s to assume the identity of other `User`s. This feature is disabled by default. See [Impersonation docs](./docs/impersonation.md) for more info ## Monitoring In order to use [New Relic](https://newrelic.com) to monitor your application requests and metrics, you must setup `NEW_RELIC_API_KEY` and `NEW_RELIC_APP_NAME` environment variables. To obtain an API key you must create an account in the platform. ## Code Owners You can use [CODEOWNERS](https://help.github.com/en/articles/about-code-owners) file to define individuals or teams that are responsible for code in the repository. Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. ## Credits Rails API Base is maintained by [Rootstrap](http://www.rootstrap.com) with the help of our [contributors](https://github.com/rootstrap/rails_api_base/contributors). [](http://www.rootstrap.com)