Skip to content

Latest commit

 

History

History
192 lines (129 loc) · 5.58 KB

README.md

File metadata and controls

192 lines (129 loc) · 5.58 KB
Raw

grape-api-boilerplate

Tests Rubocop codecov

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

Features

Running

  • 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

Creating a user

  • Run the create users Rake task.
docker compose run --rm app bundle exec rake users:create
  • Enter your desired email, username, and password.

Tests

  • Run linting and tests.
docker compose run --rm -e RACK_ENV=test app bundle exec rake

API documentation

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

Production

fly.io

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!

Sentry

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.

Prometheus

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

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

Want to play around?

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 .

Docker

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

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

Contributing

Contributions are welcome! See CONTRIBUTING.

License

MIT License. See LICENSE for details.