Potassium
A Rails application generator from Platanus, inspired by Suspenders.
Installation
You have to install Potassium globally:
$ gem install potassium
Usage
Starting a new project from scratch
Use the potassium create
command to create a new project:
$ potassium create <project-name>
Please note:
- Potassium will perform a version check before running to ensure that you are using the latest potassium.
- If you feel that it's too slow, you may need to update rubygems:
gem update --system
.- Potassium uses node under the hood, so a check will also be performed to ensure you are running the supported version.
Platanus Configutarion
In case you want to use the Platanus Configuration you should use the following command:
$ potassium create <project-name> --platanus-config
This will create a project with the following configuration:
database
:'postgresql'
local
:'es-CL'
email_service
:'sendgrid'
devise
:true
devise-user-model
:true
admin
:true
vue_admin
:true
pundit
:true
api
:true
storage
:'shrine'
heroku
:true
background_processor
:true
draper
:true
schedule
:true
sentry
:true
front_end_vite
:true
google_tag_manager
:true
test
:true
spring
:true
The remaining question will be asked as usual.
Running from Repository
If you cloned this repository and are running the gem using the bin script (potassium/bin/potassium create
), take careful note of the gem versions that are used. Sometimes the local Rails version is used instead of the one specified in the gemspec. Remove your local Gemfile.lock after pulling from the repository to help prevent these issues.
Adding recipes to an existing project
Use the potassium install
command to add a recipe to a project:
$ potassium install devise
You can force an already installed recipe by passing the --force
argument
$ potassium install devise --force
You can run the command on its own to view all the available recipes and select one:
$ potassium install
What's inside Potassium?
Potassium Rails apps includes the following gems and technologies:
- dotenv for loading environmental variables in development
- Yarn for frontend assets packages
- EditorConfig for keeping all our editor configurations the same
- pry and pry-byebug for a less painful debugging experience
- RSpec for unit and integration testing
- FactoryBot for test factories
- Guard for continuous testing and other watch-related tasks
- AWS-SDK for file uploads, sdks, etc and because we use AWS
- Puma to serve HTTP requests
- Rack Timeout to abort requests that are taking too long
- Tzinfo-Data for updating timezone information
- Faker for creating development data
- Scout for monitoring performance
- Mjml for mails style
- Bullet to identify eager loading (N+1 queries)
The following optional integrations are also added:
- PostgreSQL or MySQL for the database
- Devise for authentication
- ActiveAdmin for admin interfaces
- ActiveAdminAddons for some help with ActiveAdmin
- Pundit for role-based authorization
- Sidekiq a simple, efficient background processing for Ruby
- Sidekiq-scheduler to run scheduled processes
- Mailing configuration for AWS SES and Sendgrid with recipient interceptor support
- Sentry to monitor exceptions and errors
- Vue.js or Angular 2 for frontend development
- Google Tag Manager for analytics
- Creates the Github repository of your choice for the project. A local git repository will always be created.
A few more things are added to the project:
- A low database connection pool limit
- Setup continuous integration in CircleCI to run tests
- A
bin/setup
script to setup things on a newly cloned project - A
bin/cibuild
script to run continuous integration build on CI - A
db:fake_data:load
rake task to load fake data for development
API support
The optional API support includes:
- Responders for dry-ing our api controllers
- Versionist for some flexible api versioning
- ActiveModel::Serializers for record serialization
- Simple Token Authentication for stateless API authentication
Heroku
When you choose to deploy to heroku a few extra things are added for the project.
- Adds a Procfile to define the processes to run in heroku
- Setup continuous integration using docker and herokuish to maintain better parity between testing and production environments
- Adds a
bin/release
file with the release phase script to run specific tasks before the app is deployed completely, for examplerails db:migrate:with_data
- Adds a
.buildpacks
file with the default buildpacks to use. It use the following buildpacks:
index | buildpack | description |
---|---|---|
1. | nodejs | to support javascript package management with yarn and webpack based asset compiling |
2. | ruby-version | to support the use of .ruby-version file to instruct heroku which ruby version to use |
3. | ruby | the base buildpack to run ruby applications |
Also the heroku applications are created
- Creates a
staging
andproduction
applications - Creates a pipeline and assign the above application to the
staging
andproduction
stages - Setup initial configuration variables
- Set the application buildpack to the multi-buildpack
You'll need to manually
- Connect the pipeline with the github repository
- Assign a branch to each stage for auto deployments
- Enable deploy after CI pass
Continuous Integration
In order to CicleCI start building the project on each push you need tell circle ci. Go to https://circleci.com/add-projects, choose the repository from the list and hit Build Project
ReviewDog
In order to enable code linting via CircleCI and ReviewDog, you need to activate the Only build pull requests option under the Advanced settings
section for your project.
Development Tools
Creating a new Test project from scratch
This is useful when you are adding new recipes to Potassium, and you want to use the potassium create
command, to check the new functionality without pain.
To achieve this you need to run, In the Potassium's root path, the bin/potassium_test create
instead of potassium create
command.
This command, will do the same as potassium create
but first:
- Will drop any existent database of the test app
- Will remove the directory containing a previous version of the test app
It's important to remember that bin/potassium_test create
:
- Does not receive an
app_path
param. It always creates the test project inside/tmp/dummy_app
- Can receive the same options as
potassium create
- Runs with options with a default value. This is to avoid the "asking part" of the creation process. You need to enable what you want to test like this:
$ bin/potassium_test create --clockwork
Publishing
On master branch.
- Change
VERSION
inlib/potassium/version.rb
- Change
Unreleased
title to current version inCHANGELOG.md
- Commit new release. For example:
Releasing v6.3.0
- Create tag. For example:
git tag v6.3.0
- Push tag:
git push origin v6.3.0
Contributing
If you want to add functionality please go to the contributing
Credits
Thank you contributors!
potassium is maintained by platanus.
License
Potassium is © 2014 Platanus, SPA. It is free software and may be redistributed under the terms specified in the LICENSE file.