Skip to content

1 Setting up the Development Environment

Jump to bottom Edit New page
John R. D'Orazio edited this page Dec 28, 2023 · 53 revisions

This is a Rails app.

New to Rails? Checkout the video "Rails 5: The Tour" on https://rubyonrails.org/ as an introduction.

Rails Guides has a getting started guide as well as detailed guides about other Rails components, like Active Record and routing.

In order to set up the development environment, the following steps will be taken:

  1. Set up the Database
  2. Clone a fork of the project repository
  3. Install Ruby
  4. Install Bundler
  5. Install ruby gem dependencies
  6. Check your environment
  7. Load the database schema
  8. NodeJS dependencies
  9. Compile assets
  10. Run the App

Set up the Database

Since the application uses a PostgreSQL database, you will need to have PostgreSQL >= v9.3 installed (sudo apt install postgresql libpq-dev) and running (sudo service postgresql start). If you prefer to spin up a docker container for PostgreSQL, skip ahead to Clone a fork of the project repository, then make sure to include the steps from PostgreSQL in a docker container.

If you are installing PostgreSQL for the first time, a default user postgres will be created, and will be locked. You will need to set a password for this user: first run sudo -u postgres psql template1, then at the Postgres CLI type \password. You will be prompted for the new password twice, after which you can exit with CTRL-D. Edit the pg_hba.conf file (path /etc/postgresql/12/main/pg_hba.conf, according to your Postgres version) and change "peer" to "md5" for both the postgres user and all users:

# Database administrative login by Unix domain socket
-local      all     postgres     peer
+local      all     postgres     md5

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
-local   all             all                                     peer
+local   all             all                                     md5

Restart the PostgreSQL service sudo service postgresql restart and test that the password is working: psql -U postgres. You should be prompted for the password, and it should be accepted as you set it in the previous steps.

Let's create a database user marriage_booklet for our application:

sudo createuser -U postgres -d -e -E -l -P -r -s marriage_booklet

You'll be prompted twice for a password for the new user, then you will be prompted for the postgres user password. You should then see something like this:

SELECT pg_catalog.set_config('search_path', '', false);
CREATE ROLE marriage_booklet PASSWORD '[password-hash-here]' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;

Test that you can log into the PostgreSQL CLI as the new user: psql -U marriage_booklet template1.

Let's create an environment variable with the database password: edit your ~/.bash_profile or ~/.bashrc and add these lines at the end:

export MARRIAGE_BOOKLET_DATABASE_USER="marriage_booklet"
export MARRIAGE_BOOKLET_DATABASE_PASSWORD="[password-here]"

Close your terminal and open a new terminal for the environment variable to be picked up. Double check that the environment variables are available:

echo $MARRIAGE_BOOKLET_DATABASE_USER
echo $MARRIAGE_BOOKLET_DATABASE_PASSWORD

Clone a fork of the project repository

As an example, we will clone the marriage-booklet project to our home directory under a development subdirectory. Please adjust any of the following instructions based on the folder you choose to develop under. We will actually clone a fork of the project, seeing that any patches we would like to contribute will be developed as branches on a fork and then submitted as PR's against the main repo.

So as a first step, from the Github repo https://github.com/opensourcecatholic/marriage-booklet, click on "fork" at the top right hand side of the screen. Then clone the fork:

cd ~
mkdir development
cd development
git clone [email protected]:YourGithubUsername/marriage-booklet.git
cd marriage-booklet

(Substitute YourGithubUsername with your Github username or with whatever url your fork refers to, such as an organization perhaps). The project will now be cloned in a marriage-booklet subfolder of the development folder.

PostgreSQL in a docker container

A docker-compose.yml file has been included in the repo, if you prefer to use a docker container as your PostgreSQL instance. First, create (in the project's main directory, alongside docker-compose.yml) an .env file with the following two environment variables:

MARRIAGE_BOOKLET_DATABASE_USER="marriage_booklet"
MARRIAGE_BOOKLET_DATABASE_PASSWORD="[password-here]"

Run docker-compose up in one terminal window to spin up the PostgreSQL instance, which should now be available on the unix socket.

Install Ruby

The first thing you'll need is the correct version of Ruby. We track this in the .ruby-version file, and tools like rbenv can use that file to switch to the correct version.

We recommend installing rbenv and using it to install the correct version. Installation instructions can be found in the rbenv README. An example is included here also. If you already have rbenv installed you can skip ahead to Test for the correct version of ruby

An example installation for Ubuntu 20.04 in a WSL2 instance on Windows, using rbenv-installer:

~$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
~$ nano ~/.bashrc

Paste this at the end of the .bashrc file:

eval "$($HOME/.rbenv/bin/rbenv init - bash)"

(CTRL-O to save and CTRL-X to exit, if using nano.)

Close the terminal window and open a new instance, so that the PATH variable is reinstantiated. Verify the state of the installation:

~$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-doctor | bash

You should see a message along the lines of:

Checking for `rbenv' in PATH: ~/.rbenv/bin/rbenv
Checking for rbenv shims in PATH: OK
Checking `rbenv install` support: ~/.rbenv/plugins/ruby-build/bin/rbenv-install (ruby-build 20231225-2-g3b79c29)
Counting installed Ruby versions: none
  There aren't any Ruby versions installed under `~/.rbenv/versions'.
  You can install Ruby versions like so: rbenv install 3.0.1
Checking RubyGems settings: OK
Auditing installed plugins: OK

You should now be able to install a ruby version.

~$ rbenv install 3.0.1

(If this results in an error "No acceptable C compiler found in PATH", you must install build-essential, make sure you have all necessary dependencies installed:

~$ sudo apt update
~$ sudo apt install build-essential libssl-dev zlib1g-dev libsqlite3-dev

Then try rbenv install 3.0.1 again.)

You should see output along these lines:

Installing ruby-3.0.1...
Installed ruby-3.0.1 to ~/.rbenv/versions/3.0.1
Test for the correct version of ruby

Now, running ruby --version from within the application directory should give you something like ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-linux]. You probably won't be able to run the rails command yet, until you have installed the rails gem. However we use bundler to manage our ruby gems, so you will have to continue through the next two steps before being able to check your rails --version.

Install Bundler

We use Bundler to manage our ruby gems. You'll probably need to install this gem. If you used rbenv to install Ruby, you should be able to run gem install bundler without sudo and bundler should be installed to the correct location.

Install ruby gem dependencies

After Bundler is installed, you can use it to install our dependencies with bundle install. Our dependencies are tracked in Gemfile and Gemfile.lock.

(Make sure you are in the project directory, wherever you cloned your fork to, for example ~/development/marriage-booklet/.)

Note that any time the Gemfile is updated with new dependencies, bundle install will need to be run again to install the new dependencies. If you haven't run bundle install after new dependencies are defined, you will probably get an error message when trying to run bundle exec rails server (see below), similar to:

Could not find rack-proxy-0.7.0 in any of the sources
Run `bundle install` to install missing gems.

Since we are using the latest stable version of the webpacker gem, you can optionally patch lib/webpacker/dev_server_runner.rb so as to allow you to use the webpack-serve yarn package instead of the webpack-dev-server yarn package when running the bin/webpack-dev-server binstub:

cd $(rbenv prefix)/lib/ruby/gems/3.0.0/gems/webpacker-5.4.0
curl https://github.com/rails/webpacker/commit/31b7a6f31e38d0d45b0e2ab162f28db1afc5ffac.patch | patch -p1

Check your environment

You should now be able to see the version of rails when running bundle exec rails --version, with an output of Rails 6.1.3.2.

Since the rails gem is made available through bundler, it needs to be invoked with bundle exec. You should however be able to invoke rails --version directly just as well, seeing that a rails binstub has been included in the bin folder (it shouldn't be necessary to run bundle binstubs rails to install the executable to the bin folder which is simply a wrapper for the bundle exec rails commands.)

You can check your rails environment with bundle exec rails about. You should get an output something like:

About your application's environment
Rails version             6.1.3.2
Ruby version              ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-linux]
RubyGems version          3.2.15
Rack version              2.2.3
Middleware                Webpacker::DevServerProxy, ActionDispatch::HostAuthorization, Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::ActionableExceptions, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ContentSecurityPolicy::Middleware, ActionDispatch::PermissionsPolicy::Middleware, Rack::Head, Rack::ConditionalGet, Rack::ETag, Rack::TempfileReaper
Application root          ~/development/marriage-booklet
Environment               development
Database adapter          postgresql
Database schema version   0

Load the database schema

Run bundle exec rails db:setup. This will create the development and test databases and load the current schema.

NodeJS dependencies

You will also have to install node dependencies with yarn install before proceeding, in order for rails/webpacker to function correctly. webpack is in fact a node package. Also the tailwindcss framework that we use depends on node.

The [email protected] framework however requires that you have a version of node >= 12.13.0.

Check your version of node: node --version. If it's less than 12.13.0, then we recommend to use nvm (and optionally avn) to manage the version of node for the project.

We track the version of node required for the project both in the .nvmrc file and in the .node-version file:

  • .nvmrc can be used by nvm to automatically detect the desired version to be installed, when issuing nvm install, without having to manually specify the version of node to install
  • .node-version can be used by avn to switch automatically to the correct version of node as soon as you enter the directory (and optionally install the version of node if not yet installed)

If you have already installed nvm, avn and yarn, you may skip ahead to Install node dependencies.

How to install nvm (and optionally avn):

You can follow the instructions in the README of the nvm github repo. Basically these are the steps:

  1. Install nvm

    $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

  2. Check if the installation is successful

    $ command -v nvm

    This should output nvm if the installation was successful. If instead you see no output, try closing your terminal and opening again. Since nvm writes to your ~/.bashrc or ~/.bash_profile or ~/.profile so as to load nvm when starting a terminal session, you may need to start a fresh terminal session in order to load nvm correctly.

    In my case, I was getting nvm as output right away, but not when opening a new terminal. nvm had written to my ~/.bashrc, which was not however getting picked up for a new terminal session. In cases like this you can either copy what nvm wrote to ~/.bashrc and paste it into ~/.bash_profile, commenting it out in ~/.bashrc:

    export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

    Or better yet, the correct fix in situations like this is probably this one. Basically just make sure that ~/.bash_profile is loading ~/.bashrc. Copy this into ~/.bash_profile:

    # include .bashrc if it exists
if [ -f "$HOME/.bashrc" ]; then
    . "$HOME/.bashrc"
fi

    I wound up using this last solution, and leaving what nvm wrote to ~/.bashrc in ~/.bashrc. Now when loading a new terminal session, I am correctly seeing nvm as output when issuing command -v nvm.

  3. Install the required version of node: while in the project directory, issuing nvm install should pick up on the version of node that we use from the .nvmrc file, and should give output something like this:

    Found '~/development/marriage-booklet/.nvmrc' with version <12.22.3>
Downloading and installing node v12.22.3...
Downloading https://nodejs.org/dist/v12.22.3/node-v12.22.3-linux-x64.tar.xz...
################################################################################################# 100,0%
Computing checksum with sha256sum
Checksums matched!
Now using node v12.22.3 (npm v6.14.13)

  4. You can optionally use avn to automatically switch to the correct version of node upon entering the project's directory. Note that this will probably require usage of Node 10 for first setup! (See here): nvm install 10.24.1

    $ npm install -g avn avn-nvm avn-n
$ avn setup

    Make sure you use npm and not yarn in this case, otherwise you will probably run into a lot of issues! If you get an EACCESS permissions error when running avn setup, it might not have succeeded in writing to your ~/.bash_profile or ~/.profile, in that case you'll have to manually edit and add this at the end: [[ -s "$HOME/.avn/bin/avn.sh" ]] && source "$HOME/.avn/bin/avn.sh" # load avn.

    Exit and restart the terminal, now when you cd into the marriage-booklet directory, you should automatically switch to the correct version of node for the project.

How to install yarn

Of course you also need to have yarn installed. You can check if you have yarn by issuing yarn --version. This should give you something like 1.22.5. If you don't have yarn, installing it is as simple as this:

npm install -g yarn
Install node dependencies

The node dependencies, managed by yarn, are defined in package.json and yarn.lock. So now that you have all the tools in place, you should install the node dependencies from the project directory if you haven't done so yet:

yarn install

Optional: To fix "unmet peer dependency" warnings, issuing yarn upgrade might help to fix. This should update all of the packages to the highest possible version allowed in package.json, while maintaining compatibility between the packages in the dependency tree.

Refresh node dependencies

When package.json and/or `yarn.lock' changes adding new dependencies, such as when pulling changes into your local environment from the remote repo in a team setting, be sure to keep your NPM packages up-to-date:

yarn install

Compile assets

Now that yarn has installed webpacker, you should compile the JS and CSS assets for the application:

bundle exec rails webpacker:compile

If you're trying to refresh assets that have been previously compiled:

bundle exec rails webpacker:clobber
bundle exec rails webpacker:compile

Run the App

After all dependencies are installed with Bundler and Yarn and assets have been compiled, you can run the app in development mode with bundle exec rails server. If you first run bin/webpack-dev-server you will get real time compilation of assets. For this to work it needs to be run before bundle exec rails server, so that the rails server will know to pick up the assets from webpack-dev-server rather than from precompiled assets.

The bundle exec part of bundle exec rails server isn't always required, but will ensure you use the correct version of dependencies in case there are multiple versions installed.

Once the server is running, you can open it in a browser at http://127.0.0.1:3000 (or http://localhost:3000).

     «            GO BACK TO THE PREVIOUS SECTION                     CONTINUE TO THE NEXT SECTION           »      
     Home 2 Contributing a patch      
Add a custom footer
Add a custom sidebar
Clone this wiki locally