Setting up a development environment (WSL Ubuntu)

This page covers local development setup on Windows using WSL Ubuntu. For production deployment instructions, see Deploy the application.

Install WSL / Ubuntu

Use the current Microsoft WSL instructions: https://learn.microsoft.com/en-us/windows/wsl/install

In short:

  1. Install WSL (from an elevated PowerShell):
wsl --install
  1. Launch Ubuntu after reboot.
  2. Create your UNIX username and password.

Install base apt dependencies

Update package lists, then install the dependencies used by the current local setup:

sudo apt update
sudo apt install -y \
  build-essential git curl unzip pkg-config \
  rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev \
  default-libmysqlclient-dev libpq-dev postgresql-client \
  libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev \
  imagemagick libvips shared-mime-info \
  openjdk-17-jre-headless

Install mise

Install and activate mise for Bash:

curl https://mise.run | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

Verify installation:

mise --version
mise doctor

Runtime setup model

mise is the preferred runtime manager for local development.

  • Global Ruby can be installed with mise if you want a default outside projects.
  • GeoDiscovery uses project-local runtime versions declared in mise.toml.
  • Current project runtime targets are:
    • ruby = "3.2.1"
    • node = "20"

The repository also includes .ruby-version and Ruby pinning in Gemfile for compatibility, but mise.toml is the preferred multi-runtime local-dev setup.

Clone the repository 

git clone git@github.com:UWM-Libraries/GeoDiscovery.git
cd GeoDiscovery
mise install

Configure env files

Copy the local env files:

cp .example.env.test .env.test
cp .example.env.development .env.development

Local development expects:

  • Solr on port 8983
  • Rails on port 3000
  • A Redis URL may be present in .env.development, but local bootstrap is focused on Solr + Rails unless your feature specifically needs Redis

Install app dependencies 

bundle install
corepack enable
yarn install

Notes:

  • package.json pins Yarn via the packageManager field, so use Corepack-managed Yarn instead of globally installed Yarn.
  • Node 20 is intentional for this project; the frontend dependency tree requires newer Node than 18.

Database setup (SQLite for local dev/test) 

bundle exec rake db:create
bundle exec rake db:migrate

Start the app 

bundle exec rake uwm:server

This task starts the local app stack plus the local Solr wrapper. Java must be installed or Solr startup will fail.

Run tests

Run tests explicitly in the test environment so commands do not run against development data:

RAILS_ENV=test bundle exec rake test

RAILS_ENV=test bundle exec rails test:system

Browser requirement for system tests

GeoDiscovery system tests use Capybara with a Chrome-family browser. Local system-test execution requires Chrome or Chromium installed and discoverable on PATH. Package names can vary by Ubuntu release.

which google-chrome || which chromium || which chromium-browser