I want to know what a project actually needs before I deploy it: which database, which version, which environment variables, which services are optional and which are required. The README tells me a lot of things, but I am never sure which of them are load-bearing.
Is there a better source than the README?
The answer, for most projects, is the compose file. We read them from project repositories constantly, and they are the most information-dense file in a repository that nobody reads as documentation. Here is what a compose file tells you that the README does not.
What it tells you
The stack the project actually supports. The database engine, its major version, the cache, the queue, the object storage. Not the stack the project could work with — the one its maintainers test against. When the compose file pins Postgres 16 and the README says "Postgres", the README is a summary and the compose file is the truth.
Which services are required and which are optional. A compose file with a profiles: section, or a service marked as optional in the comments, tells you which parts you can leave out. The README lists everything.
The ports it expects. The published ports, and the internal port the service really listens on. The second one is the useful one, because it is what a reverse proxy or a health check has to know.
The environment variables it needs. Every variable the service reads, with the value it defaults to. A variable with no default and no value in the file is a required variable, and that is the single most common cause of a container that exits immediately.
The health checks. A service with a healthcheck: block tells you what the project considers "ready", and the check is usually a curl against an endpoint the documentation mentions in passing.
What it tells you about the project
How old the supported stack is. A compose file that has not been updated in two years is telling you the maintainers are not testing against current versions, whether or not the README says "latest".
Whether the quick start is the supported path. A compose file that is complex — many services, profiles, secrets, a build section — is telling you the quick start is for people who already have the infrastructure.
Who the project is for. A compose file with three services is for one person. One with eleven, a message broker, and a distributed cache is for an operator, and the README will not say that.
The rule we use
Read the compose file before the README. It takes two minutes, it is machine-readable, it is written by the people who run the thing, and it is almost never written for a newcomer — which is exactly why it is honest.