Recurse Roulette

Recurse Roulette

Spring 2020

Recurse Roulette is a project I helped build at the Recurse Center. It allows members of the community to randomly pair and chat with each other.

Recurse Roulette


Recurse Roulette opens a peer to peer connection between users using a WebRTC Javascript library called Peer JS. Recurse Roulette requires clients to connect to a signaling server to be paired. After they have been paired, they share video and audio streams via a peer to peer connection.

Tech Stack

  • Peer.js - used to make peer to peer connection on the client-side through WebRTC
  • Express and Node - used for the signaling server
  • JS Classic - used for client-side logic

Recurse Authentication

Recurse Roulette requires users to authenticate with Recurse Center before signing in. Check out the Wiki for more details. Once Recursers have authenticated, they are remembered through express sessions.

Server Code

When a client connects to the server, that client is given a peer ID. The server keeps track of the peer IDs as they connect. When a client requests to connect to another client, the server returns a list of available peers to connect to and the client randomly picks an id from this list. Once two peers are connected, both peer ids are removed from this list. The server also keeps track of all online clients. When a client ends a connection with another client, their peer id is destroyed and they are taken. To rejoin, they reconnect and are given a new peer id. The sever exposes three endpoints for the client to use:


This returns the list of available peers to connect do.


This removes the specified id from the peer set. The client sends their own id upon a successful stream/call connection.


This returns the total number of peers who are online. When clients hang up, their peer ID is destroyed and removed from this list.

Client Code

When the client connects to the signaling server, a new peer object is created for that client.

peer = new Peer({...});

Listeners are assigned for incoming connections from other peers

peer.on("call", async function (call)
peer.on("connection", function (conn)

Once a peer object is created, the client will try to initiate a data connection (peer.connect) and a media stream ( with the first available peer.

peerCall =, stream);
peerConn = peer.connect(firstAvailablePeer);

Once the connection is made the peers can share media streams and data. Once the connection is closed, the client destroys the peer object.


Contributing Guide

We hope that future Recursers will enjoy using Recurse Roulette, and we are more than excited if you want to contribute! Here are some guidelines for contributing and running Recurse Roulette locally. If you have any questions, please feel free to contact us on Zulip.

Submitting a pull request

  1. Fork and clone the repository
    git clone[your-username]/recurse-roulette-server
  2. Create a new branch from master:
    git checkout -b new-feature-name
  3. Run npm install to make sure you have the latest dependencies
  4. Make your changes
  5. Push to your fork and submit a pull request through Github

Deployment Guide

Running Recurse Roulette locally

  1. Clone the repository from Github, or create a fork.
    git clone
  2. Run npm install to make sure you have the latest dependencies
  3. Copy the values in .env.sample to a new .env file and make sure that DEVELOPMENT=TRUE(OAuth values are not needed for local development)
  4. Run npm start from the root

Deploying with Heroku

  1. Follow the steps above to get Recurse Roulette running locally
  2. Set up an OAuth app on Recurse on your settings page
  3. Replaces the values for ID and SECRET in your .env file with your
  4. Copy these values to a new .env file
  5. In your .env file change the value of DEVELOPMENT to DEVELOPMENT=FALSE
  6. Create a new Heroku app
  7. Change the hostname in index.html to the URL of your Heroku instance
  8. Configure the Heroku environment variables
  9. Follow Heroku’s steps for deployment
  10. To set up your own Recurse domain, go to your Recurse account

Recurse Roulette Team

Picture of George Madis
George Mandis
Picture of Sam Lazarus
Sam Lazarus
Picture of Allison Colyer
Alli Colyer
Picture of Asa Needle
Asa Needle