Skip to content

Latest commit

 

History

History
384 lines (291 loc) · 25.2 KB

README.md

File metadata and controls

384 lines (291 loc) · 25.2 KB
Raw

Contributors Forks Stargazers Issues MIT License

Kowl Gem Version


Kowl Header Image

Kowl (Ruby gem)

Kowl is a Rails (v6.*) based opinionated application generator used to get started quick. It's purpose is so you can focus on building your application rather spending days setting up the basic gems every time.

· Report Bug · Request Feature

Table of Contents

About The Project

Kowl is tool to easily generate a Rails (~> 6) application with a number of configurations, templates, and generators applied. That way your're not spending days running through gems and documentation to get an application setup. (This can include setting up bootstrap, devise, sidekiq, linters, dockerizing your application, and various other steps)

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

Requires a minimum of:

  • Ruby >= 2.5
  • Rails >= 2.6
# If using RVM
rvm install 2.6.5
rvm use 2.6.5 --default

Installation

1. Install the required dependencies

Depending on the options you want to use when generating an application your dependencies will vary.

  • autogen autoconf cmake libtool make v8 - For nokogiri, sassc, and various C based ruby gems.
  • docker - If you want to build a docker image using the application specific generated Dockerfile.
  • git - Is generally required for installing rubygems anyways.
  • graphviz - For generating an applications ERD (unless you skip generating an ERD for your application --skip_erd)
  • jemalloc - Optional, but helps with improving rubies memory allocation. (If using RVM you can install a ruby version to utilize jemalloc using: rvm install 2.6.5 -C --with-jemalloc)
  • imagemagick - If you plan on using ActionText/Trix you'll want imagemagick or vips for processing image uploads
  • libsodium - If you wish to encrypt particular PII user attributes (using the lockbox gem by generating an application with the encrypt flag --encrypt)
  • node && yarn - Generally any new rails app requires node and yarn for installing and transpiling JS dependencies.

Dependant on the database your application will be using, you'll also need to install their required C adapters

  • PostgreSQL - postgresql

  • Oracle - instantclient-basic && instantclient-sdk

    brew update
brew tap InstantClientTap/instantclient

brew install instantclient-basic instantclient-sdk

  • SQLserver - freetds

2. Install ruby gem

gem install kowl

Usage

Usage:
  kowl AppName

Options:
-d [--database=DATABASE]                     # If you want to use a specific database for the application (builds with sqlite3 until you are ready)
                                             # Default: sqlite3
   [--docker_distro=DISTRO]                  # Specify what docker distro to use for the application (alpine, debian)
                                             # Default: alpine (If you specify to use Oracle your distro will default to Debian)
   [--encrypt]                               # If you want encrypt various user data (using lockbox)? (For GDPR compliance)
                                             # Default: false (This requires you to install libsodium in order to encrypt the user data)
   [--framework=CSSFRAMEWORK]                # If you want to generate views using a specific CSS framework (bootstrap, semantic, none)
                                             # Default: bootstrap
   [--git_repo=REPO_NAME]                    # If you've already created a gitlab repo, specify the repo and and it will be added.
                                             # ie: https://github/username/REPO_NAME.git
                                             # Default: nil
   [--mailer=MAILER]                         # Which transactional mailer you want to use in production (postmark or sparkpost)?
                                             # Default: sparkpost (unless you specify to --skip_mailer, than neither will be used)
   [--noauth]                                # If you would like to skip adding devise and pundit to the application
                                             # Default: false
   [--simpleform]                            # Do you want your application to use simpleform to generate forms
                                             # Default: false
   [--skip_docker]                           # If you want your application to skip generating any docker files (Dockerfile, docker-compose.yml, and .dockerignore)
                                             # Default: false
   [--skip_erd]                              # If you want to skip generating an ERD for your application (requires graphviz to be installed)
                                             # Default: false
-G [--skip_git]                              # Do you want the generator to skip creating initializing and commit files to git
                                             # Default: false
   [--skip_javascript]                       # Skip adding javascript (webpacker) to the application
                                             # Default: false
   [--skip_mailer]                           # Do you want to skip setting up a transactional mailer (see --mailer option above)?
                                             # Default: false
   [--skip_pagination]                       # Do you want to skip using pagination with your application?
                                             # Default: false
   [--skip_pry]                              # Do you want to skip using pry with your applications rails console?
                                             # Default: false
   [--skip_sidekiq]                          # Do you want to skip setting up sidekiq (for background jobs, mailers, etc.)
                                             # Default: false
   [--skip_spring]                           # If you hate spring and want to skip using it with your application.
                                             # Default: false
-T [--skip_tests]                            # Do you want your application to skip building with tests
                                             # Default: false
   [--skip_turbolinks]                       # If you want to skip adding turbolinks to your applications assets
                                             # Default: false
   [--template_engine=ENGINE]                # Assign a template_engine to use for the applications views (erb, slim, haml)
                                             # Default: erb
   [--test_engine=TEST_ENGINE]               # If you want to generate the application using a specific test suite (minitest, RSpec, none)
                                             # Default: rspec
   [--uuid]                                  # Enable setting as database primary keys as UUIDs (Only while using PostgreSQL)
                                             # Default: false (NOTE: This feature is still under development)
-W [--webpack=JSFRAMEWORK]                   # If you want initialize to webpacker with a specific JS framework (react vue angular elm stimulus)
                                             # Default: nil

Examples:

kowl AppName

Generate an application using sqlite3, with a name of "AppName", requiring authentication, using RSpec, and using bootstrap.

kowl AppName --database=oracle --simpleform --noauth

This will generate an application using the Oracle database, using simple_form, and not requiring any sort of authentication (anyone can hit this app.)

kowl AppName --simpleform --template_engine=slim

This will generate an application defaulting to sqlite3, using simple_form, the Slim template engine, with pagination, and requiring authentication to load the application.

kowl AppName --simpleform --template_engine=slim --skip_tests

Generate an application using sqlite3, using bootstrap CSS framework, using the slim template engine, and build without any tests.

kowl AppName --git_repo=https://github/username/REPO_NAME.git

Will generate an app with the remote repo set as https://github/username/REPO_NAME.git

kowl foobar --template_engine=haml --simpleform --framework=semantic;

This will generating an app with the HAML template engine, using simpleform, and using the Semantic UI CSS Framework

Walk-Throughts

  • # Create an application using simple_form and create posts scaffold and admin page that will use ActionText

Gems

The gems included in the applications Gemfile are dependant on options passed when generating an application.

Assets

  • autoprefixer-rails parse CSS and add vendor prefixes to CSS rules using values from the Can I Use database
  • font-awesome-sass for including fontawesome in your applications CSS.
  • sass-rails integration for Ruby on Rails projects with the Sass stylesheet language
  • Dependant on the framework specified, these gems will be used to generate scaffold, devise, and layout views.
    • bootstrap_views_generator for generating Bootstrap based scaffold views, devise views, and layouts .(also dependant on if you want to use pagination, simple_form, and/or what template engine you use).
    • semantic_ui_views_generator for generating SemanticUI based scaffold views, devise views, and layouts .(also dependant on if you want to use pagination, simple_form, and/or what template engine you use).

Database gems

These gems are in addition to your applications required database adapters

  • bullet help to hunt down and catch N+1 queries throughout the application.
  • rails_erd used to generate Entity-Relationship Diagrams for Rails applications.
  • strong_migrations used to catch unsafe migrations in development
  • If the application is generated to use postgresql as it's database.
    • pghero a dashboard for monitor application query performance.
    • pg_query allows you to normalize queries and parse these normalized queries.

Devise/Users

User gems that will be included unless the --noauth flag is specified when generating an application.

  • Argon2 will be used for devise as as the devise encryption method (based on Ankane's recommendations)
  • AuthTrail used to track Devise login activity.
  • Devise a flexible authentication solution build with rails in mind.
  • Devise-Security used to enforce better security measures with devise.
  • MaxmindDB used for add getting GeoLocation details for the applications AuthTrail entries. The simplest and cheapest method to download the GeoLite2 database. (MaxMind now requires you to login to download the geolocation database) Uncompress and put the geolocation database in db/maxmind.
  • Pretender to login as another use with devise (helps when developing various rolls and permissions).
  • Pundit an authorization system build off a basic OOP pattern.
  • valid_email2 an email validation library.

Mailers

Misc

  • active_decorator OOP view helpers for cleaning up your models.
  • annotate for adding a comment summarizing the current schema to models, routes, etc.
  • auto_strip_attributes remove unnecessary whitespace from ActiveRecord attributes.
  • jsonapi-serializer lightning fast JSON:API serializer (originally releases by Netflix)
  • meta-tags helpers for making SEO/meta-tags easier to manage with your rails application.
  • oj a fast JSON object serializer.
  • simple_form a DSL for making forms easy to style and manage.
  • pagy for lightening fast and easy to use pagination.
  • Dependant on the --template_engine specified when generating an application.
    • haml-rails enables the HAML templaing engine and generators with your rails application.
    • slim-rails enables the SLIM templating engine and generators with your rails application.
  • pry a powerful IRB alternative.
  • pry-rails a adapter to make it easy to use pry with a rails application.
  • spirit_hands a opinionated console adapter for cleaning up your application output.

Performance

  • attendance change the behavior of present? to prevent unnecessary SQL queries.
  • fast_blank a C extension which provides a fast implementation of Active Support's String#blank?.

Responses, Errors, and Security

  • dotenv-rails to enable loading of environment variables with .env files.
  • Rack-attack Rack middleware for blocking & throttling
  • Slowpoke timeout long running page requests.

Security and Logging

  • blind_index for search encrypted database fields.
  • lockbox for encrypting database fields when at rest.
  • rbnacl a ruby adapter to enable using using libsodium (NaCl) for encryption.
  • Logging
    • lograge is used to cleanup and tame Rails logs.
    • logstop for filtering out a list of basic PII/PHI attributes from Application logs.

Sidekiq and Background Jobs

These gems will be included to setup sidekiq unless the --skip_sidekiq flag is used when generating an application.

  • hiredis a C adapter for connecting your application to a Redis datestore (faster than the ruby redis library).
  • Sidekiq simple, efficient background processing for Ruby
  • Sidekiq-Failures to get a better view of what jobs are failing.
  • Sidekiq-Scheduler to schedule sidekiq jobs on a given interval.
  • Sidekiq-Status is sidekiq extension to get a better status report of all currently running jobs.

Linter gems included

  • brakeman a static code analyser to detect possible ruby/rails vulnerabilities.
  • bundler-audit used to check andd verify if any of the applications gems have known updates/vulnerabilities.
  • rails_best_practices a code metric tool to check the quality of Rails code.
  • Rubocop
    • rubocop A Ruby static code analyzer and formatter based of the Ruby style guide.
    • rubocop-performance an extension of RuboCop focused on code performance checks.
    • rubocop-rails a RuboCop extension focused on enforcing Rails best practices and coding conventions.
    • Dependant on the test_engine you specified to use when generating the application
      • rubocop-minitest a Rubocop extension focused on enforcing Minitest best practices and coding conventions
      • rubocop-rspec a Rubocop extension focused on enforcing Rspec best practices.
  • scss_lint is linter to help you keep your SCSS/SASS clean and readable.
  • rubycritic a Ruby code quality reporter.
  • Dependant on the template engine you specified to use
    • erb_lint a linter to validate you're writing clean and valid erbs views
    • haml_lint a linter to validate you're writing clean and valid haml views
    • slim_lint a linter to validate you're writing clean and valid slims views

Test gems included (dependant on test_engine used)

  • Database Cleaner for flushing databases as you run tests
  • factory_bot_rails a fixtures replacement for generating sample data with tests.
  • faker for generating sample data for your appliaction or tests.
  • rails-controller-testing added to add additional methods for controller integration tests.
  • shoulda helps you write understandable, maintainable Rails-specific tests. (also contains shoulda-matchers and should-context)
  • simplecov for generating a code coverage report when running tests.
  • test-prof helps with application test profiling and performance stats.
  • timecop used to run time bases tests across your application
  • Integration Testing
    • capybara a test framework to make building integration tests easy to get started with.
    • selenium-webdriver a webdriver to make running selenium based tests easier to build.
    • webdrivers used to selenium based tests against your application to simulaet actual user requests.
MiniTest
  • minitest a complete suite of testing facilities supporting TDD, BDD, mocking, and benchmarking.
  • minitest-reporters customizable output for minitest results.
Rspec
  • formulaic allows you to perform easier form testing with Capybara
  • fuubar a progressbar to display when running rspec tests.
  • pig-ci-rails For displaying application memory metrics while running tests
  • pundit-matchers matchers for testing Pundit authorisation policies. (unless you generate your app with --noauth)
  • rspec-rails easily include rspec with a rails application.
  • rspec-sidekiq a collection of methods to assist with create tests for Sidekiq workers (unless you specific to --skip_sidekiq)

If using ruby >= 2.7 it also includes e2mmap and thwait to prevent ruby dependency errors.

Additonal Stuff

  • It corrects the issue (37008) when generating a Rails (v6) application when specifying Oracle as the database
  • When using this gem to generate applications it changes the devise password encrypting from bcrypt to Argon2
  • When generating application Dockerfiles it defaults to using Alpine which will produce smaller docker images. But if applications are specified to use Oracle as the database it will default to Debian (due to the required dependencies to use the Oracle InstantClient).
  • The --encrypt flag is used to enforce GDPR and CCPA compliance to encrypt PII for users. (GDPR Article 34, Section 3 (a)) By encrypting user identifiable information; this ensurers PII isn't plain text readable by hackers in case there is a data breach with the application. When encrypting user data it will use the lockbox with the xsalsa20 algorithm which requires libsodium.
  • When using javascript/webpacker not only will it gzip js assets, it will also compress assets with brotli and zopfli compression (in production).
  • A number of linter dotfiles added, that way you don't have to hunt down how they are setup. And you only need to use the linters than you want to use.

Notes

  • If looking to build a secure rails application I would begin by reading Ankane's article Securing Sensitive Data in Rails for some basic for rails security best practices.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Brandon Hicks (@tarellel)

Project Link: https://github.com/tarellel/kowl

Acknowledgements