Architecture Deep Dive

Architecture Deep Dive

Runtime-Node is not a standard Docker image. It is built FROM scratch. This page explains the specific engineering decisions and edge cases we solved to make Node.js run flawlessly in a void.

1. The Distroless Guarantee (chmod 555)

All core binaries and libraries are copied into the image with --chmod=555 (Read/Execute, No Write). Even if a container is accidentally run as root, the underlying filesystem fights back against modification. Your runtime is completely immutable.

2. DNS Resolution (nsswitch.conf)

By default, a scratch container does not know how to resolve domain names because it lacks OS-level routing configurations. We inject a custom /etc/nsswitch.conf file containing hosts: files dns. This ensures that Node.js functions like dns.lookup() and external database connections route correctly.

3. HTTPS and Certificates (ca-certificates)

To ensure your Node.js application can make secure outgoing API requests, we bundle the latest CA certificates from Alpine. We explicitly copy both /etc/ssl/certs/ca-certificates.crt and /etc/ssl/cert.pem to prevent edge-case TLS failures in specific Node fetch libraries that hardcode path expectations.

4. Timezone Support (tzdata and ENV TZ=UTC)

Standard scratch images lack the IANA Time Zone Database. This causes JavaScript Date objects, Intl.DateTimeFormat, and libraries like date-fns to behave unpredictably. We solve this by:

1. Setting ENV TZ=UTC by default.
2. Injecting the full /usr/share/zoneinfo database, allowing you to seamlessly override the TZ environment variable in your docker-compose.yml to any global timezone.

5. Default Production Environment (ENV NODE_ENV=production)

Standard Node.js runs unpredictably in production if NODE_ENV is not set to production, that's why the NODE_ENV is set to production by default.

6. Temporary Files (/tmp)

Many Node.js frameworks (and native tools) require a writable temporary directory to process file uploads or buffer memory. We provision an empty /tmp directory with the standard 1777 sticky-bit permissions (meaning anyone can write to it, but only the file owner can delete their files).

(Note: For maximum security, we recommend mounting /tmp as a tmpfs volume in your RAM in runtime configuration and to make sure to not allow any execution).