New to Rails? Checkout the introductory video on https://rubyonrails.org/ to help you get started.

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

Gemfile dependencies
default • • • • • • • • • • • • • • • development • • • test • • • • •

Setting up the Development environment

• 🍴 Clone a fork of the project repository
• 🐋 docker-compose
• 🧮 Set up the Database
• ♦️ Install Ruby
  • 🧪 Test for the correct version of ruby
• 🔡 Install Bundler
• 💎 Install ruby gem dependencies
• 🌥️ Check your Rails environment
• 📈 Load the database schema
• 📑 Check NodeJS environment
• 🌩️ Compile assets
• ⚛️ Run the App

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.

docker-compose

We provide a docker-compose file that will start database, redis, and adminer services in Docker. The database will be created with a default username and password that match the development defaults in our app configuration so you don't need to edit anything. To use this, you need Docker installed. Follow the installation instructions on their website. Once Docker's installed, just run

docker-compose up

to start the database and other services in Docker.

An instance of Adminer has been included in the docker compose file, so as to offer a tool that can help inspect the database and the tables. You may change the port in the .env file to your liking. If you do not supply the ADMINER_PORT environment variable, the adminer instance will default to port 8080. You can visit the Adminer interface at http://localhost:[ADMINER_PORT] (for example, http://localhost:8080). You can log into the adminer interface with:

System	PostgreSQL
Server	db
Username	[MARRIAGE_BOOKLET_DATABASE_USER] (default: marriage_booklet)
Password	[MARRIAGE_BOOKLET_DATABASE_PASSWORD] (default: password)
Database	marriage_booklet_development

If you prefer not to use Docker, you can also set up your database manually.

Set up the Database

(Skip this if you're using docker-compose.)

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 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/15/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

Install Ruby

You'll need 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 ~/.profile

Paste this at the end of the .profile or .bash_profile file:

# set PATH so it includes ~/.rbenv/shims if it exists
if [ -d "$HOME/.rbenv/shims" ] ; then
    PATH="$HOME/.rbenv/shims:$PATH"
fi

# set PATH so it includes ~/.rbenv/bin if it exists
if [ -d "$HOME/.rbenv/bin" ] ; then
    PATH="$HOME/.rbenv/bin:$PATH"
fi

(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: not found
  The directory `~/.rbenv/shims' must be present in PATH for rbenv to work.
  Please run `rbenv init' and follow the instructions.

Checking `rbenv install` support: ~/.rbenv/plugins/ruby-build/bin/rbenv-install (ruby-build 20210611-1-g1b477ae)
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

If you run rbenv init you may see a message like this:

# Load rbenv automatically by appending
# the following to ~/.bashrc:

eval "$(rbenv init - bash)"

It seems that ~/.bashrc can be read before ~/.profile, because when adding the above to .bashrc I was still getting an error "command rbenv not found". So I had to give the path to rbenv in my .bashrc:

nano ~/.bashrc

Paste this at the bottom:

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

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

You should now be able to install a ruby version.

~$ rbenv install 3.2.0

(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.2.0 again.)

You should see output along these lines:

Installing ruby-3.2.0...
Installed ruby-3.2.0 to ~/.rbenv/versions/3.2.0

Test for the correct version of ruby

Now, running ruby --version from within the application directory should give you something like ruby 3.2.0 (2022-12-25 revision a528908271) [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.

Check your Rails environment

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

Since the rails gem is made available through bundler, it needs to be invoked with bundle exec. However you should also be able to invoke rails --version directly, seeing that a rails binstub has been included in the bin folder (it shouldn't be necessary to run bundle binstubs rails which will install an 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
About your application's environment
Rails version             7.0.4
Ruby version              ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-linux]
RubyGems version          3.4.2
Rack version              2.2.5
Middleware                ActionDispatch::HostAuthorization, Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, ActionDispatch::ServerTiming, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, WebConsole::Middleware, 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          /home/johnrdorazio/development/marriage-booklet
Environment               development
Database adapter          postgresql
Database schema version   20230104190635

Load the database schema

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

Check NodeJS environment

With Rails 7, node isn't strictly required. It may be needed to issue commands for the i18n-js CLI such as i18n export, or i18n lint:scripts or i18n lint:translations. For this reason we have kept the .nvmrc and .node-version files in the repository, so that if you need to use these commands you can install and automatically use a recent version of node (we suggest to use nvm and avm to install and automatically switch to the version of node indicated in these files).

Compile assets

Assets for the application (JS, CSS, and images) may need to be precompiled in order for the test environment to work correctly:

bundle exec rails assets:precompile

Run the App

After all dependencies are installed with Bundler, you can run the app in development mode with bundle exec rails server. In order for live reloading to work, you will need to have redis-server installed and running.

Using bin/dev (new in Rails 7 when CSS frameworks are associated with the rails applications) rather than bundle exec rails server will ensure that CSS assets are re-compiled after any changes are made.

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).

Contributing

Check out the dedicated wiki page Contributing a patch for more information.

If you contribute a patch that contains a user facing string, please don't hard code the string, but keep I18n in mind. See the dedicated wiki page Handling i18n for more info.

Translating

If you would like to contribute to the translations of the user facing strings in this project, you can do so by opening an issue requesting an account on the weblate server where translations take place.

Current state of translations: