Skip to Content

Improving open source without rewriting it: NOMAD

How I substantially extended Project NOMAD while keeping my additions separate, so I can follow its author.
November 16, 2026 by
Improving open source without rewriting it: NOMAD
Federico Solutions, Myrko Federico

Improving open source without rewriting it: NOMAD

Field: open source software, software engineering, maintenance

Period: September 2026

Client: internal project, my own companies (Lab 77, R&D)

In another article I described what my offline knowledge server does. This one tells how it is built: starting from an open source program, Project NOMAD, which I extended substantially without ever modifying its original copy. It was the technical decision that weighed most on the project, and it has consequences a business owner should know before signing off.

Context

In early September 2026, I was assembling my own stack: a console, a search index, an installer. Reading the code of Project NOMAD, published by Crosstalk Solutions under the Apache 2.0 licence, I found that it already did most of the job: it installs and updates, in containers, an offline encyclopedia, a learning platform, maps and an assistant that searches documents. The project has a large community behind it: more than 40,000 stars on GitHub today. On 10 September, I stopped my console, my installer and my index and started from his.

Problem

  • What mattered most for my use was missing: an interface in three languages, a search that spans every module, a cautious assistant, a library that organises itself.
  • The risk of drifting apart: changing the author's code everywhere turns each new release into a merge project. You end up maintaining, alone, software you did not write.
  • Fast-moving code: NOMAD publishes releases regularly, and some parts change often.
  • An author is not a supplier: nothing obliges him to accept my changes, or even to answer.

The approach

1. An untouched copy, with additions replayed on top

The main branch of my repository remains an exact mirror of NOMAD, never modified. My additions live on a separate branch, designed to be replayed on top of the original at each new release. The original licence is kept, and a notice will flag the modified files on the day I publish my additions, as Apache 2.0 requires. I had already added one or two features to DroneRoute, an open source mission planner for drones created by Ferran Basora. On NOMAD, the volume of work is of a different order altogether.

2. Add alongside rather than inside

NOMAD can host custom applications, and I made the most of it. Each of my building blocks is a separate application, declared in its console, not code mixed into his. That is how I added a public portal in three languages, with a search that queries every module at once, the assistant and voice; a service that files deposited books and documents into the library and indexes each file only once; an AI-assisted librarian that suggests and corrects themes, authors and titles; reading of scanned books; a library of more than 5,000 recipes from openly licensed sources; a research notebook modelled on NotebookLM, Open Notebook, connected only to the local AI; speech transcription and synthesis; a collaborative wiki and courses.

3. Change his code as little as possible

In NOMAD's code, I limited myself to five changes, all listed in a document that says why it exists and in which order to replay it. The first, a few lines, puts my portal at the top of the home page. Two others fix defects: thousands of useless warnings that buried the real failures, and a file whose indexing failed but which reported itself as healthy. The last two, written and tested but not yet in service when the project was paused, make indexing the encyclopedia optional and allow index computation to run on a separate server. For the last one, with the setting left empty, the software behaves exactly like the original. I touch the files the author changes most as little as possible.

4. Make the additions reliable

The author's tests would not start in my environment, so I wrote standalone tests for the last two changes, isolating their decision in a function that can be checked. On the backup side, three databases had no consistent copy; they are now exported consistently before each run. Archives backed up twice, AI models that can be downloaded again, and caches were also excluded: the backup went down from 105 to 85 GiB, and its duration from nearly three hours to twenty minutes. The restore procedure is written block by block, and states what has actually been rehearsed and what has not yet been. Finally, a database adjustment made outside the code is documented so it can be replayed after any reinstall.

5. Follow the author, and offer him my fixes

NOMAD's built-in update button would reinstall the original version over mine. So for me an update will follow a fixed cycle: fetch the original, replay my changes in the order of the list, rebuild, check. Two fixes are ready to be offered to the author, each on its own branch; one of them is still waiting for a real-world case to be fully proven. A third indexing defect, which comes from the original code rather than my installation, is still to be reported to him. Nothing has been submitted yet.

Result

In one week, from 10 to 17 September 2026, more than a hundred recorded changes, of which only a handful are in the author's code, grouped into five changes. Everything else lives alongside it. My project has been paused since mid-September, on NOMAD version 1.34.1; the author has since released versions 1.35.0 and 1.35.1. Catching up with them will be the real test of the method: the list is short, but it still has to be replayed.

What I take away from it

  • The cost lies in keeping up, not in adopting. Starting from NOMAD spared me rewriting what it already did. Each new release from the author, on the other hand, takes work: that is the line item to budget for.
  • Your additions belong to you, the original stays with its author. Apache 2.0 does not require you to publish your changes. If a contractor writes them, the contract must say who owns the rights.
  • The list of changes is your dependency inventory. Each line is a recurring cost. A short, documented list lets you carry on alone or change contractors.
  • Adding alongside costs less than adding inside. A separate application survives the author's releases; a change to his code has to be replayed every time.
  • You give up one-click updates. That is the price of an enriched version. Better to know it from the start.
  • Offering your fixes upstream cuts the bill. Each fix the author accepts comes off your list.

Going further

Torn between a custom tool and extending existing open source software? I help you choose the project, read its licence and keep your additions maintainable. See custom applications and automations, my map of open source software for SMEs, or book a 20-minute discovery call.

Sources

Tags: open source software, fork, Project NOMAD, Apache 2.0, software maintenance, software engineering

Linking Stripe to Odoo accounting without a paid connector
A small scheduled script replaced a paid aggregation service, then gave way to an open source OCA module.