Skip to main content
jg-packages

Search

    Patterns for development scripts and test setups that use the Docker on the developer’s own machine, and must never act on another one.

    Refusing to run against a remote Docker

    Use this in a script that destroys local state, such as one that resets the app’s development database by removing its volumes. A developer whose shell still points at a shared build server, through DOCKER_HOST or a docker context use they forgot, would wipe that server’s volumes instead, so the script checks the endpoint first and sends every command to the one it checked:

    ts
    import { ERRORS, resolveLocalDockerHost, runDocker } from 'jg-local-docker';
    import { hasErrorCode } from 'jg-exception';
    
    // the directory of the Compose project that runs the app's development database
    declare const projectDirectory: string;
    
    /**
     * Resolves the local endpoint, or explains what to change when Docker points elsewhere.
     */
    const resolveHostOrExplain = async (): Promise<string> => {
      try {
        return await resolveLocalDockerHost({ timeoutSeconds: 10 });
      } catch (error) {
        if (hasErrorCode(error, ERRORS.DOCKER_ENDPOINT_NOT_LOCAL)) {
          throw new Error(
            'Docker points at another machine. Unset DOCKER_HOST, or run `docker context use default`.',
            { cause: error },
          );
        }
        throw error;
      }
    };
    
    export const resetDevelopmentDatabase = async (): Promise<void> => {
      const host = await resolveHostOrExplain();
    
      // both commands go to the endpoint just checked, even if the context changes meanwhile
      for (const args of [
        ['compose', 'down', '--volumes', '--remove-orphans'],
        ['compose', 'up', '--detach', '--wait'],
      ]) {
        const { exitCode } = await runDocker(args, {
          host,
          cwd: projectDirectory,
          timeoutSeconds: 300,
        });
        if (exitCode !== 0) {
          throw new Error(`docker ${args.join(' ')} exited with ${exitCode}.`);
        }
      }
    };

    resolveLocalDockerHost refuses a tcp:// endpoint even on 127.0.0.1, because a forwarded port or an SSH tunnel can reach another machine, and only a Unix socket or a named pipe proves the daemon is local. Its error says whether DOCKER_HOST or the context was the problem, without the endpoint itself, which can name a user. runDocker resolves with the exit code rather than throwing, so the script decides what a failure means; a command that hangs, such as an image pull on a broken network, stops at timeoutSeconds.

    Checking a Compose stack before tests

    Use this in a test suite’s global setup, when the tests need services that a developer starts with docker compose up: each one must run exactly once, be healthy when it has a healthcheck, and publish its port on loopback only, so a test never talks to a stale second container or exposes a database to the network:

    ts
    import { findPublicPorts, listComposeServices, resolveLocalDockerHost } from 'jg-local-docker';
    
    // the services the tests connect to, and the directory of their Compose project
    const REQUIRED_SERVICES = ['db', 'cache'];
    declare const projectDirectory: string;
    
    // the host port each service publishes, for the tests' connection strings
    export const checkTestStack = async (): Promise<Map<string, number>> => {
      const host = await resolveLocalDockerHost();
      const services = await listComposeServices({
        cwd: projectDirectory,
        host,
        services: REQUIRED_SERVICES,
      });
    
      const problems: string[] = [];
      const ports = new Map<string, number>();
      for (const name of REQUIRED_SERVICES) {
        const [container, ...others] = services.filter(({ service }) => service === name);
        if (container === undefined || others.length > 0) {
          problems.push(
            `${name} has ${others.length + (container === undefined ? 0 : 1)} containers, not 1`,
          );
        } else if (container.state !== 'running' || !['', 'healthy'].includes(container.health)) {
          problems.push(
            `${name} is ${container.state}${container.health === '' ? '' : `, ${container.health}`}`,
          );
        } else {
          const published = container.publishers.find(({ publishedPort }) => publishedPort !== 0);
          if (published === undefined) {
            problems.push(`${name} publishes no port`);
          } else {
            ports.set(name, published.publishedPort);
          }
        }
      }
      for (const { service, url, publishedPort } of findPublicPorts(services)) {
        problems.push(`${service} publishes port ${publishedPort} on ${url}, not on 127.0.0.1`);
      }
    
      if (problems.length > 0) {
        throw new Error(
          `The test stack isn't ready: ${problems.join('; ')}. Run docker compose up --wait.`,
        );
      }
      return ports;
    };

    listComposeServices lists stopped containers too, so a service that crashed shows up as exited instead of disappearing, and health is '' for a service without a healthcheck. A Compose file that publishes 6379:6379 without an address binds every interface, 0.0.0.0 and ::, which findPublicPorts reports as two ports; write 127.0.0.1:6379:6379 instead.

    A container for one test run

    A test runner’s global setup that starts Redis for the run and removes it afterwards, even when the run is stopped with Ctrl+C, which can end the runner before its teardown:

    ts
    import { randomUUID } from 'node:crypto';
    import { resolveLocalDockerHost, startOwnedContainer } from 'jg-local-docker';
    
    // what the setup hands the tests: where Redis listens
    declare const provide: (key: 'redisUrl', value: string) => void;
    
    export default async function setup(): Promise<() => Promise<void>> {
      const host = await resolveLocalDockerHost();
      const { container, release } = await startOwnedContainer({
        host,
        name: `app-test-redis-${randomUUID()}`,
        labels: { 'app.test.run': randomUUID() },
        image: 'redis:8.6.2-alpine',
        ports: [6379],
        createArgs: ['--memory', '256m'],
      });
      provide('redisUrl', `redis://127.0.0.1:${String(container.ports[0]?.hostPort)}`);
      return release;
    }

    The container’s random name lets several runs share one machine, and its random label is the proof removeContainer would check. The owner process outlives the runner: when the runner exits, crashes, or is interrupted, the owner still removes the container, and release in the teardown removes it on a normal finish.