Installation - Gumroad

Overview

This guide covers everything you need to install before running Gumroad locally. Follow the instructions for your operating system carefully.

Windows users should use WSL (Windows Subsystem for Linux) to run Gumroad. Once you have WSL set up with Ubuntu, follow the Linux installation instructions below.

System Requirements

Supported Platforms

macOS 10.11 or later
Linux Ubuntu/Debian distributions
Windows via WSL (Windows Subsystem for Linux)

Minimum Specifications

8GB RAM (16GB recommended)
10GB free disk space
Modern multi-core processor

Core Dependencies

Ruby

Gumroad uses Ruby 3.4.3 as specified in the .ruby-version file.

macOS
Linux

Using rbenv (recommended):

brew install rbenv ruby-build
rbenv init
rbenv install 3.4.3
rbenv global 3.4.3

Or using rvm:

curl -sSL https://get.rvm.io | bash -s stable
rvm install 3.4.3
rvm use 3.4.3 --default

Using rbenv:

# Install dependencies
sudo apt-get update
sudo apt-get install -y git curl libssl-dev libreadline-dev zlib1g-dev \
  autoconf bison build-essential libyaml-dev libreadline-dev \
  libncurses5-dev libffi-dev libgdbm-dev

# Install rbenv
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer | bash

# Add to .bashrc or .zshrc
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Install Ruby
rbenv install 3.4.3
rbenv global 3.4.3

Verify installation:

ruby --version
# Should output: ruby 3.4.3

See the official Ruby installation guide for alternative installation methods.

Node.js

Gumroad requires Node.js 20.17.0 as specified in the .node-version file.

macOS
Linux

Using nvm (recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js
nvm install 20.17.0
nvm use 20.17.0
nvm alias default 20.17.0

Or using Homebrew:

brew install node@20
brew link node@20

Using nvm:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install Node.js
nvm install 20.17.0
nvm use 20.17.0
nvm alias default 20.17.0

Verify installation:

node --version
# Should output: v20.17.0

npm --version
# Should output: 10.8.2

Docker

Docker is used to run MySQL, Redis, Elasticsearch, and MongoDB services.

macOS
Linux

Download and install Docker Desktop:

Visit Docker Desktop for Mac
Download the installer for your chip (Intel or Apple Silicon)
Open the .dmg file and drag Docker to Applications
Launch Docker Desktop and complete setup

Verify installation:

docker --version
docker compose version

Install Docker Engine:

# Install using convenience script
sudo wget -qO- https://get.docker.com/ | sh

# Add your user to docker group
sudo usermod -aG docker $(whoami)

# Log out and back in for group changes to take effect

Install Docker Compose:

sudo apt-get install docker-compose-plugin

Verify installation:

docker --version
docker compose version

Database Dependencies

MySQL 8.0

A local MySQL installation is required for the mysql2 Ruby gem, but you won’t run it as a service.

macOS
Linux

# Install MySQL 8.0
brew install mysql@8.0
brew link --force mysql@8.0

# Ensure MySQL is NOT running as a service
brew services stop mysql@8.0

Do not start MySQL as a service. The app connects to MySQL running in Docker.

# Install MySQL client libraries
sudo apt-get install -y libmysqlclient-dev mysql-client

See the MySQL 8.0 installation guide for full server installation if needed.

Percona Toolkit

Required for database maintenance operations.

macOS
Linux

brew install percona-toolkit

# Add Percona repository
wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
sudo dpkg -i percona-release_latest.generic_all.deb
sudo apt-get update

# Install toolkit
sudo apt-get install percona-toolkit

See Percona Toolkit installation for details.

OpenSSL Configuration (macOS)

Configure Bundler to use Homebrew’s OpenSSL for the mysql2 gem:

brew install openssl
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"

Media Processing Libraries

ImageMagick

Used for image preview editing and manipulation.

macOS
Linux

brew install imagemagick

sudo apt-get install -y imagemagick

Verify installation:

convert --version

libvips

Used with ActiveStorage for modern image format processing.

macOS
Linux

brew install libvips

sudo apt-get install -y libvips-dev libvips-tools

Verify installation:

vips --version

FFmpeg

Required for video file metadata extraction.

macOS
Linux

brew install ffmpeg

sudo apt-get install -y ffmpeg

Verify installation:

ffmpeg -version
ffprobe -version

PDF Processing Tools

PDFtk

Used to stamp PDF files with the Gumroad logo and buyer emails.

macOS
Linux

Download from PDFtk Server
Open the .pkg file to install

PDFtk may be blocked by macOS Gatekeeper. If installation fails:

Go to System Settings > Privacy & Security
Click “Open Anyway” next to the pdftk message
Try installation again

sudo apt-get install -y pdftk

Verify installation:

pdftk --version

wkhtmltopdf

Required for generating PDF invoices from HTML.

macOS
Linux

Download version 0.12.6 from wkhtmltopdf downloads
Open the .pkg file and follow the installer

Similar to PDFtk, wkhtmltopdf may be blocked by Gatekeeper. Follow the same process to allow it in System Settings > Privacy & Security.

# Download and install version 0.12.6
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6-1.focal_amd64.deb
sudo apt-get install -f

Verify installation:

wkhtmltopdf --version

Additional Linux Dependencies

Linux users may need these additional packages:

sudo apt-get install -y \
  libxslt-dev \
  libxml2-dev \
  build-essential \
  git-core \
  curl

Ruby Gems Setup

Install Bundler

gem install bundler

Verify installation:

bundle --version

Install Project Dependencies

Once you’ve cloned the Gumroad repository:

cd gumroad
bundle install

This installs all gems from the Gemfile, including:

Key Ruby Gems

rails (7.1.6) - Web framework
sidekiq (7.2) - Background job processing
stripe (12.0) - Payment processing
devise (4.8) - Authentication
elasticsearch (7.11.2) - Search functionality
puma (6.4.2) - Application server
mysql2 - MySQL database adapter
redis (5.0) - Cache and job queue
rspec-rails (6.0) - Testing framework

Install dotenv

Required for some console commands:

gem install dotenv

Node.js Packages Setup

Enable Corepack

Ensure the correct npm version (10.8.2) is used:

corepack enable

Install Project Dependencies

cd gumroad
npm install

This installs all packages from package.json, including:

Key Node.js Packages

react (18.1.0) & react-dom - UI library
typescript (5.5.0) - Type safety
@inertiajs/react (2.3.13) - Modern monolith architecture
tailwindcss (4.1.14) - CSS framework
@stripe/react-stripe-js - Stripe integration
webpack (5.75.0) - Module bundler
eslint (9.6.0) - JavaScript linting
@tiptap/react - Rich text editor
recharts (2.15.2) - Charts and graphs

Verify Your Installation

Run this checklist to ensure everything is installed correctly:

Check Ruby Version

ruby --version
# Expected: ruby 3.4.3

Check Node.js Version

node --version
# Expected: v20.17.0

Check Docker

docker --version
docker compose version

Check Image Processing

convert --version  # ImageMagick
vips --version     # libvips
ffmpeg -version    # FFmpeg

Check PDF Tools

pdftk --version
wkhtmltopdf --version

Check Ruby Gems

bundle check
# Should show all gems satisfied

Check Node Packages

npm list --depth=0
# Should show all packages installed

Create a checklist script to verify your installation automatically. Save time on future setups!

Environment Configuration

Optional: Set Up Custom Credentials

The app can boot without custom credentials, but you may want to configure:

cp .env.example .env

Edit .env to add credentials for:

AWS S3

File storage and CDN

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION

Stripe

Payment processing

STRIPE_PUBLISHABLE_KEY
STRIPE_SECRET_KEY

Resend

Email delivery

RESEND_API_KEY

Other Services

BUGSNAG_API_KEY
GOOGLE_CLIENT_ID
FACEBOOK_APP_ID

These credentials are optional for local development. The app will work with mock services.

Development Tools (Optional)

Git Hooks

Enable pre-commit hooks for linting:

git config --local core.hooksPath .githooks

This will automatically run ESLint and Rubocop on commits.

Editor Setup

For the best development experience:

VS Code: Install Ruby, ESLint, and Tailwind CSS extensions
RubyMine: Built-in support for Rails and Ruby
Any editor: Configure to use local ESLint and Rubocop

Next Steps

With all dependencies installed, you’re ready to:

Quickstart Guide

Follow the step-by-step guide to get the app running

Development Guide

Learn about development workflows and best practices

Troubleshooting Installation Issues

Ruby Installation Fails

# macOS: Install Xcode Command Line Tools
sudo xcode-select --install

# Linux: Ensure build tools are installed
sudo apt-get install build-essential

MySQL Gem Won’t Install

# macOS
brew install openssl@1.1
bundle config build.mysql2 --with-opt-dir="$(brew --prefix openssl@1.1)"
bundle install

# Linux
sudo apt-get install libmysqlclient-dev

Docker Permission Denied (Linux)

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
groups

NPM Install Fails

# Clear cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

If you continue to experience issues, check the GitHub issues for similar problems and solutions.

Get Started

Core Features

Payment Processing

Development

Documentation Index

​Overview

​System Requirements

​Supported Platforms

​Minimum Specifications

​Core Dependencies

​Ruby

​Node.js

​Docker

​Database Dependencies

​MySQL 8.0

​Percona Toolkit

​OpenSSL Configuration (macOS)

​Media Processing Libraries

​ImageMagick

​libvips

​FFmpeg

​PDF Processing Tools

​PDFtk

​wkhtmltopdf

​Additional Linux Dependencies

​Ruby Gems Setup

​Install Bundler

​Install Project Dependencies

​Install dotenv

​Node.js Packages Setup

​Enable Corepack

​Install Project Dependencies

​Verify Your Installation

​Environment Configuration

​Optional: Set Up Custom Credentials

AWS S3

Stripe

Resend

Other Services

​Development Tools (Optional)

​Git Hooks

​Editor Setup

​Next Steps

Quickstart Guide

Development Guide

​Troubleshooting Installation Issues

​Ruby Installation Fails

​MySQL Gem Won’t Install

​Docker Permission Denied (Linux)

​NPM Install Fails

Build docs developers (and LLMs) love

Overview

System Requirements

Supported Platforms

Minimum Specifications

Core Dependencies

Ruby

Node.js

Docker

Database Dependencies

MySQL 8.0

Percona Toolkit

OpenSSL Configuration (macOS)

Media Processing Libraries

ImageMagick

libvips

FFmpeg

PDF Processing Tools

PDFtk

wkhtmltopdf

Additional Linux Dependencies

Ruby Gems Setup

Install Bundler

Install Project Dependencies

Install dotenv

Node.js Packages Setup

Enable Corepack

Install Project Dependencies

Verify Your Installation

Environment Configuration

Optional: Set Up Custom Credentials

Development Tools (Optional)

Git Hooks

Editor Setup

Next Steps

Troubleshooting Installation Issues

Ruby Installation Fails

MySQL Gem Won’t Install

Docker Permission Denied (Linux)

NPM Install Fails