docker-service-discovery/openspec/changes/archive/2026-03-31-backend-url-env-var/design.md

Context

As outlined in the proposal, the frontend application's backend URL is hardcoded. This design details the technical approach to make this configurable, improving deployment flexibility across different environments.

Goals / Non-Goals

Goals:

• To allow the backend URL for the frontend application to be set via an environment variable named REACT_APP_BACKEND_URL.
• To update the Docker configuration to support passing this environment variable at runtime.
• To ensure the application remains runnable locally with a sensible default, requiring no extra setup for local development.

Non-Goals:

• This change will not address dynamic configuration updates at runtime. A restart of the frontend application will be needed for a new URL to take effect.
• This will not involve any changes to the backend service itself.

Decisions

• Environment Variable Name: We will use REACT_APP_BACKEND_URL. Create React App's build process automatically embeds environment variables prefixed with REACT_APP_ into the application, making them accessible via process.env.REACT_APP_BACKEND_URL. This is the standard and simplest method for this stack.
• Default Value: In the frontend JavaScript code, we will implement a fallback to http://localhost:3001 if the REACT_APP_BACKEND_URL environment variable is not set. This ensures that running npm start locally continues to work out-of-the-box.
• Docker Configuration: The docker-compose.yml file will be modified to accept the REACT_APP_BACKEND_URL environment variable and pass it to the frontend service. This allows operators to configure the backend URL when running docker-compose up.

Risks / Trade-offs

• Risk: If the REACT_APP_BACKEND_URL is not set in a production environment, the frontend will default to http://localhost:3001, which will fail.
  • Mitigation: Deployment documentation and CI/CD scripts must be updated to explicitly require and validate the presence of the REACT_APP_BACKEND_URL variable for all non-local environments.