Skip to content

docs: document environment loading precedence #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shuaiyafei wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document environment loading precedence #172

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions ENVIRONMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`. |
Expand Down
Loading