Function startContainer

packages/container/src/dev.ts:468–658

(
  options: StartDevServerOptions,
  reuseKey: string
)

}

async function startContainer(
  options: StartDevServerOptions,
  reuseKey: string
): Promise<StartDevServerResult> {
  return withSpan(
    options.span,
    'container.dev.start',
    { 'service.name': options.service?.name },
    async span => {
      const { config, meta, onStdout, onStderr } = options;
      const out: DevOutput = { onStdout, onStderr };

      // Fail fast with a clear message if Docker isn't running, rather than
      // letting `docker build`/`docker run` fail later with a bare exit code.
      await assertDockerAvailable(out);

      const image = await withSpan(span, 'container.dev.resolve_image', {}, s =>
        resolveDevImage(options, out, s)
      );

      const containerPort = await resolveContainerPort(image, out);
      const containerName = uniqueContainerName(
        options.service?.name ?? 'service'
      );

      // Env precedence: CLI process env, then the orchestrator's per-service
      // env (service URLs, resolved .env values), then a `PORT` the app honors.
      // Host/shell-only vars (TMPDIR, HOME, PATH, …) are filtered out: they
      // describe the developer's machine, not the Linux container, and leaking
      // them breaks apps that rely on container-native values (see
      // `isHostOnlyEnvVar`). Passed via a temp `--env-file` to keep secrets off
      // the command line and avoid arg-length limits.
      const mergedEnv: Record<string, string> = {};
      for (const [key, value] of Object.entries(process.env)) {
        if (typeof value === 'string' && !isHostOnlyEnvVar(key)) {
          mergedEnv[key] = value;
        }
      }
      const metaEnv = (meta?.env ?? {}) as Record<string, string | undefined>;
      for (const [key, value] of Object.entries(metaEnv)) {
        if (typeof value === 'string' && !isHostOnlyEnvVar(key)) {
          mergedEnv[key] = value;
        }
      }
      mergedEnv.PORT = String(containerPort);
      const envFilePath = writeEnvFile(mergedEnv);

      const command = normalizeCommand(
        (config as { command?: unknown }).command
      );

      // Honor the host port the orchestrator pre-allocated for this service
      // (passed via `meta.port`). Service bindings are built against this port
      // (`http://127.0.0.1:${preAllocatedPort}/`), so the container must listen
      // on it for cross-service requests to reach it. Fall back to `0` (an
      // ephemeral port chosen by Docker) when no port was provided.
      const requestedHostPort = typeof meta?.port === 'number' ? meta.port : 0;