Limestone

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

Limestone assumes you want each user to pay for access to your SaaS. If instead you want users to belong to accounts and have billing scoped to accounts, try Limestone Accounts.

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 serve as a good upgrade resource.

v0.1 is Rails 5.2
v0.2+ is Rails 6
v0.3 introduces the Pay gem
See CHANGELOG.md for more details.

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.
• Emails for welcome, billing updated, invoice paid, invoice failed and trial expiring. All except welcome are controlled by Stripe webhooks.
• Mail sends through Sidekiq with deliver_later. Sendgrid is configured, or you can use plain SMTP auth for development.
• Direct uploading to S3 with ActiveStorage. Lazy transform for resizing. Demonstrated with user avatars.
• Icon helper for user avatars with fallback to circle with user initials.
• Icon helper for Font Awesome 4.7 icons.
• Administrate dashboard lets you CRUD records (ex: users). Easy to add more 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.

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 trail, 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 🎉 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 👏

Setting up production

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