A full-featured, production ready, and easy to understand API boilerplate for the Grape framework.

• Local development with Docker and Docker Compose.
• Automatic Puma reloading locally with guard-puma.
• ActiveRecord with otr-activerecord.
• Swagger API documentation with grape-swagger.
• User authentication with bcrypt using jwt.
• Model pagination with api-pagination.
• Standard security headers with secure_headers.
• Monitoring and alerting with Sentry andPrometheus.
• Comprehensive RSpec test suite and code coverage.
• Easy fly.io deployment.

• Generate a key pair for local JWT authentication.

cd grape-api-boilerplate/config/jwt
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

• Build and run with Docker Compose.

docker compose up --build

• Setup and seed the database.

docker compose exec app bundle exec rake db:setup

• Visit your API at http:https://localhost:3000

• Run the create users Rake task.

docker compose run --rm app bundle exec rake users:create

• Enter your desired email, username, and password.

• Run linting and tests.

docker compose run --rm -e RACK_ENV=test app bundle exec rake

When running locally, you can visit http:https://localhost:3000/public/swagger/index.html to view your Swagger API documentation.

You can easily deploy to fly.io with a few steps.

• Login and create a new fly.io application.

flyctl auth login
flyctl launch

• Create a new free tier PostgreSQL database.

flyctl postgres create
flyctl postgres attach --app <my-app-name> <my-app-name>-db

• Generate a key pair for use with fly.io JWT authentication.
  • NOTE: Ensure that you keep the private key secret and out of your git repository!

ssh-keygen -t rsa -b 4096 -m PEM -f fly_jwtRS256.key
openssl rsa -in fly_jwtRS256.key -pubout -outform PEM -out fly_jwtRS256.key.pub

• Set necessary environment variables using flyctl, for example flyctl secrets set RACK_ENV=production. You should at least set the secrets below.

RACK_ENV=production
GRAPE_BOILERPLATE_SETTINGS__JWT__PRIVATE_KEY=<contents of above fly_jwtRS256.key>
GRAPE_BOILERPLATE_SETTINGS__JWT__PUBLIC_KEY=<contents of above fly_jwtRS256.key.pub>

• Deploy your code to your new fly.io app.

flyctl deploy

• Create an example user.

flyctl ssh console
cd /usr/src/app
bundle exec rake users:create

• Or alternatively, seed your database with a couple of users and widgets for testing.

flyctl ssh console
cd /usr/src/app
bundle exec rake db:seed

• Use your new API!

You can enable Sentry for your API by setting sentry.enabled in your settings file(s).

• Update the setting in app/settings/<environment>.yml.

sentry:
  enabled: true

• Add your Sentry DSN to a SENTRY_DSN environment variable.

• See the Sentry Rack guide for more.

You can enable Prometheus metrics for your API by setting prometheus.enabled in your production settings file.

• Update the setting in app/settings/production.yml.

prometheus:
  enabled: true

• The default middleware will provide some basic metrics out of the box. See the Ruby Prometheus client library documentation for advanced usage.

Note: Prometheus metrics should not be exposed publicly! Please ensure you know what you're doing before enabling this feature in your environment.

There's an instance of this API running at https://grape-api-boilerplate.fly.dev/. If it doesn't respond right away, give it a few seconds to awake from the free tier hibernation.

# Hello world!
curl https://grape-api-boilerplate.fly.dev/api/v1/hello | jq .

# Authenticate with the test user.
token=$(curl -XPOST \
  -H "Content-Type:application/json" \
  -d '{"username":"grape_user","password":"grape_user1"}' \
  https://grape-api-boilerplate.fly.dev/api/login | jq -r '.token')

curl -H "Authorization: Bearer ${token}" \
  https://grape-api-boilerplate.fly.dev/api/v1/widget | jq .

Build a production ready image with the Dockerfile and deploy to your favorite platform.

docker build -t grape-api-boilerplate:latest .

Contributions are welcome! See CONTRIBUTING.

MIT License. See LICENSE for details.