DEV Community

Cover image for How to setup WikiEduDashboard for OSS contribution
Ifeanyi Chima
Ifeanyi Chima

Posted on

How to setup WikiEduDashboard for OSS contribution

#javascript #webdev #programming #tutorial

1. Problem Statement

I wanted to contribute to an open source project called WikiEduDashboard, a web application built by Wiki Education. It helps instructors and program leaders run Wikipedia-editing classes and campaigns: students join a course, make edits to Wikipedia, and the dashboard tracks their work.

To contribute code to this project, I first need a working copy of it running on my own PC. This is called a "local development environment." Without it, I can't test any changes I make before sending them back to the project.

The problem: this project was built with tools that work best on Mac or Linux, not on plain Windows. So the first challenge wasn't even the project itself, it was figuring out how to run a Linux-friendly project on a Windows PC.

2. The Solution (High Level)

Instead of fighting Windows directly, we used a feature built into Windows called WSL (Windows Subsystem for Linux). WSL lets a real Linux system (Ubuntu, in our case) run inside Windows, side by side with your normal Windows apps. It's not a separate computer or a virtual machine you have to babysit, it just works like an extra terminal environment on the same PC.

Once inside Ubuntu, we could follow the project's official setup instructions exactly as written, since those instructions assume a Mac or Linux machine.

The overall plan looked like this:

  1. Get a Linux environment running on Windows (WSL + Ubuntu)
  2. Get a personal copy of the project's code (fork it on GitHub, then clone it)
  3. Install the programming language the project is built with (Ruby)
  4. Run the project's automated setup script, which installs the rest of the required tools (database, background job system, etc.)
  5. Start the actual application and view it in a browser
  6. Build the frontend (the visual, interactive part of the site)
  7. Set up an editor (VS Code) that can actually see and edit the code living inside Ubuntu

3. Step by Step: What We Did and Why

Step 1: Install WSL and Ubuntu

What: WSL is a Windows feature that runs a real Linux distribution (we used Ubuntu) inside Windows.

Why we needed it: WikiEduDashboard's setup script only officially supports Debian-based Linux (like Ubuntu), Fedora, and macOS. Plain Windows isn't supported well: things like Ruby, Redis, and MySQL are much harder to install and configure correctly on native Windows.

Command used (from PowerShell, as Administrator):

wsl --install
Enter fullscreen mode Exit fullscreen mode

After installing, opening "Ubuntu" from the Start menu gives a terminal prompt that looks like this:

adminuser@DESKTOP-OF73031:~$
Enter fullscreen mode Exit fullscreen mode

That ~ symbol means "home folder", it's the starting point for everything else we did.

Step 2: Confirm Git Was Available

What: Git is a tool used to download ("clone") and manage code from GitHub.

Why: We need it to grab a copy of the project's code onto our PC.

git --version
Enter fullscreen mode Exit fullscreen mode

This returned git version 2.43.0, confirming git was already installed inside Ubuntu.

Step 3: Fork and Clone the Repository

We forked the project on GitHub first (via the browser, clicking the "Fork" button on the project's page), then cloned our fork:

git clone https://github.com/YOUR_USERNAME/WikiEduDashboard.git
cd WikiEduDashboard
Enter fullscreen mode Exit fullscreen mode

Step 4: Install Ruby

What is Ruby? Ruby is the programming language WikiEduDashboard's backend (the "engine" of the app) is written in, specifically using a framework called Ruby on Rails.

Why we needed a specific version: The project requires Ruby 3.4.8 exactly. Running the setup script without Ruby installed gave this error:

ruby: command not found
Ruby-3.4.8 not found. Please install ruby-3.4.8 and run this script again.
Enter fullscreen mode Exit fullscreen mode

How we installed it: using a tool called RVM (Ruby Version Manager), which makes it easy to install and switch between specific Ruby versions.

Here is how we install the RVM tool, copy and paste this block of command into your ubuntu terminal

sudo apt update
sudo apt install -y gnupg2
gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable
source /home/adminuser/.rvm/scripts/rvm
rvm install "ruby-3.4.8"
Enter fullscreen mode Exit fullscreen mode

Confirming it worked:

ruby -v
Enter fullscreen mode Exit fullscreen mode

Result: ruby 3.4.8 (2025-12-17 revision 995b59f666) +PRISM [x86_64-linux]

Step 5: Run the Automated Setup Script

What: The project ships with a Python script (setup.py) that automates installing everything else the project needs: gems (Ruby's package system), a database (MySQL/MariaDB), configuration files, and JavaScript packages.

Why: Doing all of this by hand (the "manual setup" path in the project's docs) is long and error-prone. The script does it consistently.

python3 setup.py
Enter fullscreen mode Exit fullscreen mode

This script:

  • Installed Ruby "gems" (Ruby's version of code libraries/packages)
  • Created configuration files (config/application.yml and config/database.yml) from example templates
  • Created the development and test databases
  • Created a MySQL user for the app to use
  • Ran database migrations (setting up the actual tables the app needs)
  • Installed JavaScript packages using Yarn (a package manager for frontend/JavaScript code, similar in purpose to gem for Ruby)

At the end, it printed:

Your development environment setup is complete.
Enter fullscreen mode Exit fullscreen mode

Step 6: Start Redis

What is Redis? Redis is a fast, lightweight in-memory data store. In this project, it's used by a background job system called Sidekiq, which handles tasks like scheduled updates and syncing data, things that shouldn't slow down the main website while they run.

Why it matters: without Redis running, features that rely on background jobs (some Wikipedia-editing features especially) won't work properly.

redis-server
Enter fullscreen mode Exit fullscreen mode

We got an error saying the port was already in use:

Could not create server TCP listening socket *:6379: bind: Address already in use
Enter fullscreen mode Exit fullscreen mode

This actually meant Redis was already running in the background (likely started automatically during setup). We confirmed this instead of restarting it:

redis-cli ping
Enter fullscreen mode Exit fullscreen mode

Result: PONG, meaning Redis was alive and responding correctly.

Step 7: Start the Rails Server

What: This starts the actual backend server, the part that listens for requests and serves the website.

rails s
Enter fullscreen mode Exit fullscreen mode

Once running, it showed:

* Listening on http://127.0.0.1:3000
Use Ctrl-C to stop
Enter fullscreen mode Exit fullscreen mode

This means the app was now reachable at http://localhost:3000 in a browser. This terminal window needs to stay open and running the whole time the app is in use.

Step 8: Open the Frontend Build

open a second Ubuntu terminal window (leaving the first one running rails s untouched), move into the project folder, and run yarn start, see example below:

cd WikiEduDashboard
yarn start
Enter fullscreen mode Exit fullscreen mode

This compiles the frontend and also watches for future changes, automatically rebuilding when files are edited.

After this finished, refreshing http://localhost:3000 showed the actual dashboard homepage, fully styled and working, logged in as Chimaifeanyi29.

Step 9: Set Up VS Code to Edit the Code

The problem: the project's code physically lives inside the Ubuntu (WSL) filesystem, not in a normal Windows folder. Opening VS Code the usual way on Windows wouldn't show the right files.

The solution: VS Code has a "Remote - WSL" extension that lets it connect directly into the Ubuntu environment.

Steps:

  1. Install VS Code normally on Windows (if not already installed)
  2. Inside VS Code, go to the Extensions tab and install the extension called "WSL" (by Microsoft)
  3. From inside the Ubuntu terminal, inside the project folder, run: 
code .
Enter fullscreen mode Exit fullscreen mode

This opens VS Code on the Windows desktop, but connected directly to the Ubuntu filesystem, shown by a "WSL: Ubuntu" indicator in the bottom-left corner of the editor.

4. Summary: What's Currently Running

At the end of this session, the local development setup consists of three things running at once:

Component Purpose Where it runs
rails s The backend server (handles requests, talks to the database) Terminal 1
yarn start Builds and watches the frontend (JavaScript/React code) Terminal 2
Redis (background) Powers background jobs via Sidekiq Runs automatically

The app is reachable in a browser at:

http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

5. Key Terms Explained (Quick Reference)

  • WSL (Windows Subsystem for Linux): A way to run real Linux (Ubuntu, here) inside Windows without a separate computer or full virtual machine.
  • Fork: Your own personal copy of someone else's GitHub project, needed before you can propose changes back to it.
  • Clone: Downloading a copy of a GitHub project's code onto your own machine.
  • Ruby / Ruby on Rails: The programming language and web framework the backend of this project is built with.
  • RVM: A tool for installing and managing specific versions of Ruby.
  • Gems: Ruby's term for external code packages/libraries.
  • Yarn: A package manager for JavaScript, used here to install and build the frontend.
  • Redis: A fast in-memory data store, used to support background job processing.
  • Sidekiq: A background job system (built on Ruby) that uses Redis, used for scheduled tasks like data syncing.
  • Rails server (rails s): The command that starts the actual running web application.
  • manifest.json: A file generated by the frontend build process that tells the backend where compiled frontend assets live.

Top comments (0)