Skip to content

fix(cli): honor SUPABASE_API_* overrides (CLI-2318) #6467

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
7ttp wants to merge 4 commits into
base: develop
Choose a base branch
from
+696 −122
Open

fix(cli): honor SUPABASE_API_* overrides (CLI-2318) #6467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dff4f32
fix(cli): honor SUPABASE_API_* overrides for the local storage gateway
7ttp Sep 3, 2026
af1061b
fix: reject zero api.port for the local gateway
7ttp Sep 4, 2026
397b142
refactor: few more review nits
7ttp Sep 4, 2026
ea4123b
fix: validate api overrides on the empty-config path
7ttp Sep 4, 2026
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
1 change: 1 addition & 0 deletions apps/cli/src/legacy/commands/db/reset/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,7 @@ the whole reset** (not just "skip buckets").
| `SUPABASE_USE_SLIM_IMAGES` | resolves the local-reset Postgres image, realtime/storage/auth migrate-job images, and the pg-delta edge-runtime catalog-export image from slim `ghcr.io/supabase/cli` builds (`true`/`1` enable); majors 13/15 use `15.14.1.167` when the flag is on; historical pins, PG14, OrioleDB, flag-off `15.8.1.085`, `deno_version = 1`, and historical `.temp/edge-runtime-version` pins stay on docker.io | no (ambient shell only) |
| `PGDELTA_NPM_REGISTRY` | overrides the pg-delta edge-runtime npm registry (`.npmrc` + `NPM_CONFIG_REGISTRY` forward) for the migrations-catalog cache export (scoped for the whole run via `legacyApplyProjectEnv`, matching `db push`) | no (project `.env` or shell) |
| `SUPABASE_DB_PORT` / `SUPABASE_DB_MAJOR_VERSION` / `SUPABASE_DB_HEALTH_TIMEOUT` / `SUPABASE_DB_SETTINGS_*` | local-path container-recreate config overrides, same as `db start` | no |
| `SUPABASE_API_PORT` / `SUPABASE_API_EXTERNAL_URL` / `SUPABASE_API_TLS_*` / `SUPABASE_API_ENABLED` | local-path bucket-seed step: override the matching `[api]` fields for the Storage gateway URL/TLS, same as `seed buckets` (shell or project dotenv; #6452) | no |
| `SUPABASE_NETWORK_ID` (`--network-id`) | forces the recreated container/network onto an existing Docker network | no |

## Connection loss during migration apply
Expand Down
64 changes: 35 additions & 29 deletions apps/cli/src/legacy/commands/seed/buckets/SIDE_EFFECTS.md
View file
Open in desktop

Large diffs are not rendered by default.

326 changes: 326 additions & 0 deletions apps/cli/src/legacy/commands/seed/buckets/buckets.integration.test.ts
View file
Open in desktop

Large diffs are not rendered by default.

21 changes: 11 additions & 10 deletions apps/cli/src/legacy/commands/start/start.handler.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1926,16 +1926,14 @@ export const legacyStart = Effect.fn("legacy.start")(function* (flags: LegacySta
// raw values) so a `SUPABASE_API_ENABLED`/`SUPABASE_API_PORT`/
// `SUPABASE_API_TLS_{ENABLED,CERT_PATH,KEY_PATH}`/`SUPABASE_API_EXTERNAL_URL`
// override that actually brought Kong up on a different port/TLS/cert/
// external URL also reaches every local Storage-gateway caller below —
// otherwise `resolveLocalBaseUrl` derives its URL from the un-overridden
// `config.api.{port,tls.enabled,external_url}` and points at a
// port/scheme/host nothing is actually listening on, and
// `validateLocalKongTls`'s own `opts.config.api.enabled &&
// opts.config.api.tls.enabled` gate (`legacy-storage-credentials.ts`)
// validates against a cert/key path Kong itself isn't actually serving
// from when `api.enabled` disagrees with the raw config (Kong's own spec
// uses these same resolved `apiEnabled`/`apiTlsCertPath`/`apiTlsKeyPath`
// locals). Also folds in the
// external URL also reaches every local Storage-gateway caller below.
// `legacyResolveStorageCredentials` now folds the same `SUPABASE_API_*`
// overrides itself (`resolveLocalApiConfig`,
// `legacy-storage-credentials.ts` — #6452) and re-resolves this
// pre-folded config to identical values, so the api fold here is what
// guarantees the exact resolved-URL/TLS/cert locals Kong's own spec used
// (`apiEnabled`/`apiTlsCertPath`/`apiTlsKeyPath`) are the ones handed
// on. Also folds in the
// already-resolved `values.jwtSecret`/`values.serviceRoleKey` (decrypted,
// env/dotenv-overridden — the same values the real GoTrue/Storage containers
// were started with) instead of the raw `config.auth.*`
Expand Down Expand Up @@ -1982,6 +1980,7 @@ export const legacyStart = Effect.fn("legacy.start")(function* (flags: LegacySta
const { localKongCa } = yield* legacyResolveStorageCredentials({
projectRef: "",
config: effectiveLocalStorageConfig,
projectEnvValues,
});
// Shared by every gateway probe below (the bulk wait and the
// storage-only recheck), so both trust the same local Kong CA.
Expand Down Expand Up @@ -2038,6 +2037,7 @@ export const legacyStart = Effect.fn("legacy.start")(function* (flags: LegacySta
config: effectiveLocalStorageConfig,
document: context.loaded?.document,
},
projectEnvValues,
}).pipe(Effect.result);
if (Result.isFailure(seedResult)) {
// No manual `legacyRollbackStart` here — the outer
Expand Down Expand Up @@ -2083,6 +2083,7 @@ export const legacyStart = Effect.fn("legacy.start")(function* (flags: LegacySta
config: effectiveLocalStorageConfig,
document: context.loaded?.document,
},
projectEnvValues,
});
}

Expand Down
18 changes: 10 additions & 8 deletions apps/cli/src/legacy/commands/storage/cp/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,14 @@ Copies objects between local paths and the Storage service. The scheme of `src`/

## Files Read

| Path | Format | When |
| ---------------------------------------- | ---------- | ------------------------------------------------------------------ |
| `<workdir>/supabase/config.toml` | TOML | always (local creds; `[storage.buckets.*]` for bucket auto-create) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| upload source files | bytes | upload: sniff (≤512 bytes) + streamed body |
| Path | Format | When |
| --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always (local creds; `[storage.buckets.*]` for bucket auto-create) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| `<workdir>/supabase/.env*`, `<workdir>/.env*` | dotenv | local path, to resolve the `SUPABASE_API_*` overrides for the gateway URL/TLS (#6452) |
| upload source files | bytes | upload: sniff (≤512 bytes) + streamed body |

## Files Written

Expand All @@ -38,7 +39,8 @@ Auth: `apikey` always; `Authorization: Bearer <key>` unless the key is `sb_`-pre
## Environment Variables

`SUPABASE_AUTH_SERVICE_ROLE_KEY`, `SUPABASE_AUTH_JWT_SECRET`, `SUPABASE_ACCESS_TOKEN`,
`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME` — same roles as `storage ls`.
`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME`, and the `SUPABASE_API_*`
override family — same roles as `storage ls`.
`SUPABASE_PROJECT_ID`'s linked-ref resolution is superseded by `--project-ref` when set.

`storage` is an experimental command: `cp` requires `--experimental`
Expand Down
30 changes: 16 additions & 14 deletions apps/cli/src/legacy/commands/storage/ls/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@ Lists objects/buckets by path prefix against the Storage gateway (local stack or

## Files Read

| Path | Format | When |
| ---------------------------------------- | ---------- | ------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always (local creds/baseUrl; `[remotes.*]` merge when linked) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| Path | Format | When |
| --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always (local creds/baseUrl; `[remotes.*]` merge when linked) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| `<workdir>/supabase/.env*`, `<workdir>/.env*` | dotenv | local path, to resolve the `SUPABASE_API_*` overrides for the gateway URL/TLS (#6452) |

## Files Written

Expand All @@ -30,14 +31,15 @@ Auth: `apikey` header always; `Authorization: Bearer <key>` unless the key is `s

## Environment Variables

| Variable | Purpose | Required? |
| -------------------------------- | ---------------------------------------------------------------------- | ---------------------------------- |
| `SUPABASE_AUTH_SERVICE_ROLE_KEY` | linked: bypass tenant key fetch; local: explicit key | no |
| `SUPABASE_AUTH_JWT_SECRET` | local: derive service-role key | no (→ `auth.jwt_secret` → default) |
| `SUPABASE_ACCESS_TOKEN` | linked: Management API auth | no (→ `~/.supabase/access-token`) |
| `SUPABASE_PROJECT_ID` | linked: project-ref resolution, superseded by `--project-ref` when set | no |
| `SUPABASE_SERVICES_HOSTNAME` | local baseUrl host | no (→ Docker host → `127.0.0.1`) |
| `SUPABASE_EXPERIMENTAL` | experimental gate: `--experimental` equivalent | yes, unless `--experimental` given |
| Variable | Purpose | Required? |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `SUPABASE_AUTH_SERVICE_ROLE_KEY` | linked: bypass tenant key fetch; local: explicit key | no |
| `SUPABASE_AUTH_JWT_SECRET` | local: derive service-role key | no (→ `auth.jwt_secret` → default) |
| `SUPABASE_ACCESS_TOKEN` | linked: Management API auth | no (→ `~/.supabase/access-token`) |
| `SUPABASE_PROJECT_ID` | linked: project-ref resolution, superseded by `--project-ref` when set | no |
| `SUPABASE_SERVICES_HOSTNAME` | local baseUrl host | no (→ Docker host → `127.0.0.1`) |
| `SUPABASE_API_PORT`, `SUPABASE_API_EXTERNAL_URL`, `SUPABASE_API_TLS_ENABLED`, `SUPABASE_API_TLS_CERT_PATH`, `SUPABASE_API_TLS_KEY_PATH`, `SUPABASE_API_ENABLED` | local: override the matching `[api]` fields for the gateway URL/TLS, shell env or project dotenv (shell wins; #6452) | no |
| `SUPABASE_EXPERIMENTAL` | experimental gate: `--experimental` equivalent | yes, unless `--experimental` given |

`storage` is an experimental command: every subcommand requires
`--experimental` (or `SUPABASE_EXPERIMENTAL`), else it exits 1 with
Expand Down
16 changes: 9 additions & 7 deletions apps/cli/src/legacy/commands/storage/mv/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@ A direct move that returns `not_found` falls back to a recursive per-object move

## Files Read

| Path | Format | When |
| ---------------------------------------- | ---------- | ----------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always (local creds; `[remotes.*]` merge when linked) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| Path | Format | When |
| --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always (local creds; `[remotes.*]` merge when linked) |
| `~/.supabase/access-token` | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset |
| `~/.supabase/<hash>/linked-project.json` | JSON | linked path, to resolve the project ref |
| local Kong TLS cert/key | PEM | local + `api.enabled` + `api.tls.enabled` |
| `<workdir>/supabase/.env*`, `<workdir>/.env*` | dotenv | local path, to resolve the `SUPABASE_API_*` overrides for the gateway URL/TLS (#6452) |

## Files Written

Expand All @@ -33,7 +34,8 @@ Auth: `apikey` always; `Authorization: Bearer <key>` unless the key is `sb_`-pre
## Environment Variables

`SUPABASE_AUTH_SERVICE_ROLE_KEY`, `SUPABASE_AUTH_JWT_SECRET`, `SUPABASE_ACCESS_TOKEN`,
`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME` — same roles as `storage ls`.
`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME`, and the `SUPABASE_API_*`
override family — same roles as `storage ls`.
`SUPABASE_PROJECT_ID`'s linked-ref resolution is superseded by `--project-ref` when set.

`storage` is an experimental command: `mv` requires `--experimental`
Expand Down
Loading
Loading