Skip to content

quick start

Jump to bottom
RayBB edited this page Mar 1, 2026 · 11 revisions

order: 1

Quick Start

Estimated time: 45-90 minutes Difficulty: Beginner-friendly Prerequisites: Git and Docker installed (see below!)

This guide will take you from zero to making your first contribution to Open Library. It's designed for developers who want to jump in and start contributing quickly, without getting overwhelmed by details.

Tip

Need help? Join our weekly community calls (Tues @ 9am PT) or request a Slack invite.

📋 What You'll Learn

By end of this guide, you'll know how to:

  1. Set up your development environment with Docker
  2. Understand the basics of Git workflow
  3. Find and select a good first issue
  4. Make a small code change
  5. Test your changes locally
  6. Submit your first pull request

Let's get started!

🎬 Step 0: Get Oriented (15 minutes)

Before we dive into code, let's understand what Open Library is and how it works.

Watch the Quick Tour (10 min)

This 10-minute video will help you understand the service you'll be contributing to:

Quick Public Tour of Open Library

Review Community Guidelines (5 min)

Please review our Code of Conduct. We're committed to creating a safe, inclusive environment for all contributors.

🐋 Step 1: Set Up Your Environment (20-30 minutes)

Prerequisites

Before starting, ensure you have Docker, Git, and Pre-commit installed on your system.

Check if they're installed:

docker --version
git --version
pre-commit --version

If these commands succeed and show version numbers, you're all set! 🎉

Need to install?

Tip

Docker Desktop Settings: After installing Docker Desktop, we recommend allocating at least 4GB of RAM (8GB is better) in Docker Desktop → Settings → Resources to prevent memory issues during development.

1.1 Clone the Open Library Repository (5 min)

Now let's get the Open Library code onto your computer.

Step 1: Fork the repository

  1. Go to https://github.com/internetarchive/openlibrary
  2. Click the "Fork" button in the top-right corner
  3. This creates a copy of the repo under your GitHub account

Step 2: Clone your fork

# Replace YOUR_USERNAME with your GitHub username
git clone git@github.com:YOUR_USERNAME/openlibrary.git
cd openlibrary

Important

Use git@ (SSH) not https:// - otherwise git submodules won't work properly. If you cloned with https by mistake, fix it here.

Step 3: Verify submodules are loaded

# These commands populate the infogami submodule
git submodule init
git submodule sync
git submodule update

1.2 Build and Run Open Library (10-15 min)

Time to get Open Library running locally!

Build the project:

# From the openlibrary directory (where compose.yaml is)
docker compose build

Note

This can take 15-30 minutes on older hardware. If it times out or fails, just run the command again.

Start the application:

# Start Open Library (Ctrl-C to stop)
docker compose up

# Or start in background mode
docker compose up -d

Verify it's working:

  1. Wait until you see logs repeating every few seconds like:

    infobase_1 | 172.19.0.5:45716 - "HTTP/1.1 GET /openlibrary.org/log/2023-02-16:0" - 200 OK

  2. Open your browser to: http://localhost:8080

  3. You should see the Open Library homepage with "development version" in the banner

Congratulations! 🎉 You now have Open Library running locally.

🔧 Step 2: Understand the Git Workflow (15 minutes)

You don't need to be a Git expert to contribute. Here's what you need to know for your first PR.

The Basic Git Flow

When contributing, you'll follow this pattern:

1. Create a branch for your work
2. Make your changes
3. Test your changes locally
4. Commit your changes
5. Push your branch to your fork
6. Open a pull request

Create Your First Branch

Let's create a branch for your first contribution. We use a consistent branch naming convention that includes the issue number and a brief description:

# Ensure you're on the main branch
git switch master

# Pull latest changes from upstream
git pull upstream master

# Create a new branch with issue number and description
# Format: issue-number/type/brief-description
# Example: git switch -c 123/fix/broken-login-button
git switch -c 123/fix/broken-login-button

Tip

Branch naming convention: issue-number/type/brief-description

  • Types include: fix, feature, refactor, docs, test
  • This helps track your work and links branches to issues

Add the Upstream Repository

This lets you stay in sync with the official Open Library repository:

# Add the main repo as a remote called "upstream"
git remote add upstream https://github.com/internetarchive/openlibrary.git

# Verify it was added
git remote -v

You should see both origin (your fork) and upstream (the official repo).

🎯 Step 3: Find Your First Issue (15 minutes)

Now let's find a good issue to work on.

Good First Issues

We've curated issues specifically for new contributors:

Browse Good First Issues

When choosing an issue:

  • ✅ Pick one that's not assigned to anyone
  • ✅ Look for issues labeled with a programming language you know (Python, JavaScript, CSS, etc.)
  • ✅ Check that the issue has been active recently (no stale issues)
  • ❌ Don't pick issues someone else is actively working on

Request to Be Assigned

Found an issue you want to work on? Comment on it:

Hi! I'd like to work on this issue. I'm a new contributor and this looks like a good place to start.

My understanding of the issue:
[Briefly summarize the problem in your own words]

My proposed approach:
[Explain how you think you'll fix it]

I plan to modify:
[Mention any files or areas you think you'll touch]

Questions:
[Any clarifying questions you have]

Tip

This shows you've read and understood the issue. Maintainers are more likely to assign issues to contributors who demonstrate understanding.

✏️ Step 4: Make Your Changes (varies by issue)

This step depends on the issue you're working on. Here are some general tips:

Finding Relevant Files

Need to find where something is in the codebase? Use your code editor's search feature:

Search in your IDE:

  • VS Code: Press Shift + Command + F (Mac) or Ctrl + Shift + F (Windows/Linux) to search all files
  • WebStorm / PyCharm: Press Shift + Shift twice and type "Find in Files"
  • Other editors: Look for "Find in Files" or "Search in Project" in your editor's menu

What to search for:

  • Function or class names
  • Text that appears on the page (in templates)
  • Variable names
  • Error messages

Making Your Changes

  1. Edit files using your preferred code editor (VS Code, Vim, etc.)
  2. Test locally as you go
  3. Check your work - run the app and verify your changes work as expected

For frontend changes:

  • Refresh your browser at http://localhost:8080
  • Changes to HTML templates usually show immediately
  • CSS/JS changes may need a rebuild: docker compose run --rm home npm run build-assets

For backend changes:

  • The web server auto-reloads when Python files change
  • Check the console output for errors

🧪 Step 5: Test Your Changes (10 minutes)

Before submitting, make sure your changes work correctly.

Manual Testing

  1. Run Open Library locally: docker compose up (if not already running)
  2. Navigate to the page or feature you modified
  3. Test the specific behavior described in the issue
  4. Try to break it - what edge cases exist?

Run Automated Tests

We have automated tests to catch common issues:

# Run all tests
docker compose run --rm home make test

# Run tests for a specific file
docker compose run --rm home pytest openlibrary/plugins/somepath/tests/test_file.py

Note

If tests fail, you'll need to fix them before submitting your PR.

Run Pre-commit Checks

Pre-commit hooks automatically check for code quality issues:

# Run pre-commit on staged files
pre-commit run

# Run on specific files
pre-commit run --files path/to/file.py

📝 Step 6: Commit Your Changes (5 minutes)

Time to save your work!

Stage and Commit Your Changes

# See what files have changed
git status

# Add the files you've changed
git add path/to/changed_file.py
# Or add all changes:
git add .

# Commit with a descriptive message
git commit -m "Fix: add typehints for coverstore"

🚀 Step 7: Push and Create a Pull Request (10 minutes)

Push Your Branch to GitHub

# Push your branch to your fork
# Replace with your actual branch name from Step 2
git push origin 123/fix/broken-login-button

# If the branch already exists remotely:
git push origin -u 123/fix/broken-login-button

Create Your Pull Request

  1. Go to your fork on GitHub: https://github.com/YOUR_USERNAME/openlibrary
  2. You should see a banner asking to create a pull request
  3. Click "Compare & pull request"
  4. Fill out the PR template
  5. Click "Create pull request"

What Happens Next?

  1. Automated checks will run (tests, linting, etc.)
  2. Reviewers will look at your changes
  3. Feedback may be requested - don't worry, this is normal!
  4. Address feedback by making more commits to your branch
  5. Get merged! 🎉

Tip

  • Be responsive to reviewer feedback
  • Ask questions if you don't understand a request
  • It's okay if it takes multiple iterations to get merged

🎉 Congratulations

You've just made your first contribution to Open Library! Here's what to do next:

Keep Contributing

Learn More

Join the Community

🆘 Troubleshooting

Docker Won't Start

Problem: docker compose up fails with errors

Try these:

  1. Make sure you're in the openlibrary directory (where compose.yaml is)
  2. Stop and remove containers: docker compose down && docker compose rm -v
  3. Try again: docker compose up
  4. If that fails, try a full reset (see below)

Full Reset (nuclear option):

# Stop everything
docker compose down

# Rebuild without cache
docker compose build --pull --no-cache

# Remove old containers and images
docker container prune --filter label="com.docker.compose.project=openlibrary" --force
docker image prune --filter label="com.docker.compose.project=openlibrary" --force

# Remove volumes (wipes database)
docker volume rm openlibrary_ol-build openlibrary_ol-nodemodules openlibrary_ol-postgres openlibrary_ol-vendor openlibrary_solr-data openlibrary_solr-updater-data

# Start fresh
docker compose up

Out of Memory Error

Problem: OSError: [Errno 12] Cannot allocate memory

Solution: Increase Docker's allocated memory:

  • Docker Desktop → Settings → Resources → Advanced
  • Set memory to at least 4GB (8GB recommended)
  • Add swap space: 2GB minimum

Can't Access localhost:8080

Problem: Browser won't connect to http://localhost:8080

Try these:

  1. Verify containers are running: docker ps
  2. Check logs: docker compose logs web
  3. Restart containers: docker compose restart
  4. Wait 30-60 seconds and try again

Submodules Not Found

Problem: No module named 'infogami' error

Solution:

git submodule init
git submodule sync
git submodule update

Git Permission Denied

Problem: Permission denied (publickey) when cloning

Solution: Set up SSH keys:

  1. Generate SSH key
  2. Add SSH key to GitHub account
  3. Re-clone using SSH: git clone git@github.com:YOUR_USERNAME/openlibrary.git

📚 Further Reading

Want to learn more? Check out these resources:

Getting Started

Understanding the Codebase

Advanced Topics

💡 Tips for Success

  • Start small: Pick a simple issue for your first contribution
  • Ask for help: Don't hesitate to ask questions in Slack or on issues
  • Learn by doing: The best way to understand is to make changes and see what breaks
  • Read existing code: Look at similar changes in the codebase
  • Be patient: Code review may take a few days
  • Celebrate! Every contribution, no matter how small, helps improve Open Library

Ready to make a difference? Let's build a better library, together! 📚✨

Back to Developers Handbook

Please use the new docs site for the developers handbook.

Clone this wiki locally