Dept. of Computer Science & Engineering
CSE 3901: Web Applications (Autumn 2025)

Setting up a Development Environment

Last updated: August 15, 2025

Overview

Development for CSE 3901 projects is done locally (ie on your own computer) inside a Docker container and using VSCode. In Windows, using Docker requires also installing WSL2.

Tools

Setup Instructions

Terminal

On Windows, use the Windows Terminal. If you have Windows 11 22H2 or later, there is nothing to do because this is already the default terminal application. If you have an earlier version of Windows, install Windows Terminal by following these directions.

On MacOS, a terminal can be opened using Spotlight search: hit Command + Spacebar, then type “terminal”. (Aside: on macOS 10.15 Catalina and later, the default shell is zsh.)

GitHub

If you don’t already have one, create an account on GitHub. After creating an account, apply for the GitHub education benefits, which gives you GitHub Pro features for free.

Git

You may already have Git installed. Check by opening a terminal and running:

$ git --version
git version 2.43.1 # Your version may be different

If Git is not installed, download and install it for your platform from the Git website. (Aside for Windows: after installation is complete, Windows Terminal has a new profile available called “Git Bash”.)

Configure Git to use your name and email address, and to follow modern naming conventions. For your Git email address, use an address that is associated with your GitHub account. A good choice for your Git email address is the noreply address provided by GitHub in the form of ID+USERNAME@users.noreply.github.com found under Settings > Emails > Keep my email addresses private.

$ git config --global user.name "Your Name" 
$ git config --global user.email "you@domain"
$ git config --global init.defaultBranch main

VSCode

Download and install VSCode for your platform from the VSCode website. Review the Getting Started Guide to learn about some of the editor’s basic features.

Install the following VSCode extensions:

(Aside: Individual project dev containers will also have other extensions, such as Ruby LSP, and markdownlint; but there is no need to install these now.)

WSL2

On MacOS, skip this step. Go on to the installation of Docker.

On Windows, install WSL2 (Windows Subsystem for Linux, v2). Note: Installing WSL2 results in a separate file system. Your development work for 3901 will occur in this WSL file system (e.g., /home/jdoe/3901/lab1), not the Windows file system (e.g., C:\Users\jdoe\3901\lab1).

After completing the installation of WSL2, Windows Terminal has a new profile named “Ubuntu”.

From this WSL terminal, configure Git to use a credential manager:

$ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Docker

Install Docker Desktop for your platform from the Docker website. On Windows, choose the “WSL 2 backend”.

You do not need to sign up for a Docker account, and you do not need a paid subscription.

Smoke Test

The following steps confirm that your development environment is set up correctly. Since each step builds on the previous one, it’s important to complete them in order. If you encounter any issues, please refer to the troubleshooting section below. Help is also available in the class discussion forum.

  1. Using the terminal.

    In a terminal window (for Windows, in WSL2), create a new directory:

    $ uname -a
# output should start with Linux... (in WSL) or Darwin... (Mac)
# it should *not* start with anything else, like MINGW64 
$ mkdir hello
$ ls -la
... # etc
drwxr-xr-x  7 <user> <user>    4096 <Date-time> hello/
... # etc
$ cd hello
$ ls -pa # new directory is empty
./  ../

  2. Using Git.

    Inside the hello directory, initialize a Git repository:

    $ pwd # confirm you are in the right place
/<path>/hello
$ git init
Initialized empty Git repository in /<path>/hello/.git/
$ git commit
On branch main

Initial commit

nothing to commit (create/copy files and use "git add" to track)

  3. Launching VSCode and creating a DevContainer.

    Open the hello directory in VSCode:

    $ pwd # confirm you are in the right place
/<path>/hello
$ code . # open VSCode in the current directory (hello/)

    Notice the bottom left blue Remote Development status icon. For Windows setup, it should say “><WSL: ...”. For Mac setup, it should say “><”.

    In VSCode: Use the Command Palette to run Dev Containers: Reopen in Container > Ruby (from devcontainers). Accept all the defaults: default Ruby version (3.4-bullseye), no additional features, no optional files.

    When VSCode re-opens, the bottom-left blue Remote Development status icon has changed: Dev Container: Ruby. Also, the project now contains a .devcontainer/ folder with a devcontainer.json file.

  4. Working inside the DevContainer.

    Open the terminal in VSCode and confirm the container environment:

    $ whoami
vscode
$ lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description:    Debian GNU/Linux 11 (bullseye)
Release:        11
Codename:       bullseye
$ ruby -v
ruby 3.4.x # x is some point-release number

    The VSCode terminal is running inside the container, not on your host machine.

  5. Running a Ruby program in the container.

    Create a greeting.rb file. Add the following line:

    puts 'Hello World!'

    Run the program from the terminal in VSCode:

    $ ruby greeting.rb
Hello World!

  6. Using Git in the container

    From the terminal in VSCode:

    $ git add .
$ git commit -m "Initial commit"
[main (root-commit) cf9ce79] Initial commit
1 file changed, 1 insertion(+)
create mode 100644 greeting.rb

    Close VSCode. You can also delete the hello directory.

  7. Creating a Rails app with rails-new

    Download the rails-new script from the GitHub repo. Note: Look in “Artifacts” to find the appropriate version. On Windows, download the linux version.

    In a host terminal (for Windows, in WSL2), run the script to create a new Rails app:

    $ ./rails-new -u 3.3.8 -r 7.2.2 my-app --devcontainer
... # lots of output, ending with "run bundle install --quiet"

    Open the my-app directory in VSCode, then “Reopen in Container”.

    $ code my-app
# when prompted, click blue button to reopen in container
# or run "Dev Containers: Reopen in Container" in the command palette

    From the terminal in VSCode, run the Rails server:

    $ rails server
 => Booting Puma
 => Rails 7.2.2 application starting in development
 => Run `bin/rails server --help` for more startup options

Troubleshooting

Can’t initialize the git repo: “potentially unsafe” (Windows)

Problem: “The detected Git repository is potentially unsafe”, asks you to “Manage Unsafe Repositories”.

Solution: Create the directory in the WSL2 filesystem, not Windows.

Ruby-LSP Activation Error: General

Problem: Ruby-LSP fails to recognize the Ruby version, or the Ruby version management tool (rbenv, rvm, mise). Symptoms might include the brace icon {} in the lower right corner having an “x”.

Solution: Try VSCode’s “Developer: Reload Window” to give the Ruby-LSP a fresh start.

Ruby-LSP Pop-up “Automatic Ruby env activation with rbenv failed”

Problem: VSCode pop-up error during Ruby-LSP activation, complaining that “Automatic Ruby env activation with rbenv failed”. Offers a “Configure Ruby version” button.

Solution: Set the Ruby version manually. First find the path to the Ruby binary:

$ which ruby
/home/vscode/.local/share/mise/installs/ruby/3.4.1/bin/ruby

Then, in the pop-up, select “Configure for the workspace” and use the path you found above.

Also: Sometimes, it helps to do a “Developer: Reload Window” in VSCode.

Error Reopening in Container: Workspace does not exist

Problem: When trying to reopen the workspace in the container, you get an error like: “Workspace does not exist. Please select another workspace to open.”

Solution: Confirm that Docker Desktop has enabled WSL integration for the distro you are using. Rebuild the container.

(MacOS) rails-new: Can’t run script

Problem: MacOS security prevents running the rails-new script, and you don’t get a prompt to override the security setting.

Solution: Go into Setting > Privacy & Security, scroll down to Security. Find the entry that indicates that it denied rails-new and click “Allow Anyway”.

rails-new: “GLIBC_2.39 not found”

Problem: When running the rails-new script, you get an error like:

$ ./rails-new my-app
./rails-new: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.39' not found (required by ./rails-new)`

Solution: Update to newer version of Ubuntu. rails-new requires Ubuntu 24.04.

Error installing gems: “write permissions” (Windows)

Problem: When running the rails-new script, you get an error that you can’t install gems:

Install missing gems with `bundle install`
Fetching gem metadata from https://rubygems.org/.........
... etc (all gems install ok)
There was an error while trying to write to `/workspaces/store5/Gemfile.lock`.
It is likely that you need to grant write permissions for that path.
bin/setup:7:in 'Kernel#system': Command failed with exit 23: bundle (RuntimeError)
        from bin/setup:7:in 'Object#system!'
        from bin/setup:16:in 'block in <main>'
        from /home/vscode/.local/share/mise/installs/ruby/3.4.5/lib/ruby/3.4.0/fileutils.rb:241:in 'Dir.chdir'
        from /home/vscode/.local/share/mise/installs/ruby/3.4.5/lib/ruby/3.4.0/fileutils.rb:241:in 'FileUtils#cd'
        from bin/setup:10:in '<main>'

The problem is that the files are owned by root, so they can’t be edited by vscode user in container. (This may only be an issue for rails-new run in windows?) Mounting Windows folders in dev containers is a bit tricky, we want to do our development in the WSL2 filesystem, not Windows.

Solution: download the linux version of rails-new, and run it from WSL.