Rails API Base

How to use

1. Clone this repo
2. Install PostgreSQL in case you don't have it
3. rspec and make sure all tests pass
4. rails s
5. You can now try your REST services!

Optional configuration

• Set your FRONTEND_URL env
• Set your mail sender in config/initializers/devise.rb
• Config your timezone accordingly in application.rb.

---

Generators

This base has some generators to help you get started faster:

• bin/rails g address to generate an address model (be sure to check out the generated spec/factories/addresses.rb, and modify the addressable field)
• bin/rails g heroku to generate a heroku configuration
• bin/rails g sentry to generate a sentry configuration (be sure to set the SENTRY_DSN env variable)

---

CI

This base uses Github Actions by default as the CI tool.

Github Actions Setup

There's no need to setup anything, just push your code and it will run the tests.

---

Deployment

Deploy to AWS using Kamal

Kamal is a tool that helps you to deploy in any bare server, like the ones provided by aws, gcp, digital ocean, etc. It uses docker + traefik + letsencrypt to provide a secure and easy to use environment.

Prerequisites

Setup VM

# update linux
sudo apt update
sudo apt upgrade -y
# install and setup docker
sudo apt install -y docker.io curl git
sudo usermod -a -G docker ubuntu # change `ubuntu` to the username provided by your cloud provider

# Create directories + files necessary for traefik + letsencrypt management
sudo mkdir /letsencrypt
sudo touch /letsencrypt/acme.json
sudo chmod 600 /letsencrypt/acme.json

important: Make sure http and https ports are open.

Setup DNS

You need to have a domain name and point it to your server IP. The server IP must be configured in /config/deploy.yml and /config/deploy.staging.yml. So, access to your DNS manager, and create an A record pointing to your server IP.

Setup SSL

There's no need to setup SSL certificates, traefik will do it for you.

Setup the container registry

You need to have a container registry to push your images. You can use AWS ECR.

Setup AWS secrets

You need to setup the secret manager in AWS, and add the following secrets: There are 2 secret groups, one for staging and one for production. The secrets are the same, but the values are different. By default the secret groups names are:

• staging/RailsApi
• production/RailsApi

If you want to use different names, you can change them in .env.erb and .env.staging.erb.

The secrets are:

• SERVER_HOST (the server IP to deploy to)
• JWT_SECRET (the secret used to sign JWT tokens)
  • You can generate one with bin/rails runner "puts SecureRandom.hex(32)"
• FRONTEND_URL (the frontend url)
• MAILER_SENDER (the email sender, e.g. [email protected])
• DATABASE_URL (the database url, e.g. postgresql://user:password@somehost:5432/dbname)
• REDIS_URL (the redis url, e.g. redis://user:password@somehost:6379/0)
• S3_ACCESS_KEY_ID (the s3 access key id)
• S3_ACCESS_KEY (the s3 access key)
• S3_REGION (the s3 region)
• S3_BUCKET (the s3 bucket)
• SIDEKIQ_PASSWORD (the sidekiq password)
• SIDEKIQ_REDIS_URL (the sidekiq redis url. This can be the same as the REDIS_URL)

[OPTIONAL] Create a VM for remote docker image building

Create a new VM in your cloud provider, and run:

sudo apt update
sudo apt upgrade -y
# install and setup docker
sudo apt install -y docker.io curl git
sudo usermod -a -G docker ubuntu # change `ubuntu` to the username provided by your cloud provider

Then change config/deploy.yml and config/deploy.staging.yml to build in that VM IP.

Setup local environment for deploying from your machine

Install necessary tools

gem install kamal
brew install docker
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Log in to awscli

aws configure # enter your credentials

Setup SSH keys

ssh-add /path/to/your/key.pem

Add necessary env variables

Add to your .env file

AWS_ACCOUNT_ID=your_account_id
AWS_REGION=your_region

Deploy

Deploy to staging

kamal envify -d staging
kamal deploy -d staging

Deploy to production

kamal envify
kamal deploy

Deploy to Heroku

The repository has a generator that creates all the necessary files for deploying into heroku. Just run:

bin/rails g heroku --app-name=<your-heroku-app-name>

The cost of deploying this to heroku is 18 USD/month.

Heroku configuration files

• app.json with the following configuration:

  • The app name: rails-api
  • The app description: A minimal ruby on rails api
  • Add-ons:
    • Heroku Postgres (mini, 5 USD/month)
    • Heroku Redis (mini, 3 USD/month)
    • Papertrail (choklad, 0 USD/month)
  • Dynos:
    • web
      • command: bin/rails s -p $PORT:-3000 -e $RAILS_ENV:-development
      • size: Basic (5 USD/month)
    • worker
      • command: bin/sidekiq -e $RAILS_ENV:-development
      • size: Basic (5 USD/month)
  • Buildpacks:
    • Apt (uses the file Aptfile to install native packages)
    • heroku/ruby (ruby)

• Procfile with the following configuration:

  • web: bin/rails s -p ${PORT:-3000} -e ${RAILS_ENV:-development}
  • worker: bin/sidekiq -e ${RAILS_ENV:-development}
  • release: release.sh

• Aptfile (used by apt buildpack) with the following packages:

  • libvips-dev
  • libvips-tools
  • libvips42
  • libglib2.0-0
  • libglib2.0-dev
  • libjpeg-turbo8-dev
  • libpng-dev
  • libtiff-dev
  • giflib-tools
  • libwebp-dev
  • libpoppler-dev

CD

CD to AWS using Kamal

Because of stability issues, continuous deployment with kamal when merging a PR is not recommended.

There's a Github Actions workflow which is triggered by Manual Dispatch and it will deploy to staging/production with the selected branch.

Setup secrets

Head over to repository -> actions -> secrets and add the following secrets:

Staging secrets

• DOCKER_REMOTE_BUILDER_IP (only if you have a remote docker image builder)
• DOCKER_REMOTE_BUILDER_PRIVATE_KEY (only if you have a remote docker image builder)
• SSH_STAGING_PRIVATE_KEY (the private key to connect to your staging server)
• AWS_ACCESS_KEY_ID (the aws access key id to connect to your staging server)
• AWS_SECRET_ACCESS_KEY (the aws secret access key to connect to your staging server)
• AWS_REGION (the aws region to connect to your staging server)
• AWS_ACCOUNT_ID (the aws account id where the ECR docker image is hosted)

Production secrets

• DOCKER_REMOTE_BUILDER_IP (only if you have a remote docker image builder)
• DOCKER_REMOTE_BUILDER_PRIVATE_KEY (only if you have a remote docker image builder)
• SSH_PRODUCTION_PRIVATE_KEY (the private key to connect to your production server)
• AWS_ACCESS_KEY_ID (the aws access key id to connect to your production server)
• AWS_SECRET_ACCESS_KEY (the aws secret access key to connect to your production server)
• AWS_REGION (the aws region to connect to your production server)
• AWS_ACCOUNT_ID (the aws account id where the ECR docker image is hosted)

CD to Heroku

Go to Heroku and setup the app to auto-deploy from the main branch, and make sure to enable the option Wait for CI to pass before deploy.

Credits

rails_api is maintained by GoGrow with the help of our contributors.