bfren/node repository overview

⁠Node.js

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

Node.js⁠ and npm, running your app as a supervised service. It is built on Alpine + S6⁠, with Node.js from Alpine's packages - each Node.js version uses the newest Alpine release that has it.

The image runs /app/live/index.js as the node user. Use it as the base for a Node.js app's image (as Send⁠ does), or mount a ready-to-run app into it.

⁠Quickstart

With your app (including node_modules) in ./app, and index.js listening on port 3000:

services:
  app:
    image: quay.io/bfren/node:node24-4.2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./app:/app/live

Run docker compose up -d, then open http://127.0.0.1:3000. Without your own app, a welcome page is shown.

Your app must listen on 0.0.0.0 (all interfaces), not 127.0.0.1 - otherwise it can't be reached through the published port.

⁠Features

• 🟩 Node.js 16 to 26 - choose with the image tag
• 📦 npm installed
• 🧭 Your app runs under S6 supervision as node (UID 1000), not root
• 🛑 The container stops if your app crashes, so Docker can restart it
• 🔐 /app/live is made read-only for the app on every start
• 🧪 Built-in tests

⁠Tags

Images are published to Docker Hub (bfren/node) and Quay.io (quay.io/bfren/node) for linux/amd64 and linux/arm64.

Use an LTS version for anything long-lived - see the Node.js release schedule⁠. Images for versions that have ended are still built, but get no Node.js fixes.

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

This image adds none of its own. See Alpine + S6⁠ for BF_DEBUG, BF_TZ and the other base image variables. Your app can read any variables you pass to the container.

⁠How It Works

On every start the Node.js and npm versions are written to the log, and everything in /app/live is given to the node user and made read-only (0400 files, 0500 folders). Then node /app/live/index.js runs under S6 as node.

If your app crashes (exits with an error), the container stops - set a restart policy so Docker starts it again. If it exits cleanly, S6 starts it again inside the container.

The health check is the base image's, which checks cron is running - it doesn't check your app. To check your app, add a script to /etc/bf/health.d in your own image (see Alpine + S6⁠).

⁠Building on this image

Copy your app into /app/live and install its dependencies when the image is built:

FROM quay.io/bfren/node:node24-4.2

COPY ./app /app/live
RUN cd /app/live && npm ci --omit=dev

index.js must be the entry point. If your app's entry point is elsewhere, add an index.js that loads it, e.g. require('./dist/server.js');.

⁠Testing

./test.nu                   # builds Node.js 24 and runs /test
./test.nu 20                # or any version directory
./test.nu --all             # every version, in parallel
./run.sh 24                 # builds and opens a shell
./generate-dockerfiles.sh   # regenerates the Dockerfiles from Dockerfile.esh

/test runs this image's tests alongside the base images' tests: the app paths, the welcome page (valid JavaScript, listening on all interfaces), the installed Node.js and npm versions, and the service scripts.

⁠Troubleshooting

⁠The container stops straight after starting

Your app crashed. Check docker logs <container> for its error - often a missing node_modules folder, or no /app/live/index.js.

⁠My app can't write files (EACCES)

/app/live is read-only on purpose. Write data to another folder, and mount a volume there.

⁠The port is published but nothing answers

Your app is probably listening on 127.0.0.1 or localhost - change it to 0.0.0.0.

⁠FAQs

⁠How do I run npm install in the container?

docker exec <container> sh -c 'cd /app/live && npm install' works, but installing when the image is built (see Building on this image⁠) is more reliable, and the new files are only given to node on the next start.

⁠Can I use a different entry file?

Not directly - /app/live/index.js is always run. Make it load your real entry point.

⁠Licence

⁠Copyright