Skip to main content

​
Overview

This quickstart guide will walk you through getting the Gumroad web application running on your local machine. By the end, you’ll have a fully functional local instance accessible at https://gumroad.dev.
This guide assumes you’re on macOS or Linux. Windows users should use WSL (Windows Subsystem for Linux) and follow these same instructions.

​
Prerequisites Checklist

Before you begin, ensure you have these installed:
  • Ruby 3.4.3 (see .ruby-version)
  • Node.js 20.17.0 (see .node-version)
  • Docker Desktop (macOS) or Docker Engine (Linux)
  • MySQL 8.0.x (local installation, not running as a service)
  • Image processing libraries (ImageMagick, libvips, FFmpeg)
Don’t have these installed? Check the installation guide for detailed setup instructions.

​
Step-by-Step Setup

1

Clone the Repository

First, clone the Gumroad repository to your local machine:
git clone https://github.com/antiwork/gumroad.git
cd gumroad
2

Install Ruby Dependencies

Install Bundler if you don’t have it, then install all Ruby gems:
gem install bundler
bundle install
Also install the dotenv gem which is required for some console commands:
gem install dotenv
On macOS with Homebrew’s OpenSSL, you may need to configure the mysql2 gem:
brew install openssl
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
3

Install Node.js Dependencies

Enable corepack for the correct npm version, then install dependencies:
corepack enable
npm install
This will install all packages defined in package.json, including:
  • React 18 and React DOM for the frontend
  • TypeScript 5.5 for type safety
  • Tailwind CSS 4 for styling
  • Webpack and build tools
4

Configure Environment (Optional)

The app can boot without custom credentials, but if you want to use services like S3, Stripe, or Resend:
cp .env.example .env
# Edit .env and fill in your credentials
You can skip this step for initial setup and add credentials later as needed.
5

Start Docker Services

Start the required services (MySQL, Redis, Elasticsearch, MongoDB) using Docker:
make local
The make local command will not terminate - it runs in the foreground. Open a new terminal tab for the next steps, or use LOCAL_DETACHED=true to run in background.
6

Set Up the Database

Create and seed the database with initial data:
bin/rails db:prepare
This command will:
  • Create the development and test databases
  • Run all migrations
  • Load seed data including test users
7

Index Elasticsearch

Populate Elasticsearch indices to enable search functionality:
bin/rails c
Then in the Rails console:
DevTools.delete_all_indices_and_reindex_all
exit
Skipping this step will cause index_not_found_exception errors when browsing the app.
8

Start the Application

Start the Rails server, JavaScript build system, and Sidekiq worker:
bin/dev
This single command starts:
  • Puma web server on port 3000
  • Webpack dev server for hot module reloading
  • Sidekiq worker for background jobs
9

Access the Application

Open your browser and navigate to:
https://gumroad.dev
Note the https:// protocol - the local development environment uses SSL.

​
First Login

You can log in with these default credentials:
Additional test users with different roles are available. See the source repository’s docs/users.md file for details.

​
Verify Your Setup

Confirm everything is working correctly:
1

Check the Dashboard

After logging in, you should see the seller dashboard with sample data
2

Test Background Jobs

Verify Sidekiq is processing jobs by checking the Sidekiq dashboard:
https://gumroad.dev/sidekiq
3

Test Search

Try searching for products to confirm Elasticsearch is working

​
Common Development Commands

Here are the most frequently used commands: 
bin/rails c

​
Troubleshooting

​
Docker Services Not Starting

If Docker services fail to start:
  1. Ensure Docker Desktop is running (macOS/Windows)
  2. Check port conflicts (3306 for MySQL, 6379 for Redis)
  3. Try docker compose down then restart

​
Database Connection Errors

If you see MySQL connection errors:
  • Verify MySQL is installed locally (but not running as a service)
  • Check that Docker MySQL container is running: docker ps
  • Ensure you have libmysqlclient-dev installed (Linux)

​
Asset Compilation Errors

If JavaScript assets fail to compile: 
corepack enable
rm -rf node_modules
npm install

​
Elasticsearch Errors

If you see index_not_found_exception: 
bin/rails c
DevTools.delete_all_indices_and_reindex_all

​
macOS Fork Errors

If you encounter fork() errors when running tests: 
export DISABLE_SPRING=1
bin/rspec spec/your_spec.rb
For more detailed troubleshooting, see the Common Issues section in the README.

​
Next Steps

Now that your environment is set up:

Development Guide

Learn about common development workflows and best practices

Contributing

Read the guidelines for submitting pull requests

Testing

Understand the testing strategy and how to write tests

Architecture

Deep dive into the application architecture

​
Need Help?

If you get stuck:

Build docs developers (and LLMs) love

Get started for freeTalk to us