resolveLocalDockerHost accepts only a Unix socket (unix://) or a Windows named pipe (npipe://): DOCKER_HOST when it’s set, and the current context’s endpoint, which must match it. A tcp:// endpoint is refused even on 127.0.0.1, because a forwarded port or a tunnel can reach another machine, and so is ssh://. Either throws DOCKER_ENDPOINT_NOT_LOCAL before the script sends anything to the daemon. runDocker passes the endpoint as --host first, so a docker context use between the check and a later command can’t send that command somewhere else.
Check that a Compose stack publishes its ports on loopback only:
ts
import { findPublicPorts, listComposeServices } from 'jg-local-docker';declare const host: string;for (const { service, url, publishedPort } of findPublicPorts( await listComposeServices({ cwd: '/srv/app', host }),)) { console.error(`${service} publishes port ${publishedPort} on ${url}`);}
findPublicPorts flags a port published on any address but 127.0.0.1 or ::1, such as both halves of a port on 0.0.0.0 and ::, and ignores a port only exposed to other containers. listComposeServices runs docker compose ps --format json, stopped containers included unless all is false, and parseComposePs reads that output when you run the command yourself, as one JSON object per line or one array.
Read one container’s state, labels, and published ports:
inspectContainer uses a fixed template that never reads the container’s environment, command, mounts, or logs, which can hold secrets. A label the container doesn’t have reads as null, and a container without a healthcheck has a null health.
Start a container a script owns, such as a test database, and remove it afterwards:
ts
import { randomUUID } from 'node:crypto';import { removeContainer, startContainer } from 'jg-local-docker';declare const host: string;const name = `app-test-redis-${randomUUID()}`;const labels = { 'app.test.nonce': randomUUID() };const redis = await startContainer({ host, name, labels, image: 'redis:8.6.2-alpine', ports: [6379],});// ... use 127.0.0.1 and redis.ports[0]?.hostPortawait removeContainer(name, { host, labels });
startContainer creates the container with its name, its labels, and each port published on a random port of 127.0.0.1, starts it, and reads it back: it must be the container created, with the name and every label, and publish each port exactly once on 127.0.0.1 and nothing else, or it throws DOCKER_CONTAINER_NOT_OWNED or DOCKER_PORTS_NOT_LOOPBACK. createArgs adds docker create arguments, such as ['--memory', '256m'], and command the arguments after the image. Any failure after the creation, an aborted signal included, removes the container before the error is thrown. removeContainer removes a container only when it has the exact name and every label given, so a random label, such as a nonce, proves it’s yours: it stops it, removes it with its anonymous volumes, and confirms it’s gone, resolving to false when there was none.
startOwnedContainer does the same through an owner process, which removes the container when release is called, when your process exits or crashes, and on SIGINT and SIGTERM, which Ctrl+C sends the whole process group:
ts
import { startOwnedContainer } from 'jg-local-docker';declare const host: string;const { container, release } = await startOwnedContainer({ host, name: 'app-test-redis', labels: { 'app.test.nonce': crypto.randomUUID() }, image: 'redis:8.6.2-alpine', ports: [6379],});// ... the testsawait release(); // removes the container, and waits for the owner to exit
The owner creates the container itself, so it knows the container’s ID from the first moment, and removes that container only. Use it in a test runner’s global setup, which may exit at once on Ctrl+C, so no run leaves a container behind. release throws DOCKER_OWNER_FAILED when the owner couldn’t confirm the removal.
Every command runs without a shell, within a 30-second timeout and a 64 KiB output limit unless you pass others, which reject with jg-process’s PROCESS_TIMED_OUT and PROCESS_OUTPUT_TOO_LARGE. runDocker resolves with any exit code; the other helpers throw DOCKER_COMMAND_FAILED on a non-zero one.
Errors
Code
When
DOCKER_NOT_FOUND
docker isn’t on the PATH
DOCKER_ENDPOINT_NOT_LOCAL
DOCKER_HOST or the current context names an endpoint that isn’t a Unix socket or a named pipe, or the two differ
DOCKER_COMMAND_FAILED
A helper’s command exits with another code than 0
DOCKER_OUTPUT_INVALID
Docker’s output isn’t in the expected format
DOCKER_CONTAINER_NOT_FOUND
The container inspectContainer reads doesn’t exist
DOCKER_INVALID_ARGUMENT
An argument isn’t valid, such as an empty endpoint, a working directory that doesn’t exist, or a service name that’s an option
DOCKER_CONTAINER_NOT_OWNED
The container removeContainer found, or startContainer started, doesn’t have the name and every label given
DOCKER_PORTS_NOT_LOOPBACK
A container startContainer started doesn’t publish each port exactly once on 127.0.0.1, such as when createArgs publishes another, or it stopped
DOCKER_OWNER_FAILED
startOwnedContainer’s owner process failed to start, or exited without confirming the container’s removal
DOCKER_ENDPOINT_NOT_LOCAL’s data says where the endpoint came from, DOCKER_HOST or context, never the endpoint, which can name a user. DOCKER_COMMAND_FAILED’s data holds the subcommand and the exit code, never stderr, because Compose’s diagnostics can quote the project’s configuration. jg-process’s PROCESS_START_FAILED, PROCESS_TIMED_OUT, PROCESS_OUTPUT_TOO_LARGE, and PROCESS_TREE_SURVIVED pass through, and an aborted signal rejects with its reason.
Generated from TSDoc
API reference
Every export of [email protected], 25 in all, with its signature, its errors, and an example.
Finds the ports services publish on an address other than 127.0.0.1 or ::1, which another machine may reach, such as 0.0.0.0 or ::. A port that's only exposed to other containers isn't published, so it's left out.
Reads a container's ID, name, state, health, the labels asked for, and its published ports, with docker inspect and a fixed template that never reads its environment, command, mounts, or logs.
Checks whether a Docker endpoint is on this machine: a Unix socket (unix://) or a Windows named pipe (npipe://). A tcp:// or an ssh:// endpoint isn't, even on 127.0.0.1, because a forwarded port or a tunnel can reach another machine.
Signature
isLocalDockerEndpoint(host: unknown): host is string
Parses docker compose ps --format json output: one JSON object per line, as current Compose writes it, or a single JSON array, with LF or CRLF line ends. Empty output is no services. Entries keep Compose's order, duplicates included, so a caller can tell a service that runs twice.
Signature
parseComposePs(stdout: string): IComposeService[]
Parameters
stdoutstring
The command's stdout.
Returns
IComposeService[]
The services.
Throws
DOCKER_OUTPUT_INVALIDDocker's output isn't in the expected format.
Removes a container only when it has the exact name and every label given, such as one startContainer started: it stops it, removes it by ID with its anonymous volumes, and confirms it's gone. A container with that name but other labels, or found by an ID that starts with the name, is refused, so a name another program reuses is never removed.
Resolves the Docker endpoint the docker command would use, and checks that it's on this machine: DOCKER_HOST, when it's set, and the current context's endpoint, which must match it. Pass the result as host to every later command, so a context switch can't redirect them.
Runs a docker command without a shell, within a timeout and an output limit. With host, it passes --host first, so the command goes to that endpoint even when the current context changes after the endpoint was checked. It resolves with the exit code, whatever it is, and the output decoded as UTF-8; a timeout or too much output rejects as jg-process's runProcess does.
Creates a container, starts it, and reads it back with inspectContainer: it must be the one created, with the name and every label asked for, and publish each port exactly once, on a random port of 127.0.0.1, and nothing else. Any failure after the creation, an abort included, removes the container by its ID before the error is thrown. Labels such as a random nonce are what removeContainer later checks, so the container can't be confused with another of the same name.
Starts a container as startContainer does, through an owner process that removes it when this process disconnects from it: when release is called, when this process exits or crashes, or when it's interrupted. The owner creates the container itself, so it knows its ID from the first moment, and it handles SIGINT and SIGTERM, which Ctrl+C sends the whole process group, by removing the container before it exits. Use it for a container that must not outlive a test run, such as in a test runner's global setup, which may exit at once on Ctrl+C.
type IRunDockerOptions = { host?: string | undefined; cwd?: string | undefined; env?: NodeJS.ProcessEnv | undefined; timeoutSeconds?: number | undefined; maxOutputBytes?: number | undefined; signal?: AbortSignal | undefined;};
Members
hostproperty
string
the Docker endpoint every command goes to, passed as --host, such as the one resolveLocalDockerHost gives. Without it, Docker uses DOCKER_HOST or the current context
cwdproperty
string
the directory docker runs in, such as a Compose project's
envproperty
NodeJS.ProcessEnv
the environment docker runs with. Defaults to process.env
timeoutSecondsproperty
number
the seconds the command may run before it's stopped. Defaults to 30
maxOutputBytesproperty
number
the bytes stdout and stderr may hold together. Defaults to 64 KiB