Circulate is an operating system for lending libraries. It is in the early stages of development. 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
- Volunteer shift scheduling
- Gift membership generation and redemption
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!)
- Many desired features may be able to be adapted from babywearing, Ruby For Good's lending app for babywearing accessories.
Circulate is a fairly basic 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 scheduling
- Sentry for error collection
- Skylight for app performance monitoring
Once you've completed the setup below, you can login to the app using [email protected] and 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.
If you're new to Ruby or Rails applications, a recommended way to get set up is to use the community setup guides for Discourse. Discourse is a popular forum software project that also uses Ruby on Rails. There are scripts provided for macOS, Ubuntu, and Windows. On those pages you'll see more than the one script- for the purposes of this project, you only need to run the first, initial script command that you see. You do not need to keep going with the steps/information on Discourse. Stop when you get to "Clone Discourse"- don't do that! Come back here ✨ Note You do want to pay attention to this install as it runs in your terminal- it may ask for your password once or twice throughout the process- keep an eye on it and be prepared to type your computer's password (in the terminal! NEVER share your password in a GitHub doc). Also note that the install takes some time to run completely- it is not a 5-minute process.
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:
$ bin/setupAll right, almost there! In the terminal, type and run:
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, and type localhost:3000. 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
[email protected]as the username andpasswordas 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.
Use the standard Rails test commands: rails test, rails test:system, etc.
Note, in order to get system tests to run, you will need chromedriver installed. See Requirements section above.
Circulate uses 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.
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
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
The Procfile is configured to run database migrations during the release stage of deployment.
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.
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:
- MyTurn
- Lend Engine
- Tool Librarian for those in the Portland, OR area
Folks interested in helping to build Circulate should get in touch, though! I'd love to have collaborators on the project.