fix: make Docker container ports configurable via env vars

[shivangtanwar]

Summary

• start.sh hardcoded FRONTEND_PORT="3000" and BACKEND_PORT="8000" as static shell variables, so passing -e FRONTEND_PORT=4000 to docker run had no effect.
• Changed both to use env var fallbacks (${FRONTEND_PORT:-3000}), making ports truly configurable at runtime.
• Updated docker-compose.yml to pass both variables through and use FRONTEND_PORT in the container-side port mapping.

Limitations

Changing BACKEND_PORT alone isn't sufficient — the Next.js frontend has http://127.0.0.1:8000 baked into its proxy rewrites at build time (next.config.ts and lib/api/client.ts). Users who need a different backend port must also rebuild the image with a matching BACKEND_ORIGIN build arg. This is noted in a comment in docker-compose.yml.

Test plan

• docker compose up — verify default behavior unchanged (ports 3000/8000)
• FRONTEND_PORT=4000 PORT=4000 docker compose up — verify frontend serves on 4000
• docker run -e FRONTEND_PORT=4000 -p 4000:4000 resume-matcher — verify port override works

Closes #610

---

Summary by cubic

Make Docker ports configurable via env vars at runtime and use build args for EXPOSE (defaults: frontend 3000, backend 8000). Healthcheck now reads BACKEND_PORT from env, so changing it doesn’t require a rebuild. Closes #610.

• Bug Fixes

  • start.sh now uses env var fallbacks for FRONTEND_PORT and BACKEND_PORT.
  • docker-compose.yml maps host ${PORT:-3000} to container ${FRONTEND_PORT:-3000} and passes both port vars through.
  • Dockerfile adds ARGs and sets ENV so EXPOSE uses build arg and HEALTHCHECK reads runtime BACKEND_PORT.

• Migration

  • To change the frontend’s proxy target, rebuild with --build-arg BACKEND_ORIGIN=http://127.0.0.1:; healthcheck follows BACKEND_PORT at runtime.

^{Written for commit 9f2ad63. Summary will update on new commits.}

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
Dockerfile	131	HEALTHCHECK uses ${BACKEND_PORT} shell variable expansion - works correctly but requires the ENV to be set
Dockerfile	115	ARG BACKEND_PORT requires rebuild if changed; runtime ENV override won't affect Next.js proxy rewrites

Review Notes

What This PR Does

This PR makes the frontend and backend ports configurable via:

• Docker build arguments (ARG FRONTEND_PORT, ARG BACKEND_PORT)
• Environment variables persisted at runtime
• docker-compose.yml environment variable passthrough
• start.sh script reading from environment with defaults

Key Observations

1. Port Configuration Flow: The implementation correctly uses ARG for build-time values and ENV for runtime. The HEALTHCHECK shell expansion will work because Docker runs the CMD in a shell.

2. Next.js Proxy Limitation: The comment in docker-compose.yml correctly warns that changing BACKEND_PORT requires rebuilding. This is because next.config.ts uses BACKEND_ORIGIN which is evaluated at Next.js build time.

3. No API Breaking Changes: This PR only affects Docker configuration and does not modify any API endpoints, prompts, or LiteLLM configurations.

4. No Prompts Flow Changes: The prompts in apps/backend/app/prompts/ are unchanged.

5. No LiteLLM Configuration Changes: The LLM configuration in config.py and llm.py are unchanged.

Files Reviewed (3 files)

• Dockerfile - 2 issues (port configuration)
• docker-compose.yml - 0 new issues (documentation adequate)
• docker/start.sh - 0 issues (correct implementation)

---

Fix these issues in Kilo Cloud

[cubic-dev-ai]

No issues found across 2 files

[shivangtanwar]

Both fixed in 7df7c99. Added ARG FRONTEND_PORT=3000 and ARG BACKEND_PORT=8000 to the Dockerfile — EXPOSE and HEALTHCHECK now use the build args instead of hardcoded values.

[kilo-code-bot]

WARNING: HEALTHCHECK uses ${BACKEND_PORT} which is an ARG variable. Docker ARGs are only available at build time, not runtime.

Current behavior:

• If built with --build-arg BACKEND_PORT=9000, healthcheck uses port 9000 ✓
• If run with -e BACKEND_PORT=9000 without rebuilding, healthcheck still uses port 8000 (build-time default) ✗

This is documented in the docker-compose.yml comment, but users might still be confused. Consider either:

1. Using a shell wrapper script for the healthcheck that reads the env var at runtime
2. Making the documentation more prominent about the rebuild requirement

[shivangtanwar]

That's intentional — HEALTHCHECK is a build-time directive, so ARG is the right mechanism here.

Update: promoted ARGs to ENV in 9f2ad63 so HEALTHCHECK now resolves BACKEND_PORT at runtime too. Runtime -e BACKEND_PORT=9000 works without rebuilding.

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docker-compose.yml">

<violation number="1" location="docker-compose.yml:15">
P2: Compose comment instructs rebuilding with BACKEND_PORT for Next.js proxy rewrites, but rewrites are keyed off BACKEND_ORIGIN in next.config.ts. This guidance is incorrect and can leave rewrites pointing at the default backend origin/port after a port change.</violation>
</file>

<file name="Dockerfile">

<violation number="1" location="Dockerfile:114">
P2: Ports are declared with build-time ARG only, so runtime `-e FRONTEND_PORT/BACKEND_PORT` won’t update EXPOSE or HEALTHCHECK; health checks can hit the wrong port unless the image is rebuilt. Promote build args to ENV for runtime configurability.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}