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

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.
• index.html – The single-page application shell that loads jQuery, Mustache, and githubresume.js.
• 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, 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 for any root request. The browser then executes 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:

   gem install rack

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

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

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

   rackup config.ru

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

   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 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 for every route, allowing the client-side router in 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 consumes the GitHub REST API and renders views using the templates stored in views/resume.html.

Summary

• The resume.github.com application is a Rack-based static server that serves index.html and associated assets from the css/, js/, images/, and views/ directories.
• Client-side JavaScript in 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 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 (the main profile layout) and views/org.html (for organization displays). The client-side script 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, and all template rendering occurs client-side using the Mustache library loaded by index.html.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}