in-container is a utility for determining whether the current process is running inside a container, supporting both Docker and Podman environments. This lightweight package offers zero dependencies, enhancing its usability in various projects without overhead.

Key Features

• Library and CLI Usage: in-container can seamlessly be used as both a library and a command-line interface (CLI), providing flexibility based on user needs.
• Asynchronous and Synchronous Options: The library caters to different programming styles with both asynchronous and synchronous method implementations.
• Cross-Platform Support: Designed to return false on platforms lacking container-specific paths, such as Windows or macOS, thus ensuring compatibility across environments.

Requirements

To utilize this package as a library, ensure you have Node.js version 14.18.0 or higher. For CLI functionalities, Node.js versions 16.17.0 (excluding 17.0.0) or 18.3.0 and above are required.

Installation

To install in-container, use the following command:

npm install in-container

Usage Examples

For seamless integration into applications, the library provides easy-to-follow usage examples:

Asynchronous Check

import { inContainer } from 'in-container/async';

if (await inContainer()) {
    console.log('Running inside a container');
}

Synchronous Check

import { inContainer } from 'in-container/sync';

if (inContainer()) {
    console.log('Running inside a container');
}

For direct usability from the package root:

import { inContainerAsync, inContainerSync } from 'in-container';

API Overview

• inDocker(): Check if the process is within a Docker container, identifying through specific filesystem paths or cgroup segments.
• inPodman(): Verify if the process runs within a Podman container, utilizing distinct environmental markers for detection.
• inContainer(): Combines the functionality of Docker and Podman checks, offering a straightforward method to determine container runtime presence.

Command-Line Interface

The package also features a CLI that can be run as:

npx in-container

The command outputs results in JSON format, providing insights into the container environment:

$ in-container
{"container":true,"docker":true,"podman":false}

Use the --quiet option to restrict output to only the exit code, facilitating script usage:

if in-container --quiet; then
    echo 'Running inside a container'
fi

Limitations

While in-container effectively detects Docker and Podman, it’s important to note that:

• This method of detection is heuristic and may not account for other container runtimes like containerd or CRI-O.
• Running Docker Desktop on macOS or Windows typically results in processes executing on the host, yielding false for container checks.
• The signals used for detection can be manipulable; therefore, this package should not be relied upon for security enforcement.

With in-container, developers gain a precise and efficient solution for container detection, enhancing the robustness of their applications.