node.js

First, let's create a project structure:

mkdir -p ~/hello-world-node/src && cd ~/hello-world-node

This creates the following folder structure and sets our working directory to the root hello-world-node folder:

hello-world-node
└── src

Now let's create a package.json file, which provides metadata about the project, including dependencies:

cat << 'EOF' > package.json
{
  "name": "hello-world-app",
  "version": "1.0.0",
  "description": "Simple Node.js hello world server",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js"
  },
  "dependencies": {}
}
EOF

The above defines a package, hello-world-app, with no external dependencies that will run the code in src/index.js when started.

Let's create our application code now.

cat << 'EOF' > src/index.js
const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from Docker Hardened Node.js!\n');
});

const port = process.env.PORT || 3000;
server.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});
EOF

This application code creates a simple HTTP server using Node.js built-in http module. The server listens on port 3000 (or the PORT environment variable) and responds to all requests with a greeting message.

Finally, let's create a Dockerfile for our image build:

cat << 'EOF' > Dockerfile
# syntax=docker/dockerfile:1
# Use dev variant for building
FROM registry.ghost-prod.alphabravo.io/ghost-base/node:<tag>-dev AS build-stage

ENV NODE_ENV=production
WORKDIR /usr/src/app

# Copy package files
COPY package*.json ./

# Install dependencies and ensure node_modules exists
RUN npm i --omit=dev && mkdir -p node_modules

# Use runtime variant for final image
FROM registry.ghost-prod.alphabravo.io/ghost-base/node:<tag> AS runtime-stage

ENV NODE_ENV=production
WORKDIR /usr/src/app

# Copy node_modules from build stage
COPY --from=build-stage /usr/src/app/node_modules ./node_modules

# Copy application code
COPY src ./src
COPY package*.json ./

# Expose port (use non-privileged port)
EXPOSE 3000

# Start the application
CMD ["node", "src/index.js"]
EOF

This Dockerfile uses a multi-stage build with the -dev variant for building and the runtime variant for the final image. It sets the NODE_ENV environment variable to production, copies our application files, and runs our Node.js server.

Build and run the image

docker build -t hello-world-node .

Finally, run the container:

docker run --rm -p 3000:3000 --name hello-world-app hello-world-node

You should see the following output:

Server running on port 3000

You can test the application by opening another terminal and running:

curl http://localhost:3000

This should produce the following output:

Hello World from Docker Hardened Node.js!

You can also visit http://localhost:3000 in your browser to see the same message.

Yarn Configuration

Yarn Version Compatibility

Docker Hardened Node.js images support all versions of Yarn (v1.x Classic and v2+/v4+ Berry) out of the box. The images do not set any Yarn-specific environment variables that could interfere with your project's Yarn configuration.

Using Yarn v1 (Classic)

Yarn v1 (Classic) is included in the Node.js images by default. No additional configuration is needed:

FROM registry.ghost-prod.alphabravo.io/ghost-base/node:<tag>-dev AS build-stage

WORKDIR /usr/src/app
COPY package*.json yarn.lock ./

# Yarn v1 works out of the box
RUN yarn install --frozen-lockfile

If you want to disable Yarn's update checks in your project, add to your project's .yarnrc file:

disable-self-update-check true

Using Yarn v2+ (Berry) / Yarn v4

To use modern Yarn versions (v2+, v3, v4), use Corepack which is included in Node.js:

FROM registry.ghost-prod.alphabravo.io/ghost-base/node:<tag>-dev AS build-stage

WORKDIR /usr/src/app

# Enable Corepack and prepare Yarn version
RUN corepack enable

# Copy package files (package.json should specify packageManager)
COPY package*.json yarn.lock .yarnrc.yml ./

# Install dependencies with Yarn v4
RUN yarn install --immutable

Your package.json should specify the Yarn version:

{
  "name": "my-app",
  "version": "1.0.0",
  "packageManager": "yarn@4.10.3",
  "dependencies": {
    ...
  }
}

Why No YARN_DISABLE_SELF_UPDATE_CHECK?

Previous versions of Docker Hardened Node.js images set the YARN_DISABLE_SELF_UPDATE_CHECK=true environment variable globally. This was removed because:

1. Yarn v2+/v4+ compatibility: This environment variable is a Yarn v1 (Classic) configuration that causes Yarn v2+ to fail immediately with an error
2. Project control: Projects should control their own Yarn configuration rather than inheriting it from base images
3. Non-breaking for Yarn v1: Yarn v1 works correctly without this environment variable; it just performs update checks (which are non-blocking)

If you're using Yarn v1 and want to disable update checks, add the configuration to your project's .yarnrc file as shown above.

Troubleshooting Yarn Issues

Error: "Unrecognized or legacy configuration settings found: disableSelfUpdateCheck"

This error occurs when using Yarn v2+ with an environment variable or configuration meant for Yarn v1. Docker Hardened Node.js images no longer set this variable, but if you're seeing this error:

1. Check if you're setting YARN_DISABLE_SELF_UPDATE_CHECK in your Dockerfile
2. Check if you have a legacy .yarnrc file (without .yml extension) with Yarn v1 configuration
3. Ensure you're using .yarnrc.yml for Yarn v2+ configuration

Yarn version mismatch

If you're using Corepack and the wrong Yarn version is being used:

# Explicitly prepare the Yarn version from package.json
RUN corepack enable && corepack prepare yarn@$(node -p "require('./package.json').packageManager.split('@')[1]") --activate

For more information about Yarn configuration, see:

• Yarn v1 (Classic) Documentation
• Yarn v2+/v4 (Berry) Documentation

Non-hardened images vs Ghost hardened images

Key differences

Why no shell or package manager in runtime variants?

Ghost hardened images prioritize security through minimalism:

• Reduced attack surface: Fewer binaries mean fewer potential vulnerabilities
• Immutable infrastructure: Runtime containers shouldn't be modified after deployment
• Compliance ready: Meets strict security requirements for regulated environments

The hardened images intended for runtime don't contain a shell nor any tools for debugging. Common debugging methods for applications built with Ghost hardened images include:

• Docker Debug to attach to containers
• Docker's Image Mount feature to mount debugging tools
• Application-level logging and monitoring

Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

• For example, you can use Docker Debug:

$ docker debug <container-name>

to get a debug shell into any container or image, even if they don't contain a shell.

Image variants

Ghost hardened images come in different variants depending on their intended use. Image variants are identified by their tag.

• Runtime variants are designed to run your application in production. These images are intended to be used either directly or as the FROM image in the final stage of a multi-stage build. These images typically:

  • Run as a nonroot user
  • Do not include a shell or a package manager
  • Contain only the minimal set of libraries needed to run the app

• Build-time variants typically include dev in the tag name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

  • Run as the root user
  • Include a shell and package manager
  • Are used to build or compile applications

To view the image variants and get more information about them, select the Tags tab for this repository, and then select a tag.

FIPS variants

FIPS variants include fips in the variant name and tag. They come in both runtime and build-time variants. These variants use cryptographic modules that have been validated under FIPS 140, a U.S. government standard for secure cryptographic operations. Docker Hardened Node.js images include FIPS-compliant variants for environments requiring Federal Information Processing Standards compliance.

Steps to verify FIPS:

# Check FIPS status (should return 1 for enabled)
$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/node:<tag>-fips \
  node -e "console.log('FIPS status:', require('crypto').getFips ? require('crypto').getFips() : 'FIPS method not available')"

# Verify cipher restrictions (FIPS has significantly fewer available)
$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/node:<tag>-fips \
  node -e "console.log('FIPS ciphers:', require('crypto').getCiphers().length)"

$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/node:<tag> \
  node -e "console.log('Non-FIPS ciphers:', require('crypto').getCiphers().length)"

# Test disabled cryptographic functions (MD5 disabled in FIPS)
$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/node:tag>-fips \
  node -e "
  try {
    require('crypto').createHash('md5').update('test').digest('hex');
    console.log('MD5: Available');
  } catch(e) {
    console.log('MD5: Disabled -', e.message);
  }"

Runtime requirements specific to FIPS:

• FIPS mode enforces stricter cryptographic standards
• Weak cryptographic functions like MD5 are disabled and will fail at runtime
• Applications using restricted algorithms may need modification
• Only FIPS-approved cryptographic algorithms are available (~60% fewer than non-FIPS)

Migrate to a Ghost hardened image

To migrate your application to a Ghost hardened image, you must update your Dockerfile. At minimum, you must update the base image in your existing Dockerfile to a Ghost hardened image. This and a few other common changes are listed in the following table of migration notes.

Migrate to a Ghost hardened image

The following steps outline the general migration process.

1. Find hardened images for your app.

   A hardened image may have several variants. Inspect the image tags and find the image variant that meets your needs. Node.js images are available in versions 18, 20, 22 and 24

2. Update the base image in your Dockerfile.

   Update the base image in your application's Dockerfile to the hardened image you found in the previous step. For framework images, this is typically going to be an image tagged as dev because it has the tools needed to install packages and dependencies.

3. For multi-stage Dockerfiles, update the runtime image in your Dockerfile.

   To ensure that your final image is as minimal as possible, you should use a multi-stage build. All stages in your Dockerfile should use a hardened image. While intermediary stages will typically use images tagged as dev, your final runtime stage should use a non-dev image variant.

4. Install additional packages

   Ghost hardened images contain minimal packages in order to reduce the potential attack surface. You may need to install additional packages in your Dockerfile. To view if a package manager is available for an image variant, select the Tags tab for this repository. To view what packages are already installed in an image variant, select the Tags tab for this repository, and then select a tag.

   Only images tagged as dev typically have package managers. You should use a multi-stage Dockerfile to install the packages. Install the packages in the build stage that uses a dev image. Then, if needed, copy any necessary artifacts to the runtime stage that uses a non-dev image.

   For Alpine-based images, you can use apk to install packages. For Debian-based images, you can use apt-get to install packages.

Troubleshooting migration

The following are common issues that you may encounter during migration.

General debugging

The hardened images intended for runtime don't contain a shell nor any tools for debugging. The recommended method for debugging applications built with Ghost hardened images is to use Docker Debug to attach to these containers. Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

Permissions

By default image variants intended for runtime, run as a nonroot user. Ensure that necessary files and directories are accessible to that user. You may need to copy files to different directories or change permissions so your application running as a nonroot user can access them.

To view the user for an image variant, select the Tags tab for this repository.

Privileged ports

Non-dev hardened images run as a nonroot user by default. As a result, applications in these images can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. To avoid issues, configure your application to listen on port 1025 or higher inside the container, even if you map it to a lower port on the host. For example, docker run -p 80:8080 my-image will work because the port inside the container is 8080, and docker run -p 80:81 my-image won't work because the port inside the container is 81.

No shell

By default, image variants intended for runtime don't contain a shell. Use dev images in build stages to run shell commands and then copy any necessary artifacts into the runtime stage. In addition, use Docker Debug to debug containers with no shell.

To see if a shell is available in an image variant and which one, select the Tags tab for this repository.

Entry point

Ghost hardened images may have different entry points than images such as Docker Official Images.

To view the Entrypoint or CMD defined for an image variant, select the Tags tab for this repository, select a tag, and then select the Specifications tab.