Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/archonic/limestone

Boilerplate Rails 6 SaaS application with Webpack, Stimulus and Docker integration.
https://github.com/archonic/limestone

boilerplate devise docker flipper limestone rails rspec saas searchkick sidekiq stimulus stripe webpack

Last synced: 5 days ago
JSON representation

Boilerplate Rails 6 SaaS application with Webpack, Stimulus and Docker integration.

Awesome Lists containing this project

README 

        
# Limestone

[![](https://circleci.com/gh/archonic/limestone.svg?style=svg)](https://circleci.com/gh/archonic/workflows/limestone/tree/master)



Limestone is a boilerplate SaaS app built with Rails 6 on Ruby 2.7.2 and has an opinionated integration with NPM using [Webpacker](https://github.com/rails/webpacker) and [Stimulus](https://stimulusjs.org/).



## 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](https://github.com/pay-rails/pay)  

v0.4 uses ruby 2.7.2



See more in the [changelog](https://github.com/archonic/limestone/blob/master/CHANGELOG.md).



## The Stack

The [gemset](https://github.com/archonic/limestone/blob/master/Gemfile) 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](https://github.com/heartcombo/devise/wiki/How-To:-Add-:confirmable-to-Users) installed and configured.

* Emails for welcome, receipt, refund, subscription renewing and payment action required.

* [letter_opener](https://github.com/ryanb/letter_opener) and [letter_opener_web](https://github.com/fgrehm/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](https://sendgrid.com/) is configured and ready to use once your API keys are set in ENV.

* Direct cloud uploading with [ActiveStorage](https://edgeguides.rubyonrails.org/active_storage_overview.html). 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](https://fontawesome.com/v4.7.0/icons/) 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](https://github.com/jnunemaker/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](https://docs.docker.com/engine/installation/) and [Docker Compose](https://docs.docker.com/compose/install/)

* A [Stripe](https://dashboard.stripe.com/register) account and a [Stripe API Key](https://stripe.com/docs/keys).



### Test

* [Codeship](https://codeship.com/) files are in place - just create an account and integrate with your repo. You will need to create your [codeship.aes file](https://documentation.codeship.com/pro/builds-and-configuration/environment-variables/#downloading-your-aes-key), [install jet](https://documentation.codeship.com/pro/jet-cli/installation/) and run `jet encrypt .env .env.encrypted`.

* [CircleCI](https://circleci.com/) 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](https://edgeguides.rubyonrails.org/active_storage_overview.html#setup).

* Because Docker is already configured, you may want a Kubernetes host ([GKE](https://cloud.google.com/kubernetes-engine/), [AWS](https://aws.amazon.com/kubernetes/) or [DigitalOcean](https://www.digitalocean.com/products/kubernetes/)).



## 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.



5. 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.



6. Visit [http://localhost:3000](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](https://stripe.com/docs/testing#cards) when prompted or by visiting /subscribe.



7. See the [Limestone Wiki](https://github.com/archonic/limestone/wiki) more about [development with Docker](https://github.com/archonic/limestone/wiki/Development-with-Docker)



### Note About Flipper / Public User Registration

1. The [Flipper gem](https://github.com/jnunemaker/flipper) 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.