RMAN — Remote Man Pages

Inspiration

You're debugging inside a container at 2 AM. Something breaks. You type man tar — nothing. Minimal images strip documentation to save space. So you alt-tab to a browser, find a man page online… and it's for the wrong version. Or worse, it's the upstream default and your distro ships a patched variant with different flags. We've been burned by this enough times to do something about it.

What it does

RMAN is a very simple yet powerful API that allows you to query documentation for a particular project, allowing you to specify the exact version and flavor you actually use. Furthermore, it allows you to see the difference between two versions of the same program, or even compare them across different systems.

How we built it

Go 1.22, zero external dependencies. The entire backend — HTTP server, diff engine, tar extraction, filesystem store — uses only the standard library.

Core backend component of the RMAN project is the collector-aggregator framework we developed. Aggregator is responsible for bringing up containers and destroying them once the scraping is done. Received data is transformed and persisted in a filesystem database.

Collectors live inside containers, run the post-install jobs to download the documentation and send it up to the aggregator.

API layer reads the data from the previously seeded database and delivers it to the client. It also offers a diff-style queries for comparing programs across upgrades and different releases.

Backend serves the UI, allowing the clients to search and view through their browser.

Client is easily operated through the CLI, using tools present on every system (even minimal ones!). As an alternative, we offer a convenience wrapper script that can do OS and package detection, reducing the effort.

Challenges we ran into

Managing containers is hard. We had to take into account how different systems operate and craft plugins for each one of them. Each required a tailored installation strategy. Adding new ones is a process we can improve greatly!

Keeping the data in a organized fashion was a big topic of dispute! We settled on using a directory hierarchy which allowed us have an alternate style of deployments where everything is embedded in a single file (the binary and the database!). This simplifies the deployment of the RMAN tool, which comes in handy if you choose to host your own instance of it.

Accomplishments that we're proud of

We completed what we set out to do - created a simple to use tool solving a real-world problem many developers and system admins face today.

Creating the diff views was an unexpected feature that we thought of halfway through the project, but were keen on delivering despite the deadline. Seeing rman diff --from alpine:3.23 --to ubuntu:24.04 ls light up with colorized output was one of the best moments of the weekend.

What we learned

Containers are a moving target — every distro has its own quirks, package managers, and opinions about what belongs in a minimal image. We gained a much deeper understanding of how Linux distributions package and deliver documentation.

This was a first-time experience with go for most of the members of the team. It was challenging but enjoyable and we put a new tool in our toolbelts that we see using for many future projects.

What's next for RMAN — Remote Man Pages

Supporting new flavors is a bit of a manual process and something we look forward to improving.

Right now, we limited ourselves to just bringing up containers - therefore limiting what we provide to Linux only. However, other UNIX-like systems exist and we'd like to be able to fetch man pages for them as well! This requires us to bring up virtual machines instead and we believe we got the right bits and the architecture for it, but definitely a beast in and of itself that we didn't get around to tackling this time around.