Windows Dev Setup Guide

For Windows development, we recommend using Windows Subsystem for Linux as this closely resembles the architecture the final app is deployed to in production and is the most common way to run a Rails app on Windows.

Follow the steps below to get that setup.

Install WSL

Open Powershell and run:

wsl --install -d Ubuntu

Restart your computer as instructed, set your username and password, and run "Ubuntu" to use the WSL shell.

Install Ruby

Find the required Ruby version here.

First, update package repository and install dependencies:

sudo apt-get update

sudo apt-get install git-core zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev

Now, install rbenv:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Restart your shell for changes to take effect. Then, install a Ruby version:

rbenv install <required-ruby-version>

At this point, you may run into issues as the Debian and Ubuntu repositories do not keep an updated version of rbenv. To solve this, you can install ruby-build with the following command:

cd "$(rbenv root)"/plugins/ruby-build && git pull

If you run into issues, please see the troubleshooting guide below.

Once you have it working, install the Ruby version and set it as the default on your machine if desired:

rbenv install <required-ruby-version>
rbenv global <required-ruby-version>

Check your Ruby version:

ruby -v

If this still does not show the correct version, you may need to run the following commands to avoid conflicting binaries:

rbenv local --unset
rbenv shell --unset

Install PostgreSQL

Install Postgres and start it as a service:

sudo apt install postgresql libpq-dev

sudo service postgresql start

Start the Project

Start by forking and then cloning the repo locally. Then run the following commands to start the app:

cd maybe
cp .env.example .env
bundle install
bin/rails db:setup
bin/dev

Troubleshooting

rbenv doesn't show latest version of Ruby

I'm attempting to install version 3.3.1 of Ruby, but my terminal says version 3.3.1 is not available?

Run the following command to list the available versions of ruby that can be installed by the rbenv's ruby-build plugin.

rbenv install --list

If version '3.3.1' is not listed as one of the options within the displayed list, you may need to upgrade rbenv's ruby-build installation to gain access to Ruby Version 3.3.1. To update ruby-build, simply enter the following command:

cd "$(rbenv root)"/plugins/ruby-build && git pull

Run the --list command again to determine whether Ruby Version 3.3.0 can now be downloaded.

Cannot set default Ruby version

I've installed Ruby 3.3.1 via rbenv and set it as my default Ruby version. However, a different version of Ruby is still listed as my default?

If rbenv global 3.3.1 seems to run but doesn't change the Ruby version, your shell might be using a different ruby installation (such as one installed via apt). Confirm that you are using the rbenv managed version of ruby by running this command:

which ruby

When using rbenv, this command should usually list the home directory /root/.rbenv/shims/ruby as the location of your ruby installation. If the command lists the /usr/bin/ruby directory, or another separate directory, this likely means you are using an outside installation of ruby rather than the one managed by rbenv.

To remedy this, add the following lines to the end of your /root/.bashrc file:

export PATH="/root/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Save the file, reload your shell profile, and verify that you're using the rbenv managed ruby installation by running these commands:

source /root/.bashrc
echo $PATH
which ruby

If everything looks fine but the wrong version of Ruby is still installed, you may need to run the following commands to avoid conflicting binaries:

rbenv local --unset
rbenv shell --unset

Postgres Permission Errors when running app

For rails/bin db:setup to work properly, you may have to provision a Postgres user:

CREATE USER maybe WITH PASSWORD 'postgres';
-- more granular permissions would probably work, but this is just for local dev
ALTER USER maybe WITH SUPERUSER;

Then, update POSTGRES_USER in .env to equal maybe.

Foreman not found

$ bin/dev
bin/dev: 16: exec: foreman: not found

Run the following command to fix this:

rbenv rehash

This will reshim existing gems.