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
- 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.
- 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
chromedriverare 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
password to see the admin interface.
See DOCKER.md 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 https://github.com/rubyforgood/circulate.git
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:
CODE_OF_CONDUCT.md bin package.json Gemfile config postcss.config.js Gemfile.lock config.ru public LICENSE.md db script Procfile exports storage README.md 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:
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,
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:
- Sign in to the admin interface using
firstname.lastname@example.org the username and
passwordas 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!)
- 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:
127.0.0.1 chicago.circulate.local 127.0.0.1 denver.circulate.local
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
# Database credentials PGUSER=your-postgres-username PGPASSWORD=your-postgres-password PGHOST=localhost
.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.
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
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
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:
- Ruby on Rails web framework Guides, API
- FactoryBot test data generator Getting Started guide
- Stimulus JS framework Docs
- Spectre CSS framework Docs
- Feather iconset Website
- MJML responsive email framework Docs
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/reset are run. They are:
- 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 └─ as BUCKETEER heroku-postgresql (postgresql-horizontal-xxxxx) hobby-dev free created └─ as DATABASE sendgrid (sendgrid-tetrahedral-xxxxx) starter free created └─ as SENDGRID logdna (logdna-symmetrical-xxxxx) zepto $5/month created └─ as LOGDNA scheduler (scheduler-round-xxxxx) standard free created └─ as SCHEDULER
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:
1. https://github.com/mojodna/heroku-buildpack-jemalloc.git 2. heroku/metrics 3. https://github.com/heroku/heroku-buildpack-activestorage-preview 4. heroku/ruby
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.