Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions docs/docs/guides/geocoders.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,12 @@ running service; with no service, it falls back to Komoot's public instance.
Nominatim bundles its own PostgreSQL and imports an OpenStreetMap extract on
first start. There is no separate CLI build command.

That database has its own password, `NOMINATIM_DB_PASSWORD`. Set it in
`infra/docker/.env` before the first render; Nominatim does not render without
it. Generate it with `openssl rand -hex 32` and keep it different from
`POSTGRES_PASSWORD`. The image applies it when it first imports its database,
so changing it later takes effect only with a new import.

Nominatim _consumes_ an `osm-pbf`, so download the
extract and link it into place before starting:

Expand Down
4 changes: 3 additions & 1 deletion docs/docs/guides/supporting-infrastructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,9 @@ an image or rely on emulation without reviewing volume compatibility.
`POSTGRES_PASSWORD` is the PostgreSQL superuser's password. Only PostGIS
administration and the CLI's backups and restores use it; `app-api` and
`data-manager` connect as their own roles, whose passwords the render generates
(see [Database roles](../install/configuration.md#database-roles)).
(see [Database roles](../install/configuration.md#database-roles)). No other
service receives it: Nominatim's bundled database has its own
`NOMINATIM_DB_PASSWORD` (see [Nominatim](geocoders.md#nominatim)).

Set a unique `POSTGRES_PASSWORD` in `infra/docker/.env` before the first render.
Generate one with `openssl rand -hex 32`; production rejects known placeholders,
Expand Down
1 change: 1 addition & 0 deletions docs/docs/install/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -499,6 +499,7 @@ workload; a manifest default is not a hardware sizing guarantee.
| `POSTGIS_MAX_WAL_SIZE` | Write-ahead log PostgreSQL keeps between checkpoints. A checkpoint writes every changed page out again, and the first change to a page after it logs the whole page, so a busy database with too little WAL checkpoints every minute or faster and writes many times its changes to disk. Costs up to this much disk under `pg_wal`. | Default `4GB` |
| `POSTGIS_CHECKPOINT_TIMEOUT` | Time between PostgreSQL's timed checkpoints (`5min` to `1d`). A page changed many times between two checkpoints is written to disk once, and logged whole only after the first change, so a database that rewrites the same rows all the time (live readings) writes far less with a longer interval. After a crash, recovery replays the WAL written since the last checkpoint, which takes longer the longer the interval. Raise `POSTGIS_MAX_WAL_SIZE` with it, or checkpoints start early when the WAL reaches that size. | Default `15min` |
| `MARTIN_DB_PASSWORD` | Password of `openmapx_tiles`, the database role the Martin tile server logs in as. The role can call the tile functions in the `tiles` schema and read no table. PostGIS applies the password on every start; without it the role cannot log in. Generate with `openssl rand -hex 32`. | Required when Martin is enabled |
| `NOMINATIM_DB_PASSWORD` | Password of the database bundled in the Nominatim container; Nominatim never receives `POSTGRES_PASSWORD`. It must differ from `POSTGRES_PASSWORD` and be at least 24 characters. The image applies it when it first imports its database, so an existing import keeps its previous password until Nominatim is imported again. Generate with `openssl rand -hex 32`. | Required when Nominatim is enabled |
| `NOMINATIM_THREADS` | Import/query thread count for the self-hosted Nominatim geocoder. | Default `8` |
| `NOMINATIM_IMPORT_WIKIPEDIA` | Import Wikipedia importance scores during the Nominatim build. | Default `true` |
| `NOMINATIM_IMPORT_GB_POSTCODES` | Import GB postcodes. | Default `false` |
Expand Down
6 changes: 6 additions & 0 deletions infra/docker/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,12 @@ PHOTON_REGION=planet
# MARTIN_DB_PASSWORD=

# Nominatim (self-hosted geocoder)
# Password of the database bundled in the Nominatim container. Required when
# Nominatim is enabled; it is not, and must not equal, POSTGRES_PASSWORD. The
# image applies it when it first imports its database: an existing import
# keeps its previous password until Nominatim is imported again.
# Generate with: openssl rand -hex 32
# NOMINATIM_DB_PASSWORD=
NOMINATIM_THREADS=8
NOMINATIM_IMPORT_WIKIPEDIA=true
NOMINATIM_IMPORT_GB_POSTCODES=false
Expand Down
3 changes: 2 additions & 1 deletion infra/docker/secrets/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,8 @@ the roles from them on every start, before it reports healthy; `app-api` and
`data-manager` each mount only their own file and receive its path as
`DATABASE_PASSWORD_FILE`. The PostgreSQL superuser keeps `POSTGRES_PASSWORD`
from `.env` and is used only by PostGIS administration and the CLI's backups
and restores.
and restores. Nominatim's bundled database has its own `NOMINATIM_DB_PASSWORD`
in `.env`.

To change a password, stop `app-api` and `data-manager`, delete the file, run
`pnpm openmapx compose render`, then restart `postgis` followed by `app-api`
Expand Down
30 changes: 30 additions & 0 deletions packages/cli/src/lib/deployment-secret-policy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -162,4 +162,34 @@ describe("assertCliDeploymentSecrets", () => {
expect((error as Error).message).not.toContain(rejected);
}
});

it("leaves the geocoder's password to deployments that set it", () => {
expect(() =>
assertCliDeploymentSecrets({
...env,
NOMINATIM_DB_PASSWORD: "n".repeat(POSTGRES_DEPLOYMENT_SECRET_MIN_LENGTH),
}),
).not.toThrow();
});

it("rejects a weak geocoder password by name without revealing it", () => {
expect.assertions(2);
const rejected = "short-geocoder-fixture";
try {
assertCliDeploymentSecrets({ ...env, NOMINATIM_DB_PASSWORD: rejected });
} catch (error) {
expect((error as Error).message).toMatch(/NOMINATIM_DB_PASSWORD.*too-short/);
expect((error as Error).message).not.toContain(rejected);
}
});

it("rejects a geocoder password that repeats the superuser's", () => {
expect.assertions(2);
try {
assertCliDeploymentSecrets({ ...env, NOMINATIM_DB_PASSWORD: env.POSTGRES_PASSWORD });
} catch (error) {
expect((error as Error).message).toMatch(/NOMINATIM_DB_PASSWORD.*matches-superuser-password/);
expect((error as Error).message).not.toContain(env.POSTGRES_PASSWORD);
}
});
});
15 changes: 15 additions & 0 deletions packages/cli/src/lib/deployment-secret-policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,19 @@ export function assertCliDeploymentSecrets(env: NodeJS.ProcessEnv = process.env)
if (issue)
throw new DeploymentSecretPolicyError(issue, { credentialName: "MARTIN_DB_PASSWORD" });
}
// Only Nominatim needs it, and its manifest refuses to render without it.
// The geocoder runs a third-party image, so it must never hold the
// superuser's password, not even as a copy.
if (env.NOMINATIM_DB_PASSWORD) {
const issue =
env.NOMINATIM_DB_PASSWORD === env.POSTGRES_PASSWORD
? "matches-superuser-password"
: deploymentSecretIssue(env.NOMINATIM_DB_PASSWORD, {
username: "nominatim",
minLength: POSTGRES_DEPLOYMENT_SECRET_MIN_LENGTH,
urlEncoded: false,
});
if (issue)
throw new DeploymentSecretPolicyError(issue, { credentialName: "NOMINATIM_DB_PASSWORD" });
}
}
4 changes: 2 additions & 2 deletions packages/core/src/deployment-secret-policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,10 @@ export function deploymentSecretIssue(
}

export class DeploymentSecretPolicyError extends Error {
readonly issue: DeploymentSecretIssue | "invalid-database-url";
readonly issue: DeploymentSecretIssue | "invalid-database-url" | "matches-superuser-password";

constructor(
issue: DeploymentSecretIssue | "invalid-database-url",
issue: DeploymentSecretIssue | "invalid-database-url" | "matches-superuser-password",
options: {
credentialName?: string;
minLength?: number;
Expand Down
31 changes: 31 additions & 0 deletions release-notes/nominatim-own-database-password.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
impacts: [security, operator-action]
---

## What changes

The built-in Nominatim geocoder no longer receives the PostgreSQL superuser's
password (`POSTGRES_PASSWORD`). Its bundled database now uses its own
password, `NOMINATIM_DB_PASSWORD` from `infra/docker/.env`. Nominatim does not
render without it, and the CLI rejects a value that is shorter than 24
characters, a known placeholder or the same as `POSTGRES_PASSWORD`.

## Who is affected

Deployments that enabled the built-in Nominatim service. Others need no
action.

## Required action

Before the next render, set `NOMINATIM_DB_PASSWORD` in `infra/docker/.env` to
a new value, generated with `openssl rand -hex 32`.

The Nominatim image applies this password when it first imports its database.
An existing import keeps its previous password until Nominatim is imported
again.

Because earlier releases handed the superuser's password to the Nominatim
container, rotate `POSTGRES_PASSWORD` on every deployment that ran Nominatim:
set a new value in `infra/docker/.env`, recreate PostGIS and check that it
reports healthy, as described in
[Supporting infrastructure](../docs/docs/guides/supporting-infrastructure.md#the-password).
9 changes: 9 additions & 0 deletions scripts/check-ops-authority.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ const DATABASE_ROLE_OF_SERVICE: Readonly<Record<string, { role: string; password
},
};
const SUPERUSER_DATABASE_URL = /postgres(?:ql)?:\/\/postgres[:@]/;
/** A Compose reference to the superuser's password: `$POSTGRES_PASSWORD` or `${POSTGRES_PASSWORD…}`. */
const SUPERUSER_PASSWORD_REFERENCE = /\$\{?POSTGRES_PASSWORD(?![A-Za-z0-9_])/;

/** `$OPENMAPX_HOST_DIR`, `${OPENMAPX_HOST_DIR}` or `${OPENMAPX_HOST_DIR:?…}`, then the rest of the path. */
const HOST_DIR_SOURCE =
Expand Down Expand Up @@ -279,6 +281,13 @@ export function findAuthorityViolations(root: string = ROOT): AuthorityViolation
file,
detail: `service "${serviceId}" connects to PostgreSQL as the superuser`,
});
// Nor does any other service receive its password, under any name: a
// service with its own database (Nominatim) gets its own password.
if (serviceId !== "postgis" && SUPERUSER_PASSWORD_REFERENCE.test(text))
violations.push({
file,
detail: `service "${serviceId}" receives the PostgreSQL superuser password`,
});
// A missing URL would fall back to the code's superuser default.
const database = DATABASE_ROLE_OF_SERVICE[serviceId];
const environment = manifest.container?.environment;
Expand Down
40 changes: 40 additions & 0 deletions scripts/gate-c-host-authority.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -536,6 +536,46 @@ describe("Gate C — host authority", () => {
(details) => expect(details).toEqual([]),
);
});

it("hands the database superuser's password to PostGIS alone", () => {
const environment = (values: Record<string, string>) => ({
container: { environment: values },
});
withManifests(
{
postgis: environment({ POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?must be set}" }),
nominatim: environment({ NOMINATIM_PASSWORD: "${POSTGRES_PASSWORD:?must be set}" }),
photon: environment({ SCRIPT: "echo $POSTGRES_PASSWORD" }),
// Blanking the variable, and another database's own key, are not references.
"app-api": {
container: {
environment: {
DATABASE_URL: "postgresql://openmapx_api@postgis:5432/openmapx",
DATABASE_PASSWORD_FILE: "/run/secrets/postgres-api-password",
POSTGRES_PASSWORD: "",
},
},
bindMounts: [
{
source: "@infra:secrets/postgres-api-password",
target: "/run/secrets/postgres-api-password",
},
],
},
"dawarich-postgis": {
configSchema: { properties: { POSTGRES_PASSWORD: { "x-openmapx-secret": true } } },
},
martin: environment({ NOMINATIM_PASSWORD: "${NOMINATIM_DB_PASSWORD:?must be set}" }),
},
(details) =>
expect([...details].sort()).toEqual(
[
'service "nominatim" receives the PostgreSQL superuser password',
'service "photon" receives the PostgreSQL superuser password',
].sort(),
),
);
});
// biome-ignore-end lint/suspicious/noTemplateCurlyInString: literal Compose variable sources under test

it("declares no Docker provider anywhere in production service configuration", () => {
Expand Down
2 changes: 1 addition & 1 deletion services/nominatim/service.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
"REPLICATION_UPDATE_INTERVAL": "${NOMINATIM_REPLICATION_UPDATE_INTERVAL:-86400}",
"REPLICATION_RECHECK_INTERVAL": "${NOMINATIM_REPLICATION_RECHECK_INTERVAL:-900}",
"UPDATE_MODE": "${NOMINATIM_UPDATE_MODE:-none}",
"NOMINATIM_PASSWORD": "${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}",
"NOMINATIM_PASSWORD": "${NOMINATIM_DB_PASSWORD:?NOMINATIM_DB_PASSWORD must be set}",
"THREADS": "${NOMINATIM_THREADS:-8}",
"IMPORT_STYLE": "full",
"REVERSE_ONLY": "false",
Expand Down
Loading