Skip to content
Get packs

Guide · Open source

How to use Gumroad: run the source code locally

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gumroad is an e-commerce platform that lets creators sell products directly to consumers. The antiwork/gumroad repository holds the source code for the Gumroad web application, so developers can read it, run it on their own machine, and contribute changes. This guide walks through the local development setup described in the README, so you know what to install and in what order.

Gumroadantiwork/gumroad · ★ 10.1k · MIT

Quick start

  1. 1Check prerequisites. Install Ruby, Node.js, Docker, MySQL 8.4.x and ImageMagick at the versions the repository files specify.
  2. 2Install Bundler and gems. Run gem install bundler, then bundle install, then gem install dotenv.
  3. 3Install Node dependencies. Run corepack enable to select the correct npm, then npm install.
  4. 4Start Docker services. Run make local in one terminal and keep it running.
  5. 5Prepare the database. Run bin/rails db:prepare in a second terminal.
  6. 6Start the app. Run bin/dev and open http://localhost:3000 in your browser.

Who this setup is for

Running this repository is a developer task, not a way to open a store. If you only want to sell products, the README points you to the hosted service at gumroad.com instead.

The setup assumes you already know Ruby and Rails and are comfortable with a database and Docker. It involves many moving parts, so beginners with no Ruby or database experience will likely struggle.

  • Developers studying how a production e-commerce web app is built
  • Engineers who already know Ruby and Rails and want to run the app locally
  • Contributors who will follow the project's contribution process

Install the prerequisites before you start

You need Ruby and Node.js at the versions named in the repository files, plus Docker, MySQL 8.4.x and several command-line tools. The README links to official installation pages for Ruby and Node.js.

Use the version in .ruby-version for Ruby and the version in .node-version for Node.js. On Windows, the README says to follow its separate Windows setup guide (docs/development/windows.md) instead.

  • Ruby (version in .ruby-version)
  • Node.js (version in .node-version)
  • Docker (Docker Desktop on macOS, or Docker via a package manager on Linux)
  • MySQL 8.4.x, matched to production, used as a dependency of the mysql2 gem
  • ImageMagick, used for preview editing
  • FFmpeg, which provides ffprobe for video metadata
  • PDFtk, used to stamp PDFs
  • wkhtmltopdf, which PDFKit needs to create invoices
brew install imagemagick sudo apt-get install imagemagick

Install Bundler, Ruby gems and Node dependencies

Install Bundler first, then the Ruby gems. The README also asks you to install dotenv, which some console commands require.

For Node, enable the correct npm version with corepack, then install the Node dependencies.

gem install bundler bundle install gem install dotenv corepack enable npm install

Configure credentials (optional)

The app can boot without any custom credentials. If you want services that need them, such as S3, Stripe or Resend, copy the .env.example file to .env and fill in the values.

cp .env.example .env

Start Docker services, set up the database and run the app

Start the Docker services with make local in one terminal tab. The command keeps running, so open a second tab for the application. On Linux, or if you installed Docker through a package manager on a Mac, use sudo make local so the container ports can be exposed. Set LOCAL_DETACHED=true to run the services in the background.

Then prepare the database and start the application. bin/dev starts the Rails server, the JavaScript build system and a Sidekiq worker. The app is then at http://localhost:3000, and seller subdomains such as http://seller.localhost:3000 also resolve without editing /etc/hosts.

On Debian or Ubuntu you might first need libxslt-dev and libxml2-dev.

  • Terminal 1: make local
  • Terminal 2: bin/rails db:prepare, then bin/dev
  • Open http://localhost:3000
make local bin/rails db:prepare bin/dev

Know the local limitations

Some features need HTTPS or a registrable cookie domain, so they do not work on plain localhost. Apple Pay needs HTTPS for domain registration, and the README suggests exposing the app with ngrok. Cross-subdomain cookies, used for affiliate attribution, the _gumroad_guid cookie, switching sellers and sessions, are rejected on localhost, so test those flows on a single host or behind a local HTTPS proxy.

  • Apple Pay: expose the app over HTTPS with ngrok and register the hostname in the Stripe dashboard
  • Cross-subdomain cookies: test on one host, or use a local HTTPS proxy on a hostname such as gumroad.test
ngrok http 3000

Run the tests and log in to the seeded app

Run the full suite with bin/rspec, or a single file or line. Before running tests, start Docker services, set up the test database and generate the JS constants for the test environment. Integration specs use Capybara with Selenium and need Chrome installed.

To log in to the development app, the README lists a seller account. Elasticsearch indices must be reindexed after setup, or you will see index_not_found_exception errors.

  • Username: seller@gumroad.com
  • Password: password
  • Two-factor code: 000000
bin/rspec bin/rspec spec/requests/dashboard_spec.rb RAILS_ENV=test bin/rails db:setup RAILS_ENV=test bin/rails js:export

What people use it for

  • Reading the source of a production e-commerce Rails app to study its structure
  • Running the app locally to test a change before opening a pull request
  • Running the RSpec suite to check code behaviour
  • Exploring how seller and buyer flows fit together in a working codebase

Frequently asked questions

Is Gumroad free to use?

The source code is published under the MIT licence, which the repository lists. The README does not cover pricing for the hosted service, so check gumroad.com for its current terms.

What do I need to run Gumroad locally?

You need Ruby and Node.js at the versions in the repo's .ruby-version and .node-version files, Docker, MySQL 8.4.x, and ImageMagick. The README also lists FFmpeg, PDFtk and wkhtmltopdf for certain features.

Can I use this to set up a self-hosted Gumroad store?

Not from this README. It describes a development setup rather than a deployment guide, so it does not explain how to run a production store.

Why does make local need sudo on Linux?

The README says that on Linux, or when Docker was installed through a package manager on a Mac, you may need superuser access to expose container ports, so it suggests sudo make local.

Why am I getting index_not_found_exception errors?

The README says you must reindex Elasticsearch after setup to populate the indices. Without that, those errors appear when you visit certain pages.

How does Gumroad compare to Sharetribe, Spree Commerce, Medusa or Saleor?

These are comparable open-source commerce projects. This README covers only Gumroad's own web app, so compare them on their own documentation, stack and deployment needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this repository if you know Ruby on Rails and want to read, run or contribute to a real e-commerce codebase. If you only want to sell products, use the hosted service at gumroad.com, and if you want a self-hosted store, look at projects such as Sharetribe, Spree Commerce, Medusa or Saleor.

Install options & downloads