This guide will walk you through setting up the neccessary environment using WSL (Windows Subsystem for Linux), which will allow you to run Ubuntu on your Windows machine.

You will need the following local tools installed:

WSL
Ruby
NodeJs (optional)
Postgres
Google Chrome

WSL (Windows Subsystem for Linux)

Install WSL.

wsl --install

The above command only works if WSL is not installed at all, if you run wsl --install and see the WSL help text, do --install -d Ubuntu
Run Ubuntu on Windows

You can run Ubuntu on Windows several different ways, but we suggest using Windows Terminal.

To open an Ubuntu tab in Terminal, click the downward arrow and choose 'Ubuntu'.

The following commands should all be run in an Ubuntu window.

Ruby

Install a ruby version manager like rbenv

Be sure to install the ruby version in .ruby-version. Right now that's Ruby 3.3.6.

Instructions for rbenv:

Install rbenv

sudo apt install rbenv
Set up rbenv in your shell

rbenv init
Close your Terminal window and open a new one so your changes take effect.
Verify that rbenv is properly set up

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | bash
Install Ruby

Be sure to install the ruby version in .ruby-version. Right now that's Ruby 3.3.6.

rbenv install 3.3.6
Set a Ruby version to finish installation and start

rbenv global 3.3.6 OR rbenv local 3.3.6

Troubleshooting

If you are on Ubuntu in Windows Subsystem for Linux (WSL) and `rbenv install` indicates that the Ruby version is unavailable, you might be using Ubuntu's default install of `ruby-build`, which only comes with old installs of Ruby (ending before 2.6.) You should uninstall rvm and ruby-build's apt packages (`apt remove rvm ruby-build`) and install them with Git like this:

- `git clone https://github.com/rbenv/rbenv.git ~/.rbenv`
- `echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc`
- `echo 'eval "$(rbenv init -)"' >> ~/.bashrc`
- `exec $SHELL`
- `git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build`

You'll probably hit a problem where ruby-version reads `ruby-2.7.2` but the install available to you is called `2.7.2`. If you do, install [rbenv-alias](https://github.com/tpope/rbenv-aliases) and create an alias between the two.

NodeJS

The Casa package frontend leverages several javascript packages managed through npm, so if you are working on those elements you will want to have node, npm.

(Recommended) Install nvm

NVM is a node version manager.

Postgres

Install PostgresSQL for WSL

sudo apt install postgresql postgresql-contrib - install

psql --version - confirm installation and see version number
Install libpq-dev library

sudo apt-get install libpq-dev
Start your postgresql service

sudo service postgresql start

Google Chrome

Many of the frontend tests are run using Google Chrome, so if you don't already have that installed you may wish to install it.

For some linux distributions, installing chromium-browser may be enough on WSL. However, some versions of Ubuntu may require the chromium snap to be installed in order to use chromium. If you receive errors about needing the chromium snap while running the test suite, you can install Chrome and chromedriver instead:

Download and Install Chrome on WSL Ubuntu

Update your packages:

sudo apt update
Download Chrome:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
Install chrome from the downloaded file

sudo dpkg -i google-chrome-stable_current_amd64.deb

sudo apt-get install -f
Check that Chrome is installed correctly

google-chrome --version

Install the appropriate Chromedriver

Depending on the version of google-chrome you installed, you will need a specific chromedriver. You can see which version you need on the chromedriver dowload page.
- For example, if google-chrome --version returns 105.x.xxxx.xxx you will want to download the version of chromedriver recommended on the page for version 105.
- As of this writing, the download page says the following for Chrome version 105:
  
  If you are using Chrome version 105, please download ChromeDriver 105.0.5195.52
To download chromedriver, run the following command, replacing {CHROMEDRIVER-VERSION} with the version of chromedriver you need (e.g., 105.0.5195.52)

wget https://chromedriver.storage.googleapis.com/{CHROMEDRIVER-VERSION}/chromedriver_linux64.zip
Next, unzip the file you downloaded

unzip chromedriver_linux64.zip
Finally, move chromedriver to the correct location and enable it for use:

sudo mv chromedriver /usr/bin/chromedriver

sudo chown root:root /usr/bin/chromedriver

sudo chmod +x /usr/bin/chromedriver

Run the test suite

Assuming the rest of the application is already set up, you can run the test suite to verify that you no longer receive error regarding chromium snap: bin/rails spec

Casa & Rails

Casa's install will also install the correct version of Rails.

Download the project

You should create a fork in GitHub if you don't have permission to directly commit to this repo. See our contributing guide for more detailed instructions.

git clone <git address> - use your fork's address if you have one

ie

git clone https://github.com/rubyforgood/casa.git
Installing Packages

cd casa/

bundle install - install ruby dependencies.

npm install - install javascript dependencies.
Database Setup

Be sure your postgres service is running (sudo service postgresql start).

Create a postgres user that matches your Ubuntu user:

sudo -u postgres createuser <username> - create user

sudo -u postgres psql - logs in as the postgres user

psql=# alter user <username> with encrypted password '<password>'; - add password

psql=# alter user <username> CREATEDB; - give permission to your user to create databases

Set up the Casa DB

bin/rails db:setup - sets up the db

bin/rails db:seed:replant - generates test data (can be rerun to regenerate test data)
Compile Assets

npm run build compile javascript npm run build:dev to auto recompile for when you edit js files
npm run build:css compile css npm run build:css:dev to auto recompile for when you edit sass files

Getting Started

See Running the App / Verifying Installation.

A good option for editing files in WSL is Visual Studio Code Remote- WSL

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!