Technical Writings

This part of the Help Centre is where we write up things we have learned while building and running the systems behind this site. It is written for people who work with the same tools, and it is published in the hope that it saves someone else a difficult evening.

You do not need to share our beliefs to find these useful, and we would rather you took what is useful and left the rest. They are notes about machines, written by people whose work happens to be something else.

Why a community like ours writes about this at all

Religious life has always run on technology, and the tradition has always known it.

The printing press is the obvious example. Within a few generations of its arrival, scripture stopped being something most believers encountered only through an intermediary and became something they could hold. That was not a theological change. It was a change in machinery — and it reshaped religious life more thoroughly than most theological arguments ever have. People died over who was allowed to operate it and in what language.

Every tradition has its version of this, and ours is no exception. Islamic scholarship adopted paper early and enthusiastically, built libraries and cataloguing systems around it, and developed in the isnad — the chain of transmission — something a modern engineer would recognise immediately as a verification protocol: a claim is worth what its chain of custody is worth, and the chain is recorded so that anyone can check it. Scholars have argued about the reliability of an individual transmitter for centuries, with a rigour that would not embarrass a security review.

That is not a claim to have got there first. It is the observation that the problem is a shared one — how do you carry something faithfully across distance, across languages, and across generations, using whatever machinery you have? — and that people who take it seriously tend to arrive at recognisably similar answers, whatever they believe.

This is not reluctant engagement

It is worth being direct about this, because religious communities are often assumed to be uneasy about technology, and ours is not.

"We do not oppose technology; not only are we not opposed, rather it is wajib — religiously obligatory — that we use it." … "Let no one imagine that we are opposed to these technologies. Only a person devoid of reason opposes progress and technology."

— Grand Ayatollah Naser Makarem Shirazi (official office)

And it is not theoretical. The hawza's own institutions have spent decades digitising, indexing and making searchable a body of work that previously existed only in print — treated as scholarship rather than as administration, because it is. That work continues into territory many organisations are still hesitant about:

"I am pleased to see that the seminary has not lagged behind the caravan of science and technology. It has become a leader in applying artificial intelligence in the service of Islamic knowledge." … Quranic interpretation, he noted, is "among the most scientific fields of Islamic study, requiring linguistic, conceptual and historical precision — areas where AI can significantly enhance research accuracy and speed."

— Grand Ayatollah Makarem Shirazi, at the unveiling of a system built by the Computer Research Center for Islamic Sciences (Noor), Qom, November 2025 (report)

Why we write it down rather than only reading

There is a distinction we take seriously between learning from others and remaining permanently dependent on them:

"We must transform the approach of being consumers of science into an approach of producing science. How long must we sit as consumers of others' knowledge? I am not at all opposed to learning science from others … but being a student is one thing, and blind imitation is another."

— Imam Sayyed Ali Khamenei, to university professors and researchers, June 2018 (source)

Almost everything we know about running these systems, we learned from someone else's write-up — usually written by a stranger, usually for free, usually at the end of a long day. Reading those and never writing one is the consuming half without the producing half. It is a small thing to give back, but it is the thing we are actually able to give back.

So we work with technology in that spirit: with respect, with care about what it does to the thing it carries, and with the understanding that a tool used badly damages what it was meant to serve. Writing down what we learn is part of using it well.

What you will find here, and what you will not

You will find: accounts of specific problems we hit, what we tried, what actually worked, and — usually at greater length — the things that misled us on the way. They are written so that someone searching for the same error message finds the part they need without reading the rest.

You will not find: any description of our own infrastructure. No addresses, no machine names, no capacities, no diagrams of what sits behind what. Every example is written generically, and that is a deliberate rule rather than an oversight. The interesting part of what we learn is almost never specific to us anyway — it is usually a fact about a tool that anyone using it will meet.

And you will not find advice we have not tested. Where we have proved something on exactly one machine, the page says so and names the cases we did not try. A procedure that worked once is not the same as a procedure that works, and the difference is usually a condition nobody wrote down.

There is no schedule, on purpose

These pages appear when we have learned something worth another person's time. That might be twice in a month or not at all in a year.

We would rather this section were occasionally quiet than regularly padded. The test we apply is simple: did this come out of work we were doing anyway? If the answer is ever "we went looking for something to write about", the section has stopped being a by-product and started being the point — and the technology would have quietly become the centre, which is precisely what it is not.

The writings

• Who answered the check? Six tests that passed for the wrong reason — September 2026. Six checks passed in a single day, and each passed because something other than the thing being tested had answered it: a refusal that came from a content delivery network rather than from the application, a rule-checking search that matched the comment explaining the rule, a control that no machine we owned could have failed, a tool absent from the image it shipped in, two addresses that differed only by a prefix, and one field answering two questions. The remedy in every case was the same and takes a minute — break the check on purpose and watch it fail.

• One sign-in, many tools: letting our tools trust each other without sharing a secret — September 2026. How the tool that already knows who everybody is became the place the others ask, with a sixty-second signed note that says who somebody is and nothing about what they may do. Five decisions that matter more than the code — a return address that is a lookup and never a parameter, an algorithm that is pinned rather than read, a file of test vectors that made two halves built separately meet without surprise — and what "single sign-on" here deliberately is not.

• Every check was green: five faults nobody could see — September 2026. Five separate faults in one small mail system over two days, and every check that existed passed throughout. Each was a working instrument, correctly reporting a true fact about something next to the problem — including a health check watching the wrong process, and four DNS probes that were all right and all pointed one layer away from the fault.

• The certificate authority that merely answers — August 2026. An internal CA can look finished a week in, and almost everything that will later go wrong is already wrong at that point. Nine things that answer correctly and accomplish nothing — including a revocation command that does not revoke, and a certificate lifetime nobody chose.

• The thing you didn't change: why every check needs a control — August 2026. A machine failed the minute we changed it, and the obvious conclusion was sitting right there and was wrong. What separated the change from the coincidence was a machine we had deliberately not touched — plus three occasions in the same day where we had no such comparison and paid for it.

• The server was fine: nine wrong readings, and the accidents that caught them — August 2026. Rebuilding one server produced nine instruments reporting faults that did not exist, and every one of them failed toward alarm. What caught them was never looking harder — it was a second source disagreeing, and three of those were accidents nobody had designed.

• Proving a backup restores, and six tools that told us the wrong thing — August 2026. We had backups of every machine and had never restored one. So we erased a server and put it back. It worked; almost every instrument we checked along the way did not.