Skip to main content

Docker Functions

Utah provides Docker integration functions for container and image management directly from your shell scripts.

Available Functions​

Container Management​

FunctionReturnsDescription
docker.run(image, name?, ports?, volumes?)stringRun a container in detached mode
docker.stop(container)voidStop a running container
docker.remove(container)voidRemove a container
docker.restart(container)voidRestart a container
docker.logs(container)stringGet container logs
docker.exec(container, command)stringExecute a command in a running container
docker.isRunning(container)booleanCheck if a container is running
docker.list()stringList running container names

Image Management​

FunctionReturnsDescription
docker.build(tag, path?)stringBuild an image from a Dockerfile
docker.pull(image)voidPull an image from registry
docker.push(image)voidPush an image to registry
docker.removeImage(image)voidRemove a Docker image
docker.imageExists(image)booleanCheck if an image exists locally

Container Management​

docker.run()​

Runs a Docker container in detached mode. Returns the container ID.

// Run with just an image
docker.run("nginx");

// Run with a name
docker.run("nginx", "my-nginx");

// Run with name and port mapping
docker.run("nginx", "web-server", "8080:80");

// Run with all options
docker.run("nginx", "full-server", "8080:80", "/data:/usr/share/nginx/html");

// Capture the container ID
let containerId: string = docker.run("redis", "my-redis");
console.log("Started container: ${containerId}");

Generated Bash:

# docker.run("nginx") becomes:
docker run -d nginx

# docker.run("nginx", "web-server", "8080:80") becomes:
docker run -d --name web-server -p 8080:80 nginx

# docker.run("nginx", "full-server", "8080:80", "/data:/usr/share/nginx/html") becomes:
docker run -d --name full-server -p 8080:80 -v /data:/usr/share/nginx/html nginx

Test Coverage:

  • File: tests/positive_fixtures/docker_run.shx
  • Tests all parameter combinations including variable capture

docker.stop()​

Stops a running container.

// Stop by name
docker.stop("my-nginx");

// Stop using a variable
let container: string = "web-server";
docker.stop(container);

Generated Bash:

# docker.stop("my-nginx") becomes:
docker stop "my-nginx"

# docker.stop(container) with a variable becomes:
docker stop ${container}

Test Coverage:

  • File: tests/positive_fixtures/docker_stop_remove.shx

docker.remove()​

Removes a container.

// Remove by name
docker.remove("my-nginx");

// Stop then remove
docker.stop("web-server");
docker.remove("web-server");

Generated Bash:

# docker.remove("my-nginx") becomes:
docker rm "my-nginx"

Test Coverage:

  • File: tests/positive_fixtures/docker_stop_remove.shx

docker.restart()​

Restarts a container.

docker.restart("my-nginx");

let container: string = "web-server";
docker.restart(container);

Generated Bash:

# docker.restart("my-nginx") becomes:
docker restart "my-nginx"

Test Coverage:

  • File: tests/positive_fixtures/docker_restart.shx

docker.logs()​

Returns the logs of a container as a string.

let output: string = docker.logs("my-nginx");
console.log("Logs: ${output}");

let container: string = "web-server";
let logs: string = docker.logs(container);

Generated Bash:

# docker.logs("my-nginx") becomes:
output=$(docker logs "my-nginx")

Test Coverage:

  • File: tests/positive_fixtures/docker_logs.shx

docker.exec()​

Executes a command inside a running container and returns the output.

let result: string = docker.exec("my-nginx", "ls /usr/share/nginx/html");
console.log("Files: ${result}");

let container: string = "web-server";
docker.exec(container, "nginx -s reload");

Generated Bash:

# docker.exec("my-nginx", "ls /usr/share/nginx/html") becomes:
result=$(docker exec "my-nginx" ls /usr/share/nginx/html)

Test Coverage:

  • File: tests/positive_fixtures/docker_exec.shx

docker.isRunning()​

Returns a boolean indicating whether a container is currently running.

let running: boolean = docker.isRunning("my-nginx");

if (running) {
  console.log("Container is running");
} else {
  console.log("Container is not running");
}

Generated Bash:

# docker.isRunning("my-nginx") becomes:
running=$(docker inspect -f '{{.State.Running}}' "my-nginx" 2>/dev/null || echo "false")

# In an if condition:
if [ "${running}" = "true" ]; then
  echo "Container is running"
fi

Test Coverage:

  • File: tests/positive_fixtures/docker_is_running.shx

docker.list()​

Returns the names of all running containers.

let containers: string = docker.list();
console.log("Running containers: ${containers}");

Generated Bash:

# docker.list() becomes:
containers=$(docker ps --format '{{.Names}}')

Test Coverage:

  • File: tests/positive_fixtures/docker_list.shx

Image Management​

docker.build()​

Builds a Docker image from a Dockerfile. Defaults to the current directory if no path is specified.

// Build with tag (uses current directory)
docker.build("myapp:latest");

// Build with tag and path
docker.build("myapp:v2", "./app");

// Capture build output
let result: string = docker.build("myapp:v3");

Generated Bash:

# docker.build("myapp:latest") becomes:
docker build -t "myapp:latest" .

# docker.build("myapp:v2", "./app") becomes:
docker build -t "myapp:v2" "./app"

Test Coverage:

  • File: tests/positive_fixtures/docker_build.shx

docker.pull()​

Pulls a Docker image from a registry.

docker.pull("nginx:latest");

let image: string = "redis:alpine";
docker.pull(image);

Generated Bash:

# docker.pull("nginx:latest") becomes:
docker pull "nginx:latest"

Test Coverage:

  • File: tests/positive_fixtures/docker_pull_push.shx

docker.push()​

Pushes a Docker image to a registry.

docker.push("myregistry/myapp:latest");

Generated Bash:

# docker.push("myregistry/myapp:latest") becomes:
docker push "myregistry/myapp:latest"

Test Coverage:

  • File: tests/positive_fixtures/docker_pull_push.shx

docker.removeImage()​

Removes a Docker image from the local system.

docker.removeImage("nginx:latest");

Generated Bash:

# docker.removeImage("nginx:latest") becomes:
docker rmi "nginx:latest"

Test Coverage:

  • File: tests/positive_fixtures/docker_image_management.shx

docker.imageExists()​

Returns a boolean indicating whether a Docker image exists locally.

let exists: boolean = docker.imageExists("nginx:latest");

if (exists) {
  console.log("Image exists");
  docker.removeImage("nginx:latest");
} else {
  console.log("Image not found");
}

Generated Bash:

# docker.imageExists("nginx:latest") becomes:
exists=$(docker image inspect "nginx:latest" > /dev/null 2>&1 && echo "true" || echo "false")

Test Coverage:

  • File: tests/positive_fixtures/docker_image_management.shx

Practical Examples​

Deploy a Web Application​

let imageName: string = "myapp:latest";

// Build the image
docker.build(imageName);

// Stop and remove old container if running
let running: boolean = docker.isRunning("myapp");
if (running) {
  docker.stop("myapp");
  docker.remove("myapp");
}

// Run the new container
docker.run(imageName, "myapp", "3000:3000");
console.log("Application deployed successfully");

Container Health Check​

let containers: string[] = ["web", "api", "db"];

for (let name: string in containers) {
  let running: boolean = docker.isRunning(name);
  if (running) {
    console.log("✓ ${name} is running");
  } else {
    console.log("✗ ${name} is NOT running");
    docker.restart(name);
    console.log("  Restarted ${name}");
  }
}

CI/CD Pipeline​

let version: string = "1.0.0";
let registry: string = "myregistry.io";

// Build
docker.build("${registry}/myapp:${version}");

// Push to registry
docker.push("${registry}/myapp:${version}");

console.log("Published ${registry}/myapp:${version}");