From 0c9c8fc3eac0ae51f68d1297d6cfea10827d49e1 Mon Sep 17 00:00:00 2001
From: shuaiyafei <16618929+shuaiyafei@users.noreply.github.com>
Date: Tue, 29 Sep 2026 20:27:07 +0800
Subject: [PATCH] docs: document environment loading precedence

Explain how local, test, Docker Compose, and CI environments load values and which settings take precedence.
---
 ENVIRONMENT.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/ENVIRONMENT.md b/ENVIRONMENT.md
index fafa555..6071f17 100644
--- a/ENVIRONMENT.md
+++ b/ENVIRONMENT.md
@@ -5,6 +5,27 @@ the test suite) and fill these in.
 
 Admin requests are authenticated with a signed timestamp header. The timestamp **must be a Unix timestamp in milliseconds** (i.e. `Date.now()`). Timestamps in seconds are rejected with a `stale_signature` error; multiply by `1000` if you only have seconds.
 
+## Loading and precedence
+
+- `npm run dev` and `npm start` import `dotenv/config` before the application
+  modules load. This reads `.env` once at process startup. Values already
+  present in the shell or CI environment take precedence over values in the
+  file; dotenv does not overwrite existing environment variables.
+- `npm test` loads `.env.test` from `test/setup.ts` before importing the test
+  modules. The test database is separate because the suite resets its data.
+- `npm run db:push:test` explicitly runs Prisma with `.env.test` through
+  `dotenv-cli`.
+- GitHub Actions supplies `DATABASE_URL` directly for its temporary Postgres
+  service. It does not depend on a checked-in `.env` file.
+- Docker Compose loads `.env` for the backend container, then overrides
+  `DATABASE_URL` with the internal Postgres hostname. The host command
+  `npm run db:push` still uses the `localhost` URL from `.env`.
+
+Environment values are read at module-load time in several places, including
+the database adapter, indexer contract configuration, polling interval, and
+server port. Set the environment before starting the process; changing a
+variable after startup does not reconfigure those modules.
+
 | Variable                      | Required | Default                                | Notes                                                                                          |
 | ------------------------------ | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `DATABASE_URL`                 | Yes      | —                                        | Postgres connection string. Inside `docker compose`, the backend service overrides this to point at the `postgres` service, not `localhost`. |