Fix Docker multi-stage build to include native dependencies for mediasoup runtime #33

New Issue

2026-06-16T05:53:10Z

jasper commented

2026-06-16 05:53:10 +00:00

Context

The current Dockerfile utilizes a two-stage build process where the builder stage installs all dependencies via npm ci, including mediasoup (v3.19.14), and generates the Nuxt output in .output/server/index.mjs. The runner stage copies only the .output directory from the builder, excluding node_modules.

While standard JavaScript packages are bundled into the Nuxt server output, mediasoup is a complex native module that relies on platform-specific binaries and pre-compiled addons located within node_modules. If the Nuxt build process does not statically bundle these native components or if the runtime environment requires access to the original node_modules structure for dynamic resolution, the production container will fail to start or crash when attempting to initialize WebRTC streaming capabilities. Additionally, differences in architecture or OS between the builder and runner stages could result in incompatible binaries if they are expected but missing.

Proposed work

Modify the Dockerfile to ensure that necessary node_modules dependencies are available in the runner stage alongside the Nuxt output. This involves copying the node_modules directory from the builder stage to the /app/node_modules path in the runner stage, ensuring that native modules like mediasoup are accessible at runtime.

Acceptance criteria

The Docker image builds successfully without errors regarding missing modules or permission issues.
The application starts and serves traffic on port 3000 within the container.
WebRTC streaming features (mediasoup) function correctly, verifying that native binaries are loaded without ModuleNotFoundError or similar runtime exceptions.
The runner stage retains the non-root user execution (USER node) for security compliance.

Implementation notes

File to modify: Dockerfile.
Current runner stage copies only /app/.output. A new COPY --from=builder instruction is needed to transfer node_modules.
Ensure the copy preserves ownership or sets correct permissions for the node user, as the builder runs as root.
Reference: package.json lists mediasoup as a production dependency, and README.md confirms its use for live streaming.

Test plan

Build the Docker image locally using the modified Dockerfile.
Run the container and verify application startup logs show no missing module warnings.
Initiate a WebRTC session (e.g., via the "Share live" feature documented in README.md) to confirm successful connection and media handling.

## Context The current `Dockerfile` utilizes a two-stage build process where the `builder` stage installs all dependencies via `npm ci`, including `mediasoup` (v3.19.14), and generates the Nuxt output in `.output/server/index.mjs`. The `runner` stage copies only the `.output` directory from the builder, excluding `node_modules`. While standard JavaScript packages are bundled into the Nuxt server output, `mediasoup` is a complex native module that relies on platform-specific binaries and pre-compiled addons located within `node_modules`. If the Nuxt build process does not statically bundle these native components or if the runtime environment requires access to the original `node_modules` structure for dynamic resolution, the production container will fail to start or crash when attempting to initialize WebRTC streaming capabilities. Additionally, differences in architecture or OS between the builder and runner stages could result in incompatible binaries if they are expected but missing. ## Proposed work Modify the Dockerfile to ensure that necessary `node_modules` dependencies are available in the `runner` stage alongside the Nuxt output. This involves copying the `node_modules` directory from the `builder` stage to the `/app/node_modules` path in the `runner` stage, ensuring that native modules like `mediasoup` are accessible at runtime. ## Acceptance criteria - The Docker image builds successfully without errors regarding missing modules or permission issues. - The application starts and serves traffic on port 3000 within the container. - WebRTC streaming features (mediasoup) function correctly, verifying that native binaries are loaded without `ModuleNotFoundError` or similar runtime exceptions. - The `runner` stage retains the non-root user execution (`USER node`) for security compliance. ## Implementation notes - File to modify: `Dockerfile`. - Current `runner` stage copies only `/app/.output`. A new `COPY --from=builder` instruction is needed to transfer `node_modules`. - Ensure the copy preserves ownership or sets correct permissions for the `node` user, as the builder runs as root. - Reference: `package.json` lists `mediasoup` as a production dependency, and `README.md` confirms its use for live streaming. ## Test plan - Build the Docker image locally using the modified `Dockerfile`. - Run the container and verify application startup logs show no missing module warnings. - Initiate a WebRTC session (e.g., via the "Share live" feature documented in `README.md`) to confirm successful connection and media handling.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: keligrubb/kestrelos#33