human-essentials: inventory control for diaper banks and period supply banks

What the application is actually for

Human Essentials is described in the repository as an inventory management system for diaper, incontinence and period supply banks, and the README calls it inventory control for diaper banks and other essentials banks. The block quote under the title says the same thing more plainly.

The mission section explains who it serves. Essentials Banks maintain inventory, receive donations and other human essentials supplies such as diapers and period supplies, and issue distributions to community partner organisations. Like any non-profit they also need reports on that data and the day-to-day operational information to run on. The application aims to serve those needs and facilitate the general operations of the banks, and the README names the operational details it accounts for: using barcode readers, scale weighing and inventory audits.

Those three details say more about the design than any feature list would. Barcode readers mean the intake path is built around a scanner rather than a form. Scale weighing means the quantity received is measured, not counted. Inventory audits mean the system has to reconcile a physical count against a recorded balance, which is a different data problem from tracking what a warehouse believes it holds.

The audience is therefore a small non-profit with volunteer staff and a physical stockroom, not a distribution company. The README says there is no cost to essentials banks and that all of the source code, MIT licensed, is shared and built by volunteers as part of Ruby for Good.

The last push to the repository was on 2026-10-18 with the repository not archived, and the release tags are dated rather than numbered, with 2026.08.02, 2026.08.30 and 2026.09.20 in the recent list.

A hosted service first, source code second

The delivery model is worth being precise about, because it is unusual for a non-profit tool.

The README says Human Essentials is a free hosted service, with no cost to essentials banks, and that the source code is shared and built by volunteers. So the primary consumption path is signing up for the hosted instance, and running your own copy is the second path.

The application is also recognised as a digital public good by the Digital Public Goods Alliance, which the README links to, and it supports three Sustainable Development Goals: SDG 1, end poverty in all its forms everywhere, SDG 3, ensure healthy lives and promote well-being for all at all ages, and SDG 10, reduce inequality within and among countries.

For an organisation evaluating the software rather than the service, that distinction matters. The repository has a ngo.md with adoption information and an sbv.md with information about skills based volunteering, and the README points to both, alongside a link to the annual conference of the National Diaper Bank Network with which the team is in partnership.

The impact figures in the README are stated as the project's own, and they are the kind of number to treat as a claim rather than a measurement: over 200 registered banks across the United States at no cost to them, helping over 3 million children receive diapers, and over 400k period supply recipients receiving period supplies.

The licence is MIT with a LICENSE file at the repository root, and the language is Ruby with Rails, as the topics and the repository layout both indicate.

Local development starts with a pinned Ruby and a Postgres

The local development section is a numbered list, and the first two items are the environment.

You install Ruby, using the version specified in the .ruby-version file at the repository root, and the README points at the GoRails Install Ruby on Rails guide for Ubuntu, Windows and macOS setup, with the instruction to follow only the Installing Ruby step because the project setup differs. It also recommends using a Ruby version manager such as rbenv, asdf or rvm, and says to verify the installation by running ruby -v.

Then you install Postgres, following one of the DigitalOcean guides for macOS or Ubuntu, and you create a database.yml file in the config directory with your database configurations. The README says you can also copy the existing files called database.yml.example and .env.example and change the credentials.

The .env.example file shows what the environment needs to look like, and it opens with the database, worker and feature flag credentials:

PG_USERNAME=
PG_PASSWORD=
DELAYED_JOB_USERNAME='admin'
FLIPPER_USERNAME="admin"

After those come a reCAPTCHA site key and private key, and then a set of optional entries, marked as such, for fetching copies of the production database through Azure storage, for the canonical host of the deployment, for the HELO domain used in the SMTP conversation, and for the production and demo URLs.

The shape of that file is the architecture in miniature. A Rails app with Postgres, a background job queue, feature flags through Flipper, reCAPTCHA on the forms, and a set of deployment-specific values that are optional in development and mandatory in production.

What the repository layout says about the stack

The top-level entries describe a conventional Rails application with an unusually complete set of quality tooling, and the tooling is the interesting part for anyone considering a contribution.

Alongside the standard app, config, db, lib and spec directories there are a Guardfile, a Rakefile, a Procfile and a Procfile.dev for process management, a config.ru, a clock.rb, and a puma-dev.md document. The Cloud66 directory points at the platform the project has used for deployment, and there is a .devcontainer directory for a containerised development environment.

The linting and test configuration is extensive. There is a .rubocop.yml with a .rubocop_todo.yml beside it, a .erb_lint.yml for the ERB templates, a .reek.yml for code smell detection, a .rspec file, a .simplecov for coverage, a .browserslistrc, a .prettierignore for JavaScript formatting, a .annotaterb.yml for the ERB annotations tool, and a .all-contributorsrc. A GitBook configuration and a docs directory suggest the documentation is published as a book.

The spec directory sits next to a .cloud66 directory and a vendor directory, and the Rakefile and Gemfile are at the root, so the project uses Bundler with a checked-in Gemfile.lock.

Two of these deserve a note. The .rubocop_todo.yml is the file that records the existing violations the team has not fixed yet, which tells you the linting is applied but the codebase is not yet clean against its own rules. And the Guardfile means the team runs tests on file changes locally rather than only in CI, which is a sign of a project that expects a lot of contributions and wants them to be cheap to verify.

Features gated by environment variables, and the ones you can leave out

The .env.example file is the closest thing the repository has to a configuration reference, and reading it carefully tells you what the deployment needs and what it does not.

Four groups matter. The database group holds the Postgres username and password. The delayed job group holds a separate username and password pair for the background worker. The Flipper group holds credentials for the feature flag system. And the reCAPTCHA group holds a site key and a private key, which on a form that accepts public sign-ups is the anti-bot measure.

Then the optional group, and the comments are unusually informative. The Azure storage account name and access key are described as used to fetch copies of the production database, which is a support and debugging convenience rather than a runtime requirement. APP_HOST is the canonical host for the deployment, and the comment is careful about the scope: it only affects links generated outside a request, in mailers, jobs and rake tasks, because in-request links already follow whichever domain the visitor arrived on. SMTP_DOMAIN is the HELO domain used for the SMTP conversation, and the comment ties it to where mail is sent from and to SPF and DKIM, not to which domain the site is browsed on. PRODUCTION_URL and DEMO_URL cover the staging banner pointing at the live site and the demo credentials in email.

That last pair is worth noting for anyone deploying their own instance. The application assumes a production site and a demo deployment exist as separate things, and it generates links to both. A single self-hosted instance would need those values pointing somewhere sensible, and the comment tells you the failure mode is wrong links in emails rather than a crash.

The overall pattern is a Rails app that separates required credentials from optional ones cleanly enough that a volunteer can set up a development environment from two copied files, and the deployment configuration is the part that takes thought.

Where human-essentials is the wrong tool

The first wrong-tool case is a commercial distribution operation. The application is built for a community bank that receives donations in small volumes and hands out a few hundred diapers a week, with volunteers scanning boxes and weighing sacks. A warehouse that moves pallets, tracks lot numbers, bills partners or handles returns is a different data model, and nothing in the README suggests the application models any of that.

The second is an organisation that needs its data isolated. The README describes a hosted service with over 200 registered banks, which means a shared deployment, and the reporting described is aggregate and operational. If two unrelated organisations must not see each other's stock movements or their partners' data, the shared instance is not the answer and the reporting features in the application will not change that.

The third is a team that does not want to run a Rails application and a Postgres database. The hosted service exists precisely so that banks do not have to, and the README is explicit that there is no cost to essentials banks. Choosing to self-host when the free hosted option covers your needs adds a migration, a backup policy and a support burden for no benefit.

The fourth is a user who expects the software to be general purpose. The README's framing is narrow and specific, the project identifies itself by the SDGs it supports and the population it serves, and the repository is a volunteer effort with a stated partner organisation. Extending it into a general inventory product means taking on a scope the maintainers have not signed up for.

The fifth is a technical expectation. The licence is MIT and the source is available, but the repository's open issues and pull request badges are the visible measure of the project's activity, and the README's own contributors section attributes the work to a specific group. Anyone planning a fork should weigh that the feature set tracks the needs of diaper banks, and that the reporting and partner-distribution vocabulary is the domain model rather than an abstraction you can re-point.

Editorial conclusion

human-essentials fits a community bank with volunteer staff who need to receive donations, record distributions to partner organisations and produce reports without buying software, and who are willing to run a Rails app and a Postgres database themselves. It is the wrong choice for a commercial warehouse operation with barcode and workflow requirements the application does not model, and the wrong choice if you need multi-tenant isolation for unrelated organisations. Before adopting it, read the NGO adoption information in ngo.md, set the database credentials from the example environment file, and confirm that the hosted service covers the reporting your board needs before you plan on running your own instance.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. rubyforgood/human-essentials on GitHub