Setting Up Binder Development

Follow these instructions to get Binder running locally on your computer for testing and development!

Pre-Setup for Windows Users

Setting up Binder development is significantly easier on Linux and MacOS, so your best option is to set up a Linux subsystem such as Ubuntu. For Windows 10+, simply run

wsl --install

in PowerShell and create a username and password you can remember for your Linux subsystem. You can now follow the guide below as a Linux user with the 'Ubuntu' application. Note that some Windows users have also found they need to preface all further commands with sudo to run as a privileged user.

For more information or installation instructions for older versions of Windows, read https://learn.microsoft.com/en-us/windows/wsl/install

Installing Git

Binder uses git for version control and to easily distribute source code. You may already have it installed (Run git --version from the command line to check). Instructions to install git can be found at https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Fork and clone the Binder repository on Github

Fork Binder using the "Fork" Button in the top right of the Github screen, and clone your forked repository

git clone https://github.com/link_to/your_binder binder

Set up dependencies for Binder development

Binder uses Docker to manage dependencies and make setting up your development environment easier! If you don't already have docker on your computer, visit https://www.docker.com/ to download Docker Desktop.

Note for Windows Users: Since you're running Binder through an Ubuntu subsystem and not your computer itself, it may be easier to download Docker through the command line. Read https://docs.docker.com/engine/install/ubuntu/ for more information.

Then, before the first time running Binder you need to build the Binder Docker image that includes all of the code and dependencies required to run Binder using

docker compose build.

Run Binder Locally

Once the Binder Docker image has been built, start the Binder image by running

./binder rails s

Note that if you get a "Permission Denied" error, you may need to run chmod +x binder and try again.

After a few seconds, you should be able to visit your local Binder instance at http://localhost:3000!

At this point you may receive an error about pending migrations your first time running Binder, run the following two commands to set up the database:

./binder rails db:migrate

./binder rails db:fixtures:load

Refreshing the localhost page should now show Binder properly.

Run Other Rails Commands

Occasionally, we want to run other commands related to Binder for testing (e.g. rails console). You can run any traditional rails command by running

./binder [command to run]

Note that if you get a "Permission Denied" error, you may need to run chmod +x binder and try again.

VSCode Extension

VSCode doesn't support Ruby syntax highlighting natively. A Ruby LSP Extension such as Shopify's can make it easier to figure out what's going on in a Rails file.