A MVP ready template for Rails apps.
Everything used in this repo is open source, free, or optional.
This repo focuses on getting your project setup ASAP with all the tooling to start deploying from your first commit.
- User Accounts & Authentication: Devise
- Feature Switching with a UI: flipper
- Admin Dashboard UI: ActiveAdmin
- Secrets Management: dotenv
- Livereload for Development: Guard
- Upgraded Testing Suite: RSpec, faker, factory_bot
- Static Analysis: Brakeman, Rubopcop
- Continuous Integration: CircleCI, CodeClimate
- Code Coverage Reporting with a UI: simplecov
- Getting started
- Local setup
- Feature Switches
- Admin Dashboard
- Testing
- Code Coverage
- Static Analysis
- Deployment
- Continuous Integration
- Mailer Setup
- Custom Domain, DNS, & SSL - coming soon
To setup the repo locally start by cloning it locally:
git clone https://github.com/TristanToye/rails-template.git
cd rails-template
Next you need to install all the dependiencies:
- ruby 2.7.4
- rails 6
- node 8.16.0
- postgres 10
To accomplish this I recommend the following:
- install homebrew
- install RVM
- install ruby 2.7.4 with RVM
- install rails 6
- install NVM
- install node 8.16.0 with NVM
- install postgres 10
This guide walks you through it in details: http://railsapps.github.io/installrubyonrails-mac.html
The only issue you might run into is setting up Postgres. If you use the recommend Postgres app (do this). When installing the pg gem you will need to run the following:
gem install pg -- --with-pg-config=/Applications/Postgres.app/Contents/Versions/10/bin/pg_config
Or you can add the app's config to your ~./bash_profile:
export PATH="/Applications/Postgres.app/Contents/MacOS/bin:$PATH"
Once you have everything installed, run bundler to get our gems setup:
$ bundle install
For most credentials we want to use the Rails 5.2 credential management. This article explains it well with examples: https://medium.com/cedarcode/rails-5-2-credentials-9b3324851336
To get started here go delete my credentials located at /config/credentials.yml.enc.
We will start by adding a secret_key_base to this file:
$ rake secret
840f20e6084666b7aabe9d94...
$ EDITOR="code --wait" rails credentials:edit
# In the credentials file add the following
secret_key_base=840f20e6084666b7aabe9d94...
We also likely want to handle some environment variables locally. We use a git-ignored file to load them when the app starts.
Create a new file .env in the root of the repo. This will load any environment variables you might need to set in the future.
Makes sure postgres is running and setup your database:
$ rails db:setup db:schema:load
Now you should be able to start your rails app and load it in your browser at http://localhost:3000:
# to start with spring and all the goodies
$ guard
# OR to start just the rails server
$ rails s
This app uses the lovely Flipper gem to manage features.
It is protected with a basic auth. Add the following to your credentials:
$ EDITOR="code --wait" rails credentials:edit
# In the file
flipper:
user_name: YOUR_USERNAME
password: YOUR_PASSWORD
Then navigate to http://localhost:3000/flipper/features & enter your credentials.
Add the feature show_auth and enable it for everyone. This should show the login/signup links on the index of the app.
This app uses the ActiveAdmin gem to generate an admin UI.
This is already up and running as part of your app! You just need to create an admin user to access it.
Signup on your app and try navigate to http://localhost:3000/admin - you should be unable to access it yet.
You need to set the boolean column admin on your user account to true.
This is pretty fast to do from the rails console:
$ rails c
> User.find_by(email: 'YOUR_ACCOUNTS_EMAIL').update(admin: true)
Now navigate to http://localhost:3000/admin and you should see the blank admin UI.
You will need to read the docs to find out how to extend this for your own purposes.
You can start your app, and run your livereloading test suite with one command: $ guard
Once guard is running, simply push return to run all tests & static checks.
For more info check the Guard related gems in the Gemfile.
To run the test suite on its own: $ rspec
For more info check the RSpec related gems in the Gemfile.
Code coverage is setup with simplecov.
Run your test suite: $ rspec
In your apps directory open ./coverage/index.html in a browser to view a UI for the code coverage of your app.
If you start the app with the $ guard command the code coverage will update coverage on each saved change.
There are multiple gems integrated in this app for static analysis.
These all run as part of the $ guard command during development.
Rubocop: ruby style guide, read more here. To use run: $ rubocop.
Brakeman: security analysis, read more here. To use run: $ brakeman.
We are going to deloy this Heroku
Create an account and create your first app. Add to your app the free tier of Heroku Postgres & Papertrail.
Next install the CLI locally & login: https://devcenter.heroku.com/articles/heroku-cli
Add your .env variables to the settings tab on your Heroku app.
You will also need to add the contents of your config/master.key file to Heroku as RAILS_MASTER_KEY in the same setting location to allow Heroku to use your credentials.
Deploy your repo from the deploy tab by connecting your github account and selecting the repo OR follow the linked guide below to deloy directly from your machine.
Finally, run the following to setup you database on the Heroku Postgres instance:
heroku run rails db:schema:load -a APP_NAME
Heroku has a great set of documentation on how to get setup: https://devcenter.heroku.com/articles/getting-started-with-rails5
This section could be expanded, but out of ther box there are some basic tools in place.
Use this for CI with Heroku to ensure all your tests pass before deploying a new version, before merging your latest PRs etc.
You get one free linux box to run tests on: https://circleci.com
Connect your github account and select the repo to start running tests.
By default this is configured to push code coverage to CodeClimate (see below).
If you don't want to use CodeClimate comment out lines 94-96 from .circleci/config.yml:
- send-code-coverage:
requires:
- build-rails
Once setup and you have your tests passing you can enable the option on Heroku to Wait for CI to pass before deploy from the Deploy tab of you app.
Use this for tracking issues, code coverage etc.
Free for open source: https://codeclimate.com/
Sign in with github & connect your repo.
Add this environment variable to CirclCi: CC_TEST_REPORTER_ID
I highly recommend installing the browser extension: https://chrome.google.com/webstore/detail/code-climate/phgahogocbnfilkegjdpohgkkjgahjgk
If you have a gmail account this is a simple solution. You might want to create a new Gmail just for this app.
Add to your credentials the following:
$ EDITOR="code --wait" rails credentials:edit
# In the file opened add
email:
host: smtp.gmail.com
user_name: YOUR_GMAIL_EMAIL
password: YOUR_GMAIL_PASSWORD
You will require a real domain that you own to send email from.
Sign up with a provider like https://sparkpost.com for a free plan.
Verify your domain with them.
Select SMTP sending and get their config.
Add to your credentials the following:
$ EDITOR="code --wait" rails credentials:edit
# In the file opened add
email:
host: HOST_DOMAIN
user_name: PROVIDED_USER_NAME
password: PROVIDED_PASSWORD