Limestone

Limestone is a boilerplate SaaS app built with Rails 6 on Ruby 2.7.2 and has an opinionated integration with NPM using Webpacker and Stimulus.

Vote!

Help decide future features and changes for Limestone with this poll: https://www.strawpoll.me/42684734/

Versions

Versioning in this repo in intended to maintain and modernize the boilerplate. New versions are not intended to update existing forks, although looking through the commits serves as a good upgrade resource.

v0.1 is Rails 5.2
v0.2 is Rails 6
v0.3 introduces the Pay gem
v0.4 uses ruby 2.7.2

See more in the changelog.

The Stack

The gemset has been chosen to be modern, performant, and take care of a number of business concerns common to SaaS.

Features

• Free trial begins upon registration without credit card. Number of days is configurable with ENV var.
• Subscription management. Card update form, switch plan form and cancel account button.
• Devise confirmable installed and configured.
• Emails for welcome, receipt, refund, subscription renewing and payment action required.
• letter_opener and letter_opener_web installed and configured. Visit /admin/letter_opener in development to see emails sent.
• Mail sends through Sidekiq with deliver_later for production. Sendgrid is configured and ready to use once your API keys are set in ENV.
• Direct cloud uploading with ActiveStorage. Lazy transform for resizing. Demonstrated with user avatars.
• Icon helper for user avatars with fallback to user initials.
• Icon helper for Font Awesome 4.7 icons.
• Administrate dashboard lets you CRUD records. Easy to add more models and customize as you like. Visit /admin/.
• Impersonate users through Administrate dashboard.
• Pretty modals using Bootstrap integrated into rails_ujs data-confirm. Demonstrated with cancel account button.
• Banner with a link to billing page users that are past due.
• Opinionated search integration using Elasticsearch via Searchkick. Gem is in place but integration is up to you.
• Feature control using the Flipper gem. Demonstrated with the public_registration feature.
• 84% RSpec test coverage.
• Solargraph (language server for code-aware auto-completions) configured in docker-compose.yml. Just point to localhost:7658 in your solargraph extension in your code editor.

Notes

• RSpec controller tests have been omitted in favour of requests tests.
• You can run tests locally with docker-compose run web rspec

Pre-requisites

Development

• Install Docker and Docker Compose
• A Stripe account and a Stripe API Key.

Test

• Codeship files are in place - just create an account and integrate with your repo. You will need to create your codeship.aes file, install jet and run jet encrypt .env .env.encrypted.
• CircleCI files are in place - just create an account and integrate with your repo.
• NOTE Limestone expects your product prices to have trial days > 0. If you don't create a trial, testing will get the error Pay::Error: This customer has no attached payment source or default payment method..
• You could also just run test locally with docker-compose run web rspec or docker-compose exec web rspec if you've already run docker-compose up.

Production

• A cloud storage account compatible with ActiveStorage.
• Because Docker is already configured, you may want a Kubernetes host (GKE, AWS or DigitalOcean).

Getting Started

1. Clone this repository at the most recent tag and cd into it:

   git clone -b 'v0.3' --single-branch --depth 1 https://github.com/archonic/limestone.git
   cd limestone
   

2. Make a copy of .env-example named .env:

   cp .env-example .env
   

3. Update the .env file - running the project requires you change the following:

   • STRIPE_API_KEY
   • STRIPE_PUBLISHABLE_KEY
   • STRIPE_SIGNING_SECRET (This can be something random)

   You probably want to update the ADMIN_* environment variables. If you want a different COMPOSE_PROJECT_NAME and database name, now is the best time to do that.

4. Run docker-compose run web yarn install --pure-lockfile to download images, build your development image and install node_modules. This will take a while.

5. Run docker-compose up to run your project and it's dependencies.

6. Once everything is up, run docker-compose exec web rails db:prepare to create DB, load schema and seed. Seeding will also create your plan(s) in Stripe.

7. Visit http://localhost:3000 and rejoice :tada: You can login using the Admin user defined in .env. Keep in mind your admin doesn't have active billing. Enter a test card when prompted or by visiting /subscribe.

8. See the Limestone Wiki more about development with Docker

Note About Flipper / Public User Registration

1. The Flipper gem controls feature flagging and provides a UI. Visit the /admin/flipper.
2. The feature called public_registration has been created for you (during seeding). You can enable/disable this to control user registration :clap:

Setting up production

A wiki will be written about this. Feel free to help out here if you're familiar with Docker/Kubernetes.