Add structured logging and auto-detect Podman runtime

Add a structured logger with BERG_VERBOSE support to replace all
console.log calls. Debug messages are hidden by default, shown
only when BERG_VERBOSE=true. Auto-detect Podman socket and
configure DOCKER_HOST and TESTCONTAINERS_RYUK_DISABLED so users
no longer need to set them manually. Compatible with Docker
(no-op when Docker is detected).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kstekovi

README.md

@@ -28,11 +28,9 @@ Following tools are required to run the test suite
   - recommended version is 22.
   - [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) is recommended optional tool to install & manage multiple Node environments
 - [npx](https://github.com/npm/npx) CLI tool used to exeute binaries from project's `node_modules` directly (instead of providing absolute/relative path to the commannds). It is used in multiple build steps.
-- [Podman](https://podman.io) | [Docker](https://www.docker.com) as a container runtime used by TestContainers. Note that when using Podman as container runtime you may need to export following environment variables and start podman socket:
+- [Podman](https://podman.io) | [Docker](https://www.docker.com) as a container runtime used by TestContainers. Podman is auto-detected: `DOCKER_HOST`, `TESTCONTAINERS_RYUK_DISABLED`, and `podman.socket` are configured automatically. To override, set the environment variables manually before running the test suite:
   - `export TESTCONTAINERS_RYUK_DISABLED=true`
   - `export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock`
-    - the path can be found by command `podman info --debug` and look for `path` in `remoteSocket` section.
-  - `systemctl --user start podman.socket`
 - Java. Yes we'll need Java to write deployments/applications that will be deployed onto the running WildFly container.
 - [Maven](https://maven.apache.org). Yes, we'll need Maven to ease up the development of the deployed applications & downloading needed JDBC drivers for datasource & drivers UI tests. Maven is mostly used embedded by [node-maven](https://github.com/headcr4sh/node-maven) JS wrapper to execute Maven & Java related tasks into the build automation.
 
@@ -96,6 +94,7 @@ Following is a table of supported environment properties that can be used when r
 | `MYSQL_IMAGE`    | `docker.io/library/mysql:latest`                | MySQL image to be used for datasource tests                                                   |
 | `MARIADB_IMAGE`  | `docker.io/library/mariadb:latest`              | MariaDB image to be used for datasource tests                                                 |
 | `MSSQL_IMAGE`    | `mcr.microsoft.com/mssql/server:2022-latest`    | Microsoft SQL Server image to be used for datasource tests                                    |
+| `BERG_VERBOSE`   | `false`                                         | Enable verbose Berg logging (debug messages for container setup, CLI commands, etc.)          |
 
 ## Custom method documentation
 

config/containers/database.ts

@@ -1,6 +1,6 @@
 import { PullPolicy, GenericContainer, StartedTestContainer, Wait } from "testcontainers";
 import { DatabaseConfig } from "../interfaces";
-import { handleContainerError } from "../helpers";
+import { handleContainerError, logger } from "../helpers";
 
 export function startDatabaseContainer(
   config: DatabaseConfig,
@@ -18,7 +18,7 @@ export function startDatabaseContainer(
   return containerBuilder
     .start()
     .then((container) => {
-      console.log(config.successMessage);
+      logger.debug(config.successMessage);
       startedContainersMap.set(config.containerMapKey, container);
       return container;
     })

config/containers/wildfly.ts

@@ -11,7 +11,7 @@ import {
   MANAGEMENT_INTERFACE_ADDRESS,
 } from "../../cypress.config";
 import { WildflyManagementResponse } from "../interfaces";
-import { buildLocalhostUrl } from "../helpers";
+import { buildLocalhostUrl, logger } from "../helpers";
 
 export function pollWildflyState(managementApi: string, container: StartedTestContainer): Promise<string> {
   const startTime = new Date().getTime();
@@ -34,7 +34,7 @@ export function pollWildflyState(managementApi: string, container: StartedTestCo
           }
         })
         .catch(() => {
-          console.log("WildFly server is not ready yet");
+          logger.debug("WildFly server is not ready yet");
         });
     }, WILDFLY_POLL_INTERVAL_MS);
   });
@@ -61,7 +61,7 @@ export function configureWildflyNetworkMode(
   networkName?: string,
 ): Promise<{ portOffset: number }> {
   if (useHostMode) {
-    console.log("host mode");
+    logger.debug("host mode");
     return findAPortNotInUse(WILDFLY_PORT_RANGE.min, WILDFLY_PORT_RANGE.max).then((freePort) => {
       const portOffset = freePort - WILDFLY_PORT_RANGE.min;
       wildfly
@@ -75,7 +75,7 @@ export function configureWildflyNetworkMode(
       return { portOffset };
     });
   } else {
-    console.log(`default network mode, network name: ${networkName}`);
+    logger.debug(`default network mode, network name: ${networkName}`);
     wildfly
       .withNetworkMode(networkName!)
       .withNetworkAliases("wildfly")

config/helpers/container-runtime.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "fs";
+import { execSync } from "child_process";
+import os from "os";
+import { logger } from "./logger";
+
+function isPodmanSocket(dockerHost: string): boolean {
+  return dockerHost.includes("podman");
+}
+
+function configurePodman(): void {
+  if (!process.env.TESTCONTAINERS_RYUK_DISABLED) {
+    process.env.TESTCONTAINERS_RYUK_DISABLED = "true";
+  }
+}
+
+function detectContainerRuntime(): void {
+  if (process.env.DOCKER_HOST) {
+    if (isPodmanSocket(process.env.DOCKER_HOST)) {
+      configurePodman();
+      logger.info(`DOCKER_HOST points to Podman (${process.env.DOCKER_HOST}), configured TESTCONTAINERS_RYUK_DISABLED`);
+    } else {
+      logger.debug(`DOCKER_HOST already set to "${process.env.DOCKER_HOST}"`);
+    }
+    return;
+  }
+
+  const uid = os.userInfo().uid;
+  const podmanSocketPaths = [`/run/user/${uid}/podman/podman.sock`, "/var/run/podman/podman.sock"];
+
+  for (const socketPath of podmanSocketPaths) {
+    if (!existsSync(socketPath)) {
+      try {
+        execSync("systemctl --user start podman.socket", { stdio: "ignore" });
+      } catch {
+        continue;
+      }
+    }
+
+    if (existsSync(socketPath)) {
+      process.env.DOCKER_HOST = `unix://${socketPath}`;
+      configurePodman();
+      logger.info(`Detected Podman runtime at ${socketPath}, configured DOCKER_HOST and TESTCONTAINERS_RYUK_DISABLED`);
+      return;
+    }
+  }
+
+  if (existsSync("/var/run/docker.sock")) {
+    logger.debug("Detected Docker runtime");
+    return;
+  }
+
+  logger.debug("No container runtime detected automatically");
+}
+
+detectContainerRuntime();

config/helpers/error-handler.ts

@@ -1,4 +1,6 @@
+import { logger } from "./logger";
+
 export function handleContainerError(err: unknown): Error {
-  console.log(err);
+  logger.error(err);
   return err instanceof Error ? err : new Error(JSON.stringify(err));
 }

config/helpers/index.ts

@@ -1,3 +1,4 @@
 export * from "./error-handler";
 export * from "./url-builder";
 export * from "./container-helpers";
+export * from "./logger";

config/helpers/logger.ts

@@ -0,0 +1,9 @@
+const isVerbose = process.env.BERG_VERBOSE === "true";
+
+export const logger = {
+  error: (...args: unknown[]) => console.error("[berg]", ...args),
+  info: (...args: unknown[]) => console.log("[berg]", ...args),
+  debug: (...args: unknown[]) => {
+    if (isVerbose) console.log("[berg:debug]", ...args);
+  },
+};

config/tasks/cli-tasks.ts

@@ -1,5 +1,6 @@
 import axios from "axios";
 import { ExecuteCliParams, AxiosErrorResponse } from "../interfaces";
+import { logger } from "../helpers";
 
 export function createExecuteCli() {
   return ({ managementApi, operation, address, ...args }: ExecuteCliParams) => {
@@ -11,7 +12,7 @@ export function createExecuteCli() {
       })
       .then((response) => response.data as unknown)
       .catch((err: AxiosErrorResponse) => {
-        console.log(err);
+        logger.error(err);
         throw new Error(err.response.data);
       });
   };

config/tasks/keycloak-tasks.ts

@@ -9,7 +9,7 @@ import {
   FIXTURES_PATH,
 } from "../../cypress.config";
 import { StartKeycloakContainerParams } from "../interfaces";
-import { buildLocalhostUrl, buildKeycloakStartCommand, handleContainerError } from "../helpers";
+import { buildLocalhostUrl, buildKeycloakStartCommand, handleContainerError, logger } from "../helpers";
 
 export function createKeycloakContainer(startedContainers: Map<string, StartedTestContainer>) {
   return ({ name }: StartKeycloakContainerParams) => {
@@ -35,7 +35,7 @@ export function createKeycloakContainer(startedContainers: Map<string, StartedTe
         .then((keycloakContainer) => {
           startedContainers.set(name, keycloakContainer);
           const keycloakServer = buildLocalhostUrl(freePort);
-          console.log(`Keycloak is ready: ${keycloakServer}`);
+          logger.info(`Keycloak is ready: ${keycloakServer}`);
           return keycloakServer;
         })
         .catch((err: unknown) => {

config/tasks/wildfly-tasks.ts

@@ -9,7 +9,7 @@ import {
   JBOSS_CLI_PATH,
 } from "../../cypress.config";
 import { StartWildflyContainerParams, ExecuteInContainerParams, AxiosErrorResponse } from "../interfaces";
-import { getHostnameMapping, handleContainerError, calculateManagementPort } from "../helpers";
+import { getHostnameMapping, handleContainerError, calculateManagementPort, logger } from "../helpers";
 import { configureWildflyNetworkMode, configureWildflyPostStart } from "../containers";
 
 export function createWildflyContainer(
@@ -53,7 +53,7 @@ export function createWildflyContainer(
         );
       })
       .then((wildflyServer) => {
-        console.log(`WildFly server is ready: ${wildflyServer}`);
+        logger.info(`WildFly server is ready: ${wildflyServer}`);
         return wildflyServer;
       })
       .catch((err: unknown) => {
@@ -67,7 +67,7 @@ export function createExecuteInContainer(
   startedContainersManagementPorts: Map<string, number>,
 ) {
   return ({ containerName, command }: ExecuteInContainerParams) => {
-    console.log(`CLI commands: ${command}`);
+    logger.debug(`CLI commands: ${command}`);
     const containerToExec = startedContainers.get(containerName);
     let managementPort = startedContainersManagementPorts.get(containerName);
     managementPort = managementPort ?? WILDFLY_MANAGEMENT_PORT;
@@ -86,7 +86,7 @@ export function createExecuteInContainer(
         if (value.exitCode === 0) {
           return value;
         } else {
-          console.log(value);
+          logger.debug(value);
           throw new Error(`Command failed with exit code ${value.exitCode}: ${value.output || ""}`);
         }
       })