# How to Set Up and Run the GitHub Résumé Application Locally Using Rack

> Easily set up and run the GitHub Résumé application locally using Rack. Clone the repo, install rack, and launch your local server to render GitHub profiles.

- Repository: [GitHub resume generator/resume.github.com](https://github.com/resume/resume.github.com)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Clone the resume.github.com repository, install the `rack` gem, and execute `rackup config.ru` to start a local server on port 9292, then navigate to `http://localhost:9292/?username` to render any public GitHub profile.**

The resume.github.com project is a minimalist Rack-based web application that generates visual résumés from GitHub public data. Because all GitHub API queries and template rendering occur client-side via JavaScript, the server requires only Ruby and the Rack gem to serve static assets and the entry-point HTML file.

## Architecture and File Structure

The application follows a static-site pattern where Rack handles HTTP requests and the browser performs all data processing:

- **`config.ru`** – The Rack entry point that configures `Rack::Static` middleware to serve assets from `/css`, `/images`, `/js`, and `/views`, while routing all other requests to [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html).
- **[`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html)** – The single-page application shell that loads jQuery, Mustache, and [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js).
- **[`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js)** – The client-side controller that fetches GitHub user data via the public API and injects it into Mustache templates.
- **`views/`** – Directory containing Mustache templates (e.g., [`resume.html`](https://github.com/resume/resume.github.com/blob/main/resume.html), [`org.html`](https://github.com/resume/resume.github.com/blob/main/org.html)) that define the résumé layout sections.

When you run `rackup config.ru`, the server either returns a static asset (CSS, images, or templates) or streams [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html) for any root request. The browser then executes [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js), which queries `api.github.com` for user repositories, contributions, and profile data, rendering the final résumé without further server involvement.

## Prerequisites

Before starting the application, ensure your environment meets these minimal requirements:

- **Ruby** version 2.0 or higher (any modern Ruby installation suffices).
- The **rack** gem installed globally or within a local gemset.

## Step-by-Step Local Setup

Follow these commands to clone the repository and launch the Rack server:

1. **Install the Rack gem** if it is not already present:

   ```bash
   gem install rack
   ```

2. **Clone the repository** and change into the project directory:

   ```bash
   git clone https://github.com/resume/resume.github.com.git
   cd resume.github.com
   ```

3. **Start the Rack server** using the provided configuration file:

   ```bash
   rackup config.ru
   ```

   By default, the server binds to `http://localhost:9292`. To specify a different port, use the `-p` flag:

   ```bash
   rackup -p 8080 config.ru
   ```

4. **Access the application** by opening a browser and appending a GitHub username as a query parameter:

   ```

   http://localhost:9292/?octocat
   ```

   Replace `octocat` with any public GitHub username to generate that user's résumé.

## Understanding the Rack Configuration

The `config.ru` file implements a minimal Rack interface (`call(env) -> [status, headers, body]`) that efficiently serves the application without a full-stack framework. According to the resume.github.com source code, the configuration mounts `Rack::Static` to handle four asset directories—`css`, `images`, `js`, and `views`—while a custom proc returns [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html) for all non-asset requests. This design enables clean URLs (e.g., `/?username` rather than `/index.html?username`) and keeps the server footprint to a few hundred lines of Ruby.

## Why Rack for a Static Application?

The project uses Rack instead of a heavier framework like Rails or Sinatra because the server has no dynamic backend logic to execute. Rack provides exactly what is needed:

- **Static asset delivery** via `Rack::Static`, which efficiently streams CSS, JavaScript, and Mustache templates from the filesystem.
- **Single-page entry point** handling that serves [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html) for every route, allowing the client-side router in [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js) to manage application state.

This architecture keeps dependencies minimal (only the `rack` gem) while delegating all data fetching and templating to the browser, where [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js) consumes the GitHub REST API and renders views using the templates stored in [`views/resume.html`](https://github.com/resume/resume.github.com/blob/main/views/resume.html).

## Summary

- The resume.github.com application is a Rack-based static server that serves [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html) and associated assets from the `css/`, `js/`, `images/`, and `views/` directories.
- Client-side JavaScript in [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js) handles all GitHub API communication and template rendering using Mustache files from the `views/` directory.
- To run locally, execute `rackup config.ru` after installing the `rack` gem; the server defaults to `localhost:9292`.
- Access any public GitHub profile by navigating to `http://localhost:9292/?username`.
- The Rack configuration in `config.ru` uses `Rack::Static` for assets and falls back to the root HTML file for all other requests, requiring no database or server-side processing.

## Frequently Asked Questions

### Do I need a GitHub API token to run this application locally?

No. The application does not require a GitHub API token for local development because [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js) makes unauthenticated requests to the GitHub public API. However, unauthenticated requests are subject to lower rate limits (60 requests per hour per IP address), so heavy local testing may temporarily trigger rate limiting.

### Can I use a different port than 9292 when running locally?

Yes. While `rackup config.ru` defaults to port 9292, you can specify an alternative port using the `-p` or `--port` flag. For example, `rackup -p 3000 config.ru` serves the application on `localhost:3000`. This is useful when port 9292 is already occupied by another service.

### Where are the résumé layout templates stored?

The Mustache templates that define the résumé structure reside in the `views/` directory at the repository root. Key files include [`views/resume.html`](https://github.com/resume/resume.github.com/blob/main/views/resume.html) (the main profile layout) and [`views/org.html`](https://github.com/resume/resume.github.com/blob/main/views/org.html) (for organization displays). The client-side script [`js/githubresume.js`](https://github.com/resume/resume.github.com/blob/main/js/githubresume.js) fetches these templates via HTTP and merges them with GitHub API data before injecting the final HTML into the DOM.

### Does the Rack server process any GitHub data itself?

No. The Rack server (`config.ru`) functions solely as a static file server. It never contacts the GitHub API or processes user data. All API requests originate from the browser executing [`githubresume.js`](https://github.com/resume/resume.github.com/blob/main/githubresume.js), and all template rendering occurs client-side using the Mustache library loaded by [`index.html`](https://github.com/resume/resume.github.com/blob/main/index.html).