Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 2 additions & 187 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,188 +1,3 @@
# Rails API Template
# Rails API Template - test fork CI

[![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.

## 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).

[<img src="https://s3-us-west-1.amazonaws.com/rootstrap.com/img/rs.png" width="100"/>](http://www.rootstrap.com)
This is a test commit to validate CI behavior for fork PRs.
Loading