Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


An update on the Circulate project

TLDR: The Circulate team (Jim and Richard) will be putting Circulate on hiatus over the coming months.

Thank you to everyone who has been a part of this project over the last few years. This software has enabled The Chicago Tool Library to grow from just an idea into a thriving resource for the people of Chicago. We have successfully built a lending platform that provided features available nowhere else, and did it as a community of people who did good. We’ve had an incredible amount of support from people all over the world on the project, and I can’t thank each person enough for being a part of the project.

For most of 2022, we have struggled to provide a good experience to volunteers as well as deal with production issues in a timely manner. This has been due to the limited time of many of the core contributors to the project, especially Jim.

The only current tenant of the application, Chicago Tool Library, has made the decision to move to a SaaS solution to manage its lending early next year. There are a few reasons for this, including CTL needing some features Circulate hasn’t built yet as well as guarantees around customer support for when things go wrong. Jim is currently on the board of CTL and supports this decision.

In parallel, we’ve been considering how much time we can continue to contribute to the project going forward, and we’ve made the decision to spin down our involvement with the project.

We anticipate that development on Circulate will stop indefinitely, but the codebase will live on in Github and as it is open-source, it’s possible that it will be revived in the future, either through Ruby For Good or as a fork. Regardless, please know that your efforts on this project have been valuable and valued, helping many Chicago Tool Library members learn skills, build self-sufficiency, save money, reduce waste, and live more enjoyable and productive lives. We consider the project to be a success.

If you are looking to write some more Ruby code to help people, Ruby for Good has many other projects to contribute to. They’d be glad to have you!

Thanks for your time, your contributions, and reading this message. Cheers!

Jim Benton and Richard Kim

CI status

Welcome contributors!

We are very happy to have you! Circulate and Ruby for Good are committed to welcoming new contributors of all skill levels. We have plenty of tiny, small, and medium issues.

We highly recommend that you join us in the Ruby For Good Slack in the #circulate channel to ask questions, coordinate on work, hear about office hours (on hold for the moment, but occasionally on Tuesdays at 7pm CT), stakeholder news, and upcoming new issues.

Issues on the project board in the Ready to be worked on column are fair game. To claim an issue, comment on it with something like "I am working on this issue." Feel free to assign to yourself and move the Issue to the "In Progress" column if you have Project permissions.

Pull requests which are not for an issue but which improve the codebase by adding a test or improving the code are also welcome! Feel free to make GitHub issues when you notice issues. A maintainer will be keeping an eye on issues and PRs every day or three.

See also our contributing guide 💖


Circulate is an operating system for lending libraries. It currently provides the following functionality:

  • Member signup, including optional payment via Square
  • Inventory management, including item photos and configurable borrowing rules
  • Item loaning to members, including fine calculation
  • Item holds and waitlists
  • Renewal requests and approvals
  • Member account view and profile management
  • Appointment scheduling for item pick-up and drop-off
  • Volunteer shift scheduling
  • Gift membership generation and redemption
  • Various internal reporting and metrics
  • Limited support for multi-tenancy (see Project Board for current status)

There is content and information hard-coded in many of the views that is specific to The Chicago Tool Library, for which the software is being initially developed. Over time, the plan is for these specifics to make their way into configuration or user-editable content so that the software is easily used by other lending libraries.

Project Considerations

  • The Chicago Tool Library serves a diverse group of people in Chicago, with varying levels of technological sophistication, abilities, and understandings of English. The app should strive to be accessible to as many people as possible, including easy-to-understand UX; accessibility to different levels of vision (blind, low vision, color-blind); and straightforward, simple English.
  • Look-and-feel for Chicago Tool Library overall is generally fun, warm, bright, accessible, approachable, humble. A neighborhood old-timey hardware store. The Chicago Tool Library version of the app doesn't need to have as specific of a look-and-feel, but it shouldn't clash with this aesthetic. See the SquareSpace Chicago Tool Library site for more of a sense of this.
  • circulate may be used by other tool libraries or other lending organizations in the future, so should be built with an eye towards multi-tenancy. (Multi-lingual support may also be a goal someday!)


Circulate is a fairly standard Rails application. The main application requires a recent version of Ruby, a PostgreSQL database, and a modern version of Node and Yarn to build assets.

  • A version of chromium (Google Chrome is fine) and a compatible chromedriver are required to run application tests. This will be downloaded automatically for you when running system tests.
  • Imagemagick needs to be installed for gift memberships and item thumbnails to be generated.


The following third party services are used:

  • Sendgrid for sending email
  • Amazon S3 for image storage
  • Square for payment processing
  • Gmail and Google Calendar for volunteer and appointment shift scheduling
  • Sentry for error collection
  • Skylight for app performance monitoring
  • Imagekit for image resizing and manipulation


Once you've completed the setup below, you can login to the app using and password to see the admin interface.

See for instructions on setting up your environment using Docker. For non-Docker installations, follow the instructions below.

Setting up Circulate on your machine

If you're new to Ruby or Rails applications, a recommended way to get set up is to use the GoRails setup guide. On that page you can select your operating system and the versions of Ruby and Rails you want to setup. It's worth going through the entire tutorial if you haven't worked on a Ruby on Rails application on your computer already as it is easier to sort through possible issues before getting into a large project like Circulate. It will take about 30 minutes to complete this tutorial.

Time to get the Circulate repo! In your terminal, first make sure you're where you want to put the repo by typing pwd. If you want the Circulate repo to be in a different spot, type cd and change to the directory you want to put the Circulate repo in.

Next, put the full text below and press enter:

git clone

That will clone the Circulate repo to your machine, so you have a nice copy to work with locally! (Looking ahead, as you work you'll be pushing UP any changes you make from there to the Circulate repo on GitHub as a pull request.)

In your terminal, type cd circulate to change the directory you are in to your freshly-cloned, locally-hosted directory, Circulate.

In your terminal, type ls to take a look at what you'll be working with in this repo!

It should look like this:	bin			package.json
Gemfile			config			postcss.config.js
Gemfile.lock		public		db			script
Procfile		exports			storage		gems			test
Rakefile		lefthook.yml		tmp
app			lib			vendor
babel.config.js		log			yarn.lock

Close your Terminal window and open a new one so your changes take effect.

Okay, at this point you've got a Ruby on Rails development environment set up and cloned the Circulate repo! Now you'll need to run the following commands one at a time in your terminal:

$ bin/setup

This command will run install Ruby and JavaScript dependencies, create a local database, fill that database with a development dataset. If you see errors when it runs, you can look at what steps the script runs and work through them one at a time to figure out what is going wrong.

All right, almost there! In the terminal, type and run:

$ bin/rails test

Look for the word "Finished". That output should look similar to this:

Finished in 4.167485s, 41.0319 runs/s, 134.8535 assertions/s.

For working on this app, it is great to have several terminal windows open. Run bin/rails server in one terminal, bin/webpack-dev-server in another, and have a third terminal open for commands. The command in the second terminal kicks off a new webpack build when files change, which speeds up page load during local development considerably if you're making changes to JavaScript or SCSS.

Open an internet browser, type localhost:3000, and hit enter. You should see the Circulate app in your browser!

After you have the application running, here are some places to explore:

  1. Sign in to the admin interface using as the username and password as the password. (Please note, this is very rare, and only for the purposes of building at this moment. Please do not share your password on GitHub files!)
  2. Complete the new member signup flow.


The default tenant for this application is the Chicago Tool Library, but the application permits multiple tenants, identified by the URL used to access the application. In the local development environment, the following tenants are available:


Users are not currently shared between libraries; check db/seeds.rb for the full set of users as whom you can login to each of these libraries.

In order to access libraries other than the first one on your local machine, you need to edit your hosts file. This file is located at /etc/hosts on macOS and Linux, and C:\Windows\System32\drivers\etc on Windows or under WSL (Windows Subsystem for Linux). Add the following lines to the file: chicago.circulate.local denver.circulate.local

You can now access these libraries at http://chicago.circulate.local:3000 and http://denver.circulate.local:3000.

You will need to add additional lines to your hosts file if you need to work with additional libraries locally.

Configuring your database

By default the application will attempt to connect to a local PostgreSQL database accessible via a local domain socket. IF you need to specify other credentials on your machine, add any required values to the file .env.local:

# Database credentials

If .env.local doesn't exist in your project directory yet, you will need to create it.

Resetting the application

During development, you can reset the database to the initial state by running bin/reset. This will delete any changes you have made to the database!

This can be useful if you need to run through a certain scenario multiple times manually, or when switching branches to get back into a known good state.

Running tests

Use the standard Rails test commands:

$ rails test # to run model, controller, and integration tests
$ rails test:system # to run system tests

Note, in order to get system tests to run, you will need chromedriver installed. See Requirements section above.

Code formatting and linting

We are using Standard and ERB Lint to keep the project's code consistently formatted. The format of code is checked on PRs as a part of our GitHub Actions workflow.

To check the format of the project's code, use the following commands:

$ bundle exec standardrb --fix                   # Check all .rb files
$ bundle exec erblint --lint-all --autocorrect   # Check all .erb files

If you run into issues with these tools, please let us know and we'll be happy to help you out.

Setup pre-commit checks

You may choose to leverage Lefthook to run a few linters before creating commits, including Standard. Follow these instructions to configure your local git repository to run pre-commit checks.

Note that ERB files aren't checked as a part of precommit as it is just too slow.


Circulate leans heavily on a handful of open source frameworks and libraries, the documentation for which will be useful to developers:

Who to log in as

During development, you will probably want to log into the app as various users (e.g. an admin or a member). seeds.rb creates a set of user accounts when bin/setup or bin/reset are run. They are:

  • Admin
  • Verified member
  • New member
  • Member for 18 months
  • Expired Member
  • Membership expiring in one week

These users are associated with the first seed library, Chicago Tool Library. A similar set of users can be used to log in to the second seed library, Denver Tool Library, by appending .denver to the username portion of the email address (for example,

All of the seed user passwords are the word "password".


Circulate is currently running on Heroku in production, but it should run fairly well anywhere Rails applications can be run.

The following addons are expected to be enabled:

$ heroku addons
Add-on                                           Plan       Price     State
───────────────────────────────────────────────  ─────────  ────────  ───────
bucketeer (bucketeer-defined-xxxxx)              hobbyist   $5/month  created

heroku-postgresql (postgresql-horizontal-xxxxx)  hobby-dev  free      created

sendgrid (sendgrid-tetrahedral-xxxxx)            starter    free      created

logdna (logdna-symmetrical-xxxxx)                zepto      $5/month  created
 └─ as LOGDNA

scheduler (scheduler-round-xxxxx)                standard   free      created

Using a different way of configuring the file storage or email services should require trivial code changes.


The following buildpacks are currently used in production:

2. heroku/metrics
4. heroku/ruby

Release Command

The Procfile is configured to run database migrations during the release stage of deployment.

Daily Summary Emails

rails send_daily_loan_summaries is set to run every evening using Heroku Scheduler. Set this to a time after any open hours to ensure that all of the day's activity has taken place.

Here is the full list of scheduled tasks:

rails sync:calendars Every 10 minutes
rails email:send_return_reminders Daily at 1:00 PM UTC	
rails email:send_daily_loan_summaries Daily at 3:00 AM UTC	
rails email:send_staff_daily_renewal_requests Daily at 12:00 AM UTC  	
rails holds:start_waiting_holds Every 10 minutes 	
rails email:send_overdue_notices Daily at 3:00 AM UTC 	
rails email:send_membership_renewal_reminders Daily at 12:00 AM UTC


It's a bit early for non-developers to adopt Circulate. There are some existing systems worth considering for anyone looking to get something setup right now:

Folks interested in helping to build Circulate should get in touch, though! We'd love to have more contributors to the project.