Debugging

Debugging Without a Shell

Runtime-Node strictly enforces a distroless guarantee: there is no /bin/sh, bash, or ash included in the image.

If you attempt to run docker exec -it <container_name> /bin/sh, you will receive an executable file not found in $PATH error. This is a security feature, not a bug. By eliminating the shell, we eliminate Remote Code Execution (RCE) escalation paths.

How to Debug in a Distroless Environment

1. Use Application-Level Logging (Recommended) Your application should be treated as an immutable black box. Output all necessary telemetry, errors, and access logs to stdout and stderr using console.log() or a structured logger like Pino/Winston. Docker automatically captures this stream:

   docker logs -f my_running_container

2. The Temporary Swap Method (For Deep Debugging) If you have a persistent file-system bug or path issue that you absolutely must investigate interactively, temporarily swap the base image in your Dockerfile.

   Change this:

   FROM runtimenode/runtime-node:v<major>.<minor>.<patch>+node<node_version>

   To this:

   FROM node:<node_version>-alpine3.23

   Rebuild the image, docker exec into it, find the bug, fix your code, and switch back to runtimenode for your production deployment.