System Requirements

• Ruby 3.2.2
• Node.js v18
• Bundler - gem install bundler

Homebrew dependencies:

• Redis - For ActionCable, Sidekiq, caching, etc.
• PostgreSQL - For database
• Overmind - For running Procfile processes
• Libvips or ImageMagick - For ActiveStorage image processing

All Homebrew dependencies are listed in Brewfile, so you can install them all at once like this:

brew bundle install --no-upgrade

Then you can start the database servers:

brew services start postgresql
brew services start redis

Rails Getting Started

• run bin/setup to setup. This should do a couple of things to get the app ready for development. You can also setup manually by running each command from the bin/setup file.

• Setup the RAILS_MASTER_KEY credentials as secret on GitHub for CI to work. Settings > Secrets > New repository secret

• Customize values in config/initializers/0_constants.rb

Running the app for development

• Run bin/dev to start the app locally
• Run overmind connect web to connect to the web process logs & run debugger
• Open localhost:3000 in your web browser to view the app
• Open localhost:3000/admin to view the admin panel (create an AdminUser record via console).
• Open localhost:3000/rails/mailers to view mailers preview locally
• Open localhost:3000/sidekiq to view sidekiq dashboard
• Emails sent in local development are automatically opened in the browser by letter_opener.

Gems Documentations

HTML templating & components:

• HAML - for HTML templating
• Phlex - for Ruby components architecture

Backend:

• Pagy - for pagination
• Devise - for authentication
• Pundit - for authorization
• PaperTrail - for versioning
• ActiveStorage - for file uploads
• Blueprinter - for JSON API serialization
• Sidekiq - for background jobs queue

Frontend:

• Importmap Rails - for JS modules
• Tailwind CSS - for CSS framework
• Alpine JS - for JS framework for inline JS animation & toggles, etc.
• Stimulus JS - for JS framework
• Hotwire - for Turbo and Stimulus JS

Testing:

• Rspec - for testing
• FactoryBot - for factories
• Faker - for fake data
• Shoulda Matchers - for testing matchers quickly

External Services

• Google OAuth2 - connecting with Google. Update Authorized redirect URIs and update credentials in our app. Set callback URL to http://localhost:3000/users/auth/google_oauth2/callback for development & similar for production with your domain.
• Sentry - for error tracking. Setup two projects and update credentials - for Rails & JS frontend.
• Postmark - for transactional emails. Verify domain for sending emails.
• Cloudflare R2 - for file uploads. Setup a R2 bucket and update credentials.
• Contentful - for CMS. Update credentials. And import the BlogPost content model. Instructions below on conteful.

Things to Update

Checklist for things to update before you launch your app:

• Update Privacy Policy and Terms and Conditions

• Update AnonymizationService to anonymize user data and relating records where personal information is stored when user requests to delete their account. This is important to comply with GDPR & other regulations. User data is scrambled but the record is kept for audit trail. Alternatively just delete the record if you want to completely get rid of the data immediately. Update the destroy method on RegistrationsController.

• Add pages to config/sitemap.rb file for sitemap generation.

• If you don't want some pages to be indexed by search engines, add noindex meta tag and update config/sitemap.rb file to exclude those pages.

• Onboarding flow with custom fields that you require user to fill out after sign up. Or disable the onboarding in the constants file.

Contenful

We use Contentful (free plan) to manage blog posts. You can use Contentful for other content types as well and the structure is setup with webhooks and caching. Everything ready to go.

To get setup:

1. Setup a new Contentful space.
2. Install the Contentful CLI.
3. Import our sample model structure to the space. contentful space import --space-id <space_id> --content-file lib/templates/contentful.json
4. Create a Contentful API Key & update our credentails file.
5. Add some blog posts in Contentful & enjoy!

Deploying to Heroku

Automatic Deploy

Deploy with an app.json file that helps Heroku pre-configure the application.

Manual Deploy

Install Heroku CLI and login to Heroku account (heroku login).

The usual steps (create a Heorku app, deploy the code) plus the following:

Install addons:

• Heroku Postgres addon
• Redis addon
• Heroku Scheduler addon

Set config vars:

• Set RAILS_MASTER_KEY config var to decrypt credentials.yml.enc file
• Set HOST config var to your domain
• Set RAILS_ENV config var to production

Setup Buildpacks:

• heroku buildpacks:set heroku/ruby -a <app_name> (will take last priority)
• heroku buildpacks:add --index 1 https://github.com/heroku/heroku-buildpack-apt.git -a <app_name>
• heroku buildpacks:add --index 2 https://github.com/brandoncc/heroku-buildpack-vips -a <app_name>
• heroku buildpacks:add --index 3 https://github.com/gaffneyc/heroku-buildpack-jemalloc.git -a <app_name>

Post Deploy

Run migrations:

• heroku run rake db:migrate

Other setup:

• Contentful - setup webhook to production server for clearing cache. https://<HOST>/contentful/webhook with the secret token (Header as Authorization:Bearer) that is set in the credentials file.
• Setup Rake tasks below on the scheduler addon

Rake Tasks

• rake active_storage:purge_unattached_blobs to purge unattached file that are older than 2 days in active storage. - Run once a day.
• rake anonymize:users to anonymize users data. - Run once a day. Important to delete user's data in our database. Give's time for them to change their mind before we delete their data.
• rake sitemap:refresh to refresh sitemap. - Run once a day.