diff --git a/README.md b/README.md index 7dcdfca4..cf399d09 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,6 @@ We are a [Rails company](https://rubyonrails.org/foundation), so the most value will be found in the parts concerning Rails. But anyways you'll also find a lot about the inner workings of Renuo. -* [Ruby on Rails – Application Setup Guide](./ruby_on_rails/README.md) - -## Some Notes on the Side - If you are reading this document, it means that you have to setup a new application. A new project started and it's now time to set everything up so that **everyone**, in your team, **can start working on it**. @@ -19,32 +15,38 @@ This guide is the result of more than ten years of experience, so this means thr **You are always welcome to challenge the guide and improve it with a Pull Request.** -The basic things that need to be ready before the team can start working on a project are: +**:exclamation: Do not blindly follow this guide, always think about what you are doing and why. +If you think something is wrong or simply outdated, improve this guide with a Pull Request.** -* An existing *git* repository containing the project -* Two branches: *main* and *develop* -* A README with essential information about the application -* Convenience-scripts: `bin/setup`, `bin/check`, `bin/fastcheck`, `bin/run` -* One running, green test -* Continuous integration (*CI*) ready, running and green for both branches -* Continuous deployment (*CD*) ready and running for both branches -* The application deployed for both branches +Thank you for your work and have fun! :tada: -As an appendix, you'll find a [checklist](checklist.md) you can use to follow the guide. +## How to Use This Guide -**:exclamation: Do not blindly follow this guide, always think about what you are doing and why. -If you think something is wrong or simply outdated, improve this guide with a Pull Request.** +The guide is structured as a linear walkthrough. Follow it from top to bottom when setting up a new project. -We want you to know exactly the reason behind each single step of this guide. +1. **Before You Start** — Read [Naming Conventions](naming_conventions.md), [GitFlow](gitflow.md), and [Security](security.md) to understand the ground rules. +2. **Rails Application Setup** — Follow the [step-by-step setup](ruby_on_rails/README.md) to create, deploy, and configure your app. +3. **Guides & Recipes** — Pick the ones you need (emails, authentication, payment, etc.). +4. **Reference** — Use the [Checklist](checklist.md) to verify you haven't missed anything, and the [Go Live!](go_live.md) page when you're ready to launch. -Thank you for your work and have fun! :tada: +## What Needs to Be Ready + +Before the team can start working on a project, you need: + +* An existing *git* repository containing the project +* Two branches: *main* and *develop* (or just *main* for internal projects) +* A README with essential information about the application +* Convenience-scripts: `bin/setup`, `bin/check`, `bin/fastcheck`, `bin/run` +* One running, green test +* Continuous integration (*CI*) ready, running and green for all branches +* Continuous deployment (*CD*) ready and running for all branches +* The application deployed for all branches ## Serving the Documentation Locally -To view this documentation on your machine, run the following commands: +To view this documentation on your machine, run the following command: ```sh -brew install mdbook mdbook serve ``` diff --git a/SUMMARY.md b/SUMMARY.md index 9690106e..d2fa93da 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,65 +2,69 @@ [Overview](README.md) -# General +# Before You Start -- [Create a Git Repository](create_git_repository.md) -- [GitFlow](gitflow.md) -- [Go Live!](go_live.md) - [Naming Conventions](naming_conventions.md) +- [GitFlow](gitflow.md) - [Security](security.md) -- [Project Checklist](checklist.md) -# Rails Application Setup Guide +# Rails Application Setup -- [Getting started](ruby_on_rails/README.md) +- [Getting Started](ruby_on_rails/README.md) -- [Setup]() +- [Step 1: Create the App]() - [Initialise the Rails App](ruby_on_rails/app_initialisation.md) + - [Create a GitHub Repository](create_github_repository.md) - [Push to Git Repository](ruby_on_rails/first_git_push.md) - [Initialise Gitflow](ruby_on_rails/initialise_gitflow.md) - - [Configure Git Repository](configure_git_repository.md) - - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md) + - [Configure GitHub Repository](configure_github_repository.md) +- [Step 2: Deploy the App]() - [Create an Application Server (Deploio)](ruby_on_rails/create_application_server_deploio.md) + - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md) - [Configure the CI/CD](ruby_on_rails/configure_ci.md) -- [Tools]() +- [Step 3: Quality Tools]() - [RSpec](ruby_on_rails/rspec.md) - [Linting and automatic checks](ruby_on_rails/linting_and_automatic_check.md) - [Gems and libraries](ruby_on_rails/suggested_libraries.md) - [Cloudflare](ruby_on_rails/cloudflare.md) -- [Additional Services]() +- [Step 4: Monitoring & Protection]() + - [AppSignal](ruby_on_rails/appsignal.md) - [Sentry](ruby_on_rails/sentry.md) - [NewRelic](ruby_on_rails/newrelic.md) - [Robots.txt](ruby_on_rails/robots_txt.md) - [Percy](ruby_on_rails/configure_percy.md) - [Protect develop environment](ruby_on_rails/environment_protection.md) -- [Customer Plan Services]() +- [Step 5: Customer Plan Services]() - [Uptimerobot](ruby_on_rails/uptimerobot.md) - [Depfu Security monitoring](ruby_on_rails/depfu.md) -- [Gems]() - - [Jest](ruby_on_rails/jest.md) - - [Send Emails](ruby_on_rails/send_emails.md) - - [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md) - - [Devise](ruby_on_rails/devise.md) - - [Cucumber](ruby_on_rails/cucumber.md) - - [Object Storage](ruby_on_rails/object_storage.md) - - [Bootstrap](ruby_on_rails/bootstrap.md) - - [FontAwesome](ruby_on_rails/font_awesome.md) - - [Bullet](ruby_on_rails/bullet.md) - - [Lograge](ruby_on_rails/appsignal.md) - - [Hotjar](ruby_on_rails/hotjar.md) - - [Wicked PDF](ruby_on_rails/wicked_pdf.md) - - [Recaptcha v3](ruby_on_rails/recaptcha.md) +# Guides & Recipes + +- [Send Emails](ruby_on_rails/send_emails.md) +- [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md) +- [Devise](ruby_on_rails/devise.md) +- [Object Storage](ruby_on_rails/object_storage.md) +- [Jest](ruby_on_rails/jest.md) +- [Cucumber](ruby_on_rails/cucumber.md) +- [Bootstrap](ruby_on_rails/bootstrap.md) +- [FontAwesome](ruby_on_rails/font_awesome.md) +- [Bullet](ruby_on_rails/bullet.md) +- [Hotjar](ruby_on_rails/hotjar.md) +- [Wicked PDF](ruby_on_rails/wicked_pdf.md) +- [Recaptcha v3](ruby_on_rails/recaptcha.md) +- [Wallee Payment](ruby_on_rails/wallee.md) +- [Content Security Policy](ruby_on_rails/content_security_policy.md) +- [I18n](i18n.md) # Services - [Google Analytics](google_analytics.md) -- [Google Apis](google_apis.md) +- [Google APIs](google_apis.md) - [Slack and Notifications](slack_and_notifications.md) +# Reference -# Templates - -- [README](templates/README.md) +- [Project Checklist](checklist.md) +- [Go Live!](go_live.md) +- [README Template](templates/README.md) - [Pull Request Template](templates/pull_requests_template.md) diff --git a/configure_git_repository.md b/configure_github_repository.md similarity index 82% rename from configure_git_repository.md rename to configure_github_repository.md index 373731d9..06b689da 100644 --- a/configure_git_repository.md +++ b/configure_github_repository.md @@ -7,38 +7,37 @@ Please stick to it unless you have special needs. * Features: Remove *Wikis*, *Issues* and *Projects* * Pull Requests * Disable *Allow merge commits* and *Allow rebase merging* - * Always suggest updating pull request branches * Allow auto-merge * Automatically delete head branches + * Always suggest updating pull request branches * Manage access * Add *staff* team as a collaborator with Admin access * Add *security* team as collaborator with Write access * Branches * Default branch: either `main` or `develop` depending on whether you want one or two environments. * Rules/Rulesets - * `develop` + * We use two rulesets: one for `main` and one for everything else. This ensures that long-lived branches like `redesign` and feature branches like `feat/my-feature` share the same protection rules as `develop`. + * `non-main` * Enforcement status: `Active` + * Branch targeting criteria: + * Include all branches + * Exclude by pattern: `main` * Bypass list: add `Repository Admin` Role with *allow for pull requests only* option - * Branch targeting criteria: `develop` * Restrict deletions * Require linear history * Require a pull request before merging * Require status checks to pass - * Select `ci/semaphore/push` (AFTER SETTING UP SEMAPHORE) + * Select `ci/semaphore/push` * Block force pushes - * `main` (same as develop but...) + * `main` (same as non-main but...) * Branch targeting criteria: `main` * ❌ Require a pull request before merging * ❌ Require status checks to pass - * Autolink references * Add a new Autolink reference with: * Reference prefix: `TICKET-` * Target URL: `https://redmine.renuo.ch/issues/` -In case you have a second long-living environment (e.g., for a design rewrite, a new major version, etc.), -consider applying the same rules as on `develop` to it as well. - ## Team Each project has a team owning it. The team is named after the project: `[team-name] = [project-name]`. diff --git a/create_git_repository.md b/create_github_repository.md similarity index 87% rename from create_git_repository.md rename to create_github_repository.md index ac9dec07..87b4ae52 100644 --- a/create_git_repository.md +++ b/create_github_repository.md @@ -1,4 +1,4 @@ -# Create a Git Repository +# Create a GitHub Repository At Renuo we currently use [GitHub](https://github.com/) as our git repository. You should already be part of the Renuo Organisation and have permissions to do so. If that's not the case, double check the Laptop Setup Guide or ask wg-operations. @@ -8,7 +8,7 @@ To create a new GitHub project you can use the tool you prefer, but it should ha * Should have `[project-name]` as a name * Should be private (unless you are creating an OpenSource project) -Use the command `hub create -p renuo/[project-name]` to create the repo and add it to the origin of the current folder. +Use the command `gh repo create renuo/[project-name] --private --source=. --remote=origin` to create the repo and add it to the origin of the current folder. ## Public repos need a license diff --git a/ruby_on_rails/README.md b/ruby_on_rails/README.md index c66d4ee0..c2c5121e 100644 --- a/ruby_on_rails/README.md +++ b/ruby_on_rails/README.md @@ -13,25 +13,37 @@ The application (and relative GitHub repo) will be named after the `[project-nam > Why the difference? Because we can bare the risk of having a bug in an internal project, but we cannot do that for a customer. > Decide with your team if you want one or two branches. +> :bulb: **Tip:** Sections marked with ✨ are already set up by the Renuo Rails template or ship with Rails 8.1 by default. You only need to verify them, not install them. + +--- + +## Step 1: Create the App + 1. [Initialise the Rails Application](app_initialisation.md) 1. [Push to Git Repository](first_git_push.md) 1. [Initialise Gitflow](initialise_gitflow.md) -1. [Configure Github Repository](../configure_git_repository.md) +1. [Configure Github Repository](../configure_github_repository.md) + +## Step 2: Deploy the App + 1. [Create an Application Server for Deploio](create_application_server_deploio.md) or [Create an Application Server for Heroku](create_application_server_heroku.md) 1. [Configure the CI / CD](configure_ci.md) Once here, your app should be up and running on all environments. +## Step 3: Quality Tools + It's now time to introduce some more tools which will help you and the team to keep a high quality during the project development. 1. [RSpec](rspec.md) 1. [Linting and automatic checks](linting_and_automatic_check.md) 1. [Gems and libraries :gem:](suggested_libraries.md) 1. [Cloudflare](cloudflare.md) -1. [README](compile_readme.md) :tada: Finally you are ready to start working on you new project! :tada: +## Step 4: Monitoring & Protection + While everyone starts working there are some more things which you should setup. Most are not optional, but the rest of the team can start working even if those are not in place yet. @@ -42,41 +54,42 @@ Most are not optional, but the rest of the team can start working even if those 1. [Percy](configure_percy.md) (optional) 1. [Protect develop environment](environment_protection.md) -Some services should be configured accordingly to the packages bought by the customer. -Once the new application is created, please add the project to the -[monitoring list](https://docs.google.com/spreadsheets/d/1FY4jqByO-aI5sDan0hD7ULu6a2-eLsmO6kgdCFlPmuY/edit#gid=0) -and discuss with the PO how the service should be configured. +## Step 5: Customer Plan Services + +Bookmark the project on [Redmine](https://dashboard.renuo.ch/redmine_projects) and configure the services listed there. 1. [Uptimerobot](uptimerobot.md) -1. Depending on the monitoring list, also [Sentry notifications](sentry.md) need to be configured. +1. [Sentry notifications](sentry.md), if requested 1. [Depfu security monitoring](depfu.md) -1. Depending on the monitoring list, also [Papertrail alerts](papertrail.md) need to be configured. - -Here you will find a series of chapters and guides on how to setup some of the gems we use most often and some other -useful services: - -1. [Run Javascript tests with Jest](jest.md) -1. [Pull Requests Template](../pull_requests_template.md) -1. [Slack and Project Notifications](../slack_and_notifications.md) -1. [Send emails](send_emails.md) -1. [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md) -1. [Devise](devise.md) -1. [Cucumber](cucumber.md) -1. [Object storage](object_storage.md) -1. awesome_print `gem 'awesome_print'` -1. [bootstrap](bootstrap.md) -1. [font-awesome](font_awesome.md) -1. [bullet](bullet.md) `gem 'bullet'` -1. [lograge](appsignal.md) `gem 'lograge'` -1. Rack Tracker (Google Analytics) `gem 'rack-tracker'` --> see [Google Analytics](../google_analytics.md) -1. Favicons -1. [Rack CORS](https://github.com/cyu/rack-cors) -1. [Rack Attack](https://github.com/rack/rack-attack#installing) -1. [:fire: Hotjar](hotjar.md) -1. SEO - * redirect non-www to www - * Header tags -1. [wicked pdf](wicked_pdf.md) `gem wicked_pdf` -1. [Recaptcha v3](recaptcha.md) -1. [Wallee Payment Integration](wallee.md) -1. [Sign in with Redmine](https://gist.github.com/sislr/fb7f6d8f05c96c199d9525706561902d) +1. [Papertrail alerts](papertrail.md), if requested + +--- + +## Guides & Recipes + +The following are not part of the sequential setup. Use them as needed for your project. + +* [Run Javascript tests with Jest](jest.md) +* [Pull Requests Template](../templates/pull_requests_template.md) +* [Slack and Project Notifications](../slack_and_notifications.md) +* [Send emails](send_emails.md) +* [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md) +* [Devise](devise.md) +* [Cucumber](cucumber.md) +* [Object storage](object_storage.md) +* awesome_print `gem 'awesome_print'` +* [bootstrap](bootstrap.md) +* [font-awesome](font_awesome.md) +* [bullet](bullet.md) `gem 'bullet'` +* [lograge](appsignal.md#lograge) `gem 'lograge'` +* Rack Tracker (Google Analytics) `gem 'rack-tracker'` --> see [Google Analytics](../google_analytics.md) +* Favicons +* [Rack CORS](https://github.com/cyu/rack-cors) +* [Rack Attack](https://github.com/rack/rack-attack#installing) +* [:fire: Hotjar](hotjar.md) +* SEO + * redirect non-www to www + * Header tags +* [wicked pdf](wicked_pdf.md) `gem wicked_pdf` +* [Recaptcha v3](recaptcha.md) +* [Wallee Payment Integration](wallee.md) diff --git a/ruby_on_rails/app_initialisation.md b/ruby_on_rails/app_initialisation.md index c6a3bc14..44675192 100644 --- a/ruby_on_rails/app_initialisation.md +++ b/ruby_on_rails/app_initialisation.md @@ -95,7 +95,7 @@ Check existing projects for an example of the usage. config.action_controller.action_on_unpermitted_parameters = :raise config.i18n.raise_on_missing_translations = :strict - config.generators.apply_rubocop_autocorrect_after_generate! + config.generators { |g| g.apply_rubocop_autocorrect_after_generate! } ``` * Update `config/environments/test.rb` settings: diff --git a/ruby_on_rails/compile_readme.md b/ruby_on_rails/compile_readme.md deleted file mode 100644 index 8017a7e2..00000000 --- a/ruby_on_rails/compile_readme.md +++ /dev/null @@ -1,4 +0,0 @@ -# README File - -It's time to compile our README.md file for the project. -Please follow the [README](../templates/README.md). \ No newline at end of file diff --git a/ruby_on_rails/create_application_server_deploio.md b/ruby_on_rails/create_application_server_deploio.md index 1a20eeff..a81de2b1 100644 --- a/ruby_on_rails/create_application_server_deploio.md +++ b/ruby_on_rails/create_application_server_deploio.md @@ -2,21 +2,13 @@ ## Prerequisites -Before setting up your application, ensure you have completed the following for Deploio. - -### Prerequisites for Deploio - - You've [read about what Deploio is](https://docs.nine.ch/docs/deplo-io/getting-started-with-deploio). - You have a Deploio account. - You have installed the `renuo-cli` gem. - You have installed the `nctl` command. - You have logged in using `nctl`. -## Setup Your Application - -### Setup Deploio Application - -#### Remote Configuration +## Setup Run [the command to generate a script](https://github.com/renuo/renuo-cli/blob/main/lib/renuo/cli/commands/create_deploio_app.rb) which will create and configure all Deploio apps. `[project-name]` string length is limited to 63 characters: @@ -36,7 +28,7 @@ If you think that the production database will soon reach the 10 GB, please cons If you think that the script is outdated, please open a Pull Request on the [renuo-cli](https://github.com/renuo/renuo-cli) project. -For further configuration and best practices, please refer to the [Deploio documentation](https://guides.deplo.io). You can also view a Ruby on Rails specific guide [here](https://guides.deplo.io/ruby/quick-start.html). +For further configuration, see the [Rails on Deploio guide](https://guides.deplo.io/ruby/quick-start.html). For general Deploio docs, see [guides.deplo.io](https://guides.deplo.io). ## Next Steps diff --git a/ruby_on_rails/create_application_server_heroku.md b/ruby_on_rails/create_application_server_heroku.md index ab02b2ef..bb5a2eca 100644 --- a/ruby_on_rails/create_application_server_heroku.md +++ b/ruby_on_rails/create_application_server_heroku.md @@ -2,19 +2,11 @@ ## Prerequisites -Before setting up your application, ensure you have completed the following for Heroku. - -### Prerequisites for Heroku - - You've [read about what Heroku is](https://www.heroku.com/platform). - You have a Heroku account. - You have installed the `renuo-cli` gem. -## Setup Your Application - -### Setup Heroku Application - -#### Remote Configuration +## Setup Run the command to generate a script which will create and configure all Heroku apps. `[project-name]` string length is limited to 22 characters: @@ -29,7 +21,7 @@ In particular, you might need only one of the two environments if you decided to If you think that the script is outdated, please open a Pull Request on the [renuo-cli](https://github.com/renuo/renuo-cli) project. -#### Setup Rails for Heroku +## Setup Rails for Heroku 1. Add a file called `Procfile` to your code root: diff --git a/ruby_on_rails/cucumber.md b/ruby_on_rails/cucumber.md index 1beba008..7f353006 100644 --- a/ruby_on_rails/cucumber.md +++ b/ruby_on_rails/cucumber.md @@ -41,8 +41,6 @@ If you add Cucumber to an existing project, test a real page instead of using th Add the following files: -* [`app/controllers/home_controller.rb`](../templates/app/controllers/home_controller.rb) (If you haven't done so -already) in the [RSpec](rspec.md) section. * [`features/home_check.feature`](../templates/features/home_check.feature) * [`features/step_definitions/home_check_steps.rb`](../templates/features/step_definitions/home_check_steps.rb) diff --git a/ruby_on_rails/first_git_push.md b/ruby_on_rails/first_git_push.md index 28136a46..d74910b6 100644 --- a/ruby_on_rails/first_git_push.md +++ b/ruby_on_rails/first_git_push.md @@ -1,18 +1,15 @@ # Push to Git Repository -It's now time to push to the git repository and configure our CI and CD to deploy our application on Heroku. -To do that you first need to [Create a Git Repository](../create_git_repository.md). +By now `rails new` has already initialised the local git repository and created an initial commit for you. This step pushes that commit to the GitHub repository you created in the [previous step](../create_github_repository.md). -After creating the repo you can connect your project to the remote git repo (if you didn't use `hub create` command) +If you used `gh repo create renuo/[project-name] --private --source=. --remote=origin`, the `origin` remote is already set. Otherwise, add it: ```sh git remote add origin git@github.com:renuo/[project-name].git ``` -and push using: +Then push: ```sh -git add . -git commit -m "Initial commit" git push -u origin main ``` diff --git a/ruby_on_rails/initialise_gitflow.md b/ruby_on_rails/initialise_gitflow.md index 059d5fb0..032a4347 100644 --- a/ruby_on_rails/initialise_gitflow.md +++ b/ruby_on_rails/initialise_gitflow.md @@ -4,4 +4,4 @@ You can initialise gitflow in you project with `git flow init -d` Then push also your new develop branch `git push --set-upstream origin develop` if you have one. -Once you have pushed all the branches, you can finish the [configuration of Git Repository](../configure_git_repository.md) +Once you have pushed all the branches, you can finish the [configuration of GitHub Repository](../configure_github_repository.md) diff --git a/ruby_on_rails/linting_and_automatic_check.md b/ruby_on_rails/linting_and_automatic_check.md index 77db1411..8b4cdd17 100644 --- a/ruby_on_rails/linting_and_automatic_check.md +++ b/ruby_on_rails/linting_and_automatic_check.md @@ -7,8 +7,9 @@ Check out the `bin/fastcheck` [fastcheck](../templates/bin/fastcheck) for the fi ## Renuocop 👮 +> ✨ Installed by the Renuo Rails template (replaces `rubocop-rails-omakase`). + Renuocop is based on Standard Ruby and is a set of rules that we use to lint our Ruby code. -It's already included in your Gemfile by default. You can execute it and correct the issues you'll find. @@ -16,7 +17,9 @@ You can execute it and correct the issues you'll find. ## Brakeman -Brakeman comes by default with Rails. Add it to the `bin/fastcheck` script. +> ✨ Ships with Rails 8.1 by default. + +Add it to the `bin/fastcheck` script. ```sh bundle exec brakeman -q -z --no-summary --no-pager diff --git a/ruby_on_rails/rspec.md b/ruby_on_rails/rspec.md index 525e7113..40b18250 100644 --- a/ruby_on_rails/rspec.md +++ b/ruby_on_rails/rspec.md @@ -1,5 +1,8 @@ # Setup RSpec +> **Note:** The Renuo Rails template does NOT set up RSpec. All steps on this page are manual. +> Rails 8.1 does ship `capybara` and `selenium-webdriver` in the `:test` group by default. There is no need to add those manually when using the template. + Even though Rails uses Minitest per default, RSpec is the *de-facto* standard at Renuo. Add the following gems to your Gemfile: @@ -148,10 +151,7 @@ SELENIUM_DRIVER="selenium_chrome_headless" ### config/environments/development.rb ```rb -config.generators do |g| - g.test_framework :rspec -end - +config.generators { |g| g.test_framework :rspec } ``` * Add the line `bundle exec parallel_rspec` to `bin/check`