Ruby API: a phone friendly browser for the Ruby standard library docs

The problem is search on a phone, not missing documentation

Ruby API is a fast, mobile friendly documentation browser for Ruby and the Ruby standard library, and it is live at rubyapi.org. The description in the repository says it makes it easy and fast to search or browse the Ruby language API docs.

The stated reason for existing is specific. The existing Ruby docs sites are hard to search and uncomfortable to read on a phone, which is where a lot of people look up docs, and the project's job is to fix that with instant search, pages small enough to load over a slow connection, and layouts that behave the same on a phone as on a laptop. It is free, supported by Ruby Central, and has no ads.

The goals are listed as a short set of intentions, and each one maps to a decision in the code. Readable on any size device, fast on any speed internet connection, relevant search results that surface useful APIs, search engine optimised pages for every API method, and free with no ads, ever.

That last pair of goals is why the technical choices below matter. A documentation browser that is fast on a slow connection cannot serve heavy pages, and a site that must index every method for search engines needs a real search index rather than a grep over static HTML. The design follows from the goals rather than the other way round, and for a reader deciding whether to use the site or self host it, that is the point to check first.

RDoc output becomes an OpenSearch index

The mechanism is two well known pieces of Ruby infrastructure joined together.

Documentation is imported directly from the official Ruby source via RDoc, and the imported content is indexed in OpenSearch. RDoc is the documentation generator that ships with Ruby, so the content is the same material the official docs are built from, and the import is a job that runs against a Ruby version rather than a hand maintained copy of the pages.

The search experience is inspired by Dash, which is the documentation browser that made offline searchable API documentation a habit for many developers, and Ruby API is the browser shaped version of that idea for Ruby with a web backend instead of a desktop index.

The repository is a Rails application, and the layout shows the two data stores it depends on. There is a db directory and a config directory for the PostgreSQL side, an app directory for the Rails code that renders the pages, and a lib directory where the import logic lives. The compose file at the root starts OpenSearch 3.5.0 with a single node discovery setting, the OpenSearch Dashboards image for the admin console, and PostgreSQL 17 on Alpine, each with a health check so that dependent services wait for a working database and a working search cluster.

Running the stack locally with three commands

Local development needs Ruby 4 and Docker, with PostgreSQL and OpenSearch running in containers. The setup is three commands.

docker compose up -d # start PostgreSQL and OpenSearch
bin/setup            # install gems, copy database.yml, prepare the database
bin/dev              # start the Rails server on port 3000

The middle step is the one that does the work. bin/setup installs the gems, copies database.yml and prepares the database, and the documentation says it is also what you run when you pull updates, since it refreshes the gems and applies new migrations.

The compose file binds the service ports to the loopback interface rather than to every interface, which is the safer default for a development machine.

services:
  search:
    image: opensearchproject/opensearch:3.5.0
    init: true
    ports:
      - "127.0.0.1:9600:9600"
      - "127.0.0.1:9200:9200"
    environment:
      - discovery.type=single-node
      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=RubyApi-Local-OpenSearch-2026!
    volumes:
      - search-data:/usr/share/opensearch/data

OpenSearch is then reachable at https://localhost:9200 and the Dashboards console at http://localhost:5601, and the documentation gives the local administrator credentials for both.

The fastest way to try the project at all is GitHub Codespaces, which boots a fully configured environment in one click, and the repository includes a .devcontainer directory for it. Docker is the only setup the project officially supports, and Podman tends to work if you already use it, with podman-compose in place of docker compose.

Importing one Ruby version or all of them

The import step is a Rails task, and it takes a version.

bin/rails import:ruby[4.0]
bin/rails import:ruby:all

The first form pulls the documentation for a single Ruby version, and the second pulls every currently supported version at once. The second form is the one that fills a search index the way the hosted site has it, and it is a long running job, so a self hosted instance that wants to mirror the full catalogue has to plan for it.

Two other developer commands complete the workflow. Tests run with bin/rails test, and the documentation is explicit that they hit a real database, so PostgreSQL and OpenSearch both have to be running. Linting uses RuboCop, with bin/rubocop to see violations and bin/rubocop -a to autocorrect what can be corrected automatically.

The split between local data and imported content is worth noting for a self hoster. The Rails application, the database and the search cluster are yours to run, while the documentation content comes from the official Ruby source at import time. Nothing about the site requires a Ruby gem index, which is why it covers the language and the standard library and not the ecosystem of published gems.

Production runs on Kamal, a slim Ruby image and donated infrastructure

The deployment story is a conventional Rails one, and the repository carries the artefacts.

The Dockerfile builds on a slim Ruby image, with the Ruby version taken as a build argument and a comment reminding you that it has to match the version in the .ruby-version file. The base stage installs curl, jemalloc, the PostgreSQL client and sqlite3, sets BUNDLE_DEPLOYMENT with the bundle path and without the development and test groups, and sets RAILS_ENV to production. A throw-away build stage compiles the gems with build-essential and the library headers, and bootsnap is used to precompile both the gemfile cache and the application and library code for faster boot times.

The deployment tool is Kamal, since a .kamal directory is at the top level, alongside a compose.yml, a Rakefile, a Gemfile and its lockfile, a .herb.yml configuration, a .rubocop.yml and a .devcontainer directory. There are also AGENTS.md and CLAUDE.md files, which suggests the project expects automated coding assistants to work on it.

The infrastructure behind the hosted site is donated rather than rented. Hosting is donated by Amazon Web Services and the CDN is donated by Fastly. The project itself is supported by Ruby Central, a non-profit that funds Ruby community infrastructure including RubyGems.org, RubyConf, RailsConf and Bundler, and the readme points at the sponsorship and membership options for that organisation.

Where Ruby API is the wrong tool

Four mismatches are worth naming.

The first is gem documentation. The importer pulls from the official Ruby source, so the catalogue is the language and the standard library. If the question you have is about a gem you installed, this site does not answer it, and no amount of configuration changes that.

The second is the operational weight. A deployment is a Rails application, PostgreSQL and OpenSearch, with a search index that has to be populated by a long running import task before the site is useful. That is a fair amount of infrastructure for reading documentation, and it is the reason a small team might be better served by a local copy of the RDoc output or by a desktop documentation browser than by running this stack.

The third is offline use. The design goal is to be fast on a slow connection, which is not the same as working with no connection. The index lives in OpenSearch on your server, and the pages are served by the application, so a self hosted instance with no network path to itself has no search.

The fourth is release discipline. The repository publishes no GitHub releases, and the last push was on 2026-10-01, so there is no versioned artefact to pin in the way there is for a packaged gem. You are tracking the main branch, and a deployment is only as stable as the commit you happened to build.

Licence, governance and what a community project implies

The licence is MIT, with the licence file named LICENSE.md at the root of the repository, so the code can be used, modified and redistributed in commercial and non commercial work provided the notice is kept. This is not legal advice, and a company with a licence review process should still run its own check.

The governance is worth understanding, because it explains several of the choices. Ruby API is a project of the Ruby community rather than of a company, and the site is supported by Ruby Central, the same non-profit that funds RubyGems.org, the conferences and Bundler. The hosting and the CDN are donated, which is how a site with no ads stays available.

The readme also states a code of conduct expectation for everyone interacting with the source code, the issue trackers and the chat rooms, and the repository carries the CODE_OF_CONDUCT.md file, a .github directory, an .editorconfig and a .rubocop.yml, all of which point to a project with normal community process rather than a personal project.

The practical takeaway for a self hoster is that the operational costs are the ones to plan for, not the licence. PostgreSQL, OpenSearch and a Rails app are yours to run and keep patched, the index needs rebuilding whenever you add a Ruby version, and the project itself publishes no releases, so your upgrade path is the main branch.

Editorial conclusion

Ruby API is the right tool for a Ruby developer who looks up standard library methods on a phone or over a slow connection, and for anyone who wants a self hosted, ad free copy of the Ruby documentation with proper search. It is the wrong tool for gem documentation, which it does not index, for a team that only needs a local copy of the RDoc HTML, and for a deployment that cannot run PostgreSQL and OpenSearch alongside a Rails application. Before adopting, run the import task for the single Ruby version you care about and check that the search results are the ones your team would have found, and confirm that the OpenSearch and PostgreSQL services are bound to localhost in your deployment the way the compose file binds them.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. rubyapi/rubyapi on GitHub