Research: Public API Build Configuration

Decision 1: Bind the public API address at build time

Decision: Treat the client API destination as a required build-time value for production.

Rationale: Next.js inlines NEXT_PUBLIC_ values into browser JavaScript during next build. Changing a runtime container environment cannot alter that already-built browser bundle.

Alternatives considered:

• Runtime client configuration endpoint: rejected for this hotfix because it adds a request, caching behavior, and a new failure mode.
• Same-origin reverse proxy: rejected because the current production setup exposes the API on a separate public host and no proxy contract was requested.

Decision 2: Use Dokploy Build Time Arguments

Decision: Configure the public API address in Dokploy's Build Time Arguments field.

Rationale: Dokploy passes Docker build arguments to the Dockerfile, matching the point at which Next.js freezes public client variables. The API address is public, so it is not a secret.

Alternatives considered:

• Dokploy runtime environment variable: rejected because it arrives after the client bundle is produced.
• Build-time secret: rejected because the public API address is intentionally visible in the browser and a secret interface is misleading.

Decision 3: Fail closed in production

Decision: A production build fails when the API destination is absent, invalid, or points to localhost.

Rationale: A failed delivery gives the deploy owner an actionable correction; a localhost bundle appears healthy but cannot serve production users.

Sources: Next.js environment variables, Dokploy Docker build arguments.