biolockj.util

Class DockerUtil

java.lang.Object

biolockj.util.DockerUtil

public class DockerUtil
extends Object

DockerUtil for Docker integration.

Field Summary

Fields

Modifier and Type	Field and Description
static String	AWS_EC2_HOME Docker container dir to map HOST $HOME to save logs + find Config values using $HOME: "/home/ec2-user" Need to name this dir = "/home/ec2-user" so Nextflow config is same inside + outside of container
static String	CONTAINER_BLJ_DIR Docker container blj dir: "/app/biolockj"
static String	CONTAINER_ID_KEY
static String	DEFAULT_DOCKER_MAPPER
static String	DEFAULT_IMAGE_NAME A light-weight docker image to use.
static String	DEFAULT_IMAGE_OWNER
static String	DEFAULT_IMAGE_TAG
static String	DOCKER_BLJ_MOUNT_DIR Docker container root user EFS directory: /mnt/efs
static String	DOCKER_DB_DIR Docker container root user DB directory: /mnt/efs/db
static String	DOCKER_DEFAULT_DB_DIR Docker container root user DB directory: /mnt/efs/db
static String	DOCKER_HUB_USER Config String property: "docker.imageOwner" Docker Hub URL: https://hub.docker.com By default the "biolockj" user is used to pull the standard modules, but advanced users can deploy their own versions of these modules and add new modules in their own Docker Hub account.
static String	DOCKER_IMG Config String property: "docker.imageName"
static String	DOCKER_IMG_VERSION Config String property: "docker.imageTag"
static String	DOCKER_MOUNT_SOCK Config Boolean property: "docker.mountSock"
static String	DOCKER_PIPELINE_DIR All containers mount "internal.pipelineDir" to the container volume: /mnt/efs/output
static String	DOCKER_USER Docker container default $USER: "root"
static String	PURE_DOCKER_PIPELINE_DIR When running in pure docker to do the initial setup, use this pipelines dir: "/workspace/pipelines"
static String	ROOT_HOME Docker container root user $HOME directory: /root
(package private) static String	SAVE_CONTAINER_ON_EXIT Config Boolean property: "docker.saveContainerOnExit"
(package private) static String	SPAWN_DOCKER_CONTAINER Name of the bash script function used to generate a new Docker container: "spawnDockerContainer"

Constructor Summary

Constructors

Constructor and Description
DockerUtil()

Method Summary

Modifier and Type	Method and Description
static List<String>	buildSpawnDockerContainerFunction(BioModule module, String startedFlag) Build the "spawnDockerContainer" method, which takes container name, in/out port, and optionally script path parameters.
static void	checkDependencies(BioModule module)
static File	containerizePath(File file) containerizePath(String)
static String	containerizePath(String path) If running in docker mode, convert this path to the form that can be used inside the docker container.
static File	deContainerizePath(File innerFile) deContainerizePath(String)
static String	deContainerizePath(String innerPath) If running in docker mode, convert this path to the form that can be used on the host machine.
static Long	downloadDB(String[] args, String label) Download a database for a Docker container
static String	getContainerId() Deprecated.
static String	getDockerImage(BioModule module) Return the name of the Docker image needed for the given module.
static File	getDockerVolumePath(String path, String containerPath) Get Docker file path through mapped volume
static String	getHostName()
static String	getMainDockerImage()
static DockerMountMapper	getMapper(boolean initAsNeeded) Intended for diagnostic purposes only.
static String	getVersionAsTag() Get the docker image tag that represents the current BioLockJ version.
static boolean	inAwsEnv() Return TRUE if running in AWS (based on Config props).
static boolean	inDockerEnv() Check runtime env for /.dockerenv
static boolean	isLocalImage(BioModule module, String image)
static ArrayList<String>	listProps() Let modules see property names.
static void	main(String[] args) Even outside of a BioLockJ instance, access the containerize() and decontainerze() methods.
static void	makeMapper() As version v1.3.18, the logic to do this mapping is not part of the DockerUtil class.
static void	registerProps() Register properties with the Properties class for API access.
static void	touchDockerInfo() Save a file with info about the current docker container.
static boolean	workerContainerStopped(File mainStarted, File workerScript)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AWS_EC2_HOME

public static final String AWS_EC2_HOME

Docker container dir to map HOST $HOME to save logs + find Config values using $HOME: "/home/ec2-user" Need to name this dir = "/home/ec2-user" so Nextflow config is same inside + outside of container

See Also:

Constant Field Values

DOCKER_BLJ_MOUNT_DIR

public static final String DOCKER_BLJ_MOUNT_DIR

Docker container root user EFS directory: /mnt/efs

See Also:

Constant Field Values

DOCKER_DB_DIR

public static final String DOCKER_DB_DIR

Docker container root user DB directory: /mnt/efs/db

See Also:

Constant Field Values

DOCKER_DEFAULT_DB_DIR

public static final String DOCKER_DEFAULT_DB_DIR

Docker container root user DB directory: /mnt/efs/db

See Also:

Constant Field Values

DOCKER_PIPELINE_DIR

public static final String DOCKER_PIPELINE_DIR

All containers mount "internal.pipelineDir" to the container volume: /mnt/efs/output

See Also:

Constant Field Values

PURE_DOCKER_PIPELINE_DIR

public static final String PURE_DOCKER_PIPELINE_DIR

When running in pure docker to do the initial setup, use this pipelines dir: "/workspace/pipelines"

See Also:

Constant Field Values

DOCKER_USER

public static final String DOCKER_USER

Docker container default $USER: "root"

See Also:

Constant Field Values

ROOT_HOME

public static final String ROOT_HOME

Docker container root user $HOME directory: /root

CONTAINER_BLJ_DIR

public static final String CONTAINER_BLJ_DIR

Docker container blj dir: "/app/biolockj"

See Also:

Constant Field Values

DOCKER_IMG_VERSION

public static final String DOCKER_IMG_VERSION

Config String property: "docker.imageTag"

See Also:

Constant Field Values

DOCKER_MOUNT_SOCK

public static final String DOCKER_MOUNT_SOCK

Config Boolean property: "docker.mountSock"

See Also:

Constant Field Values

SAVE_CONTAINER_ON_EXIT

static final String SAVE_CONTAINER_ON_EXIT

Config Boolean property: "docker.saveContainerOnExit"

See Also:

Constant Field Values

SPAWN_DOCKER_CONTAINER

static final String SPAWN_DOCKER_CONTAINER

Name of the bash script function used to generate a new Docker container: "spawnDockerContainer"

See Also:

Constant Field Values

DOCKER_IMG

public static final String DOCKER_IMG

Config String property: "docker.imageName"

See Also:

Constant Field Values

DOCKER_HUB_USER

public static final String DOCKER_HUB_USER

Config String property: "docker.imageOwner"

Docker Hub URL: https://hub.docker.com
By default the "biolockj" user is used to pull the standard modules, but advanced users can deploy their own versions of these modules and add new modules in their own Docker Hub account.

See Also:

Constant Field Values

CONTAINER_ID_KEY

public static final String CONTAINER_ID_KEY

See Also:

Constant Field Values

DEFAULT_DOCKER_MAPPER

public static final String DEFAULT_DOCKER_MAPPER

See Also:

Constant Field Values

DEFAULT_IMAGE_OWNER

public static final String DEFAULT_IMAGE_OWNER

See Also:

Constant Field Values

DEFAULT_IMAGE_NAME

public static final String DEFAULT_IMAGE_NAME

A light-weight docker image to use.

See Also:

Constant Field Values

DEFAULT_IMAGE_TAG

public static final String DEFAULT_IMAGE_TAG

See Also:

Constant Field Values

Constructor Detail

DockerUtil

public DockerUtil()

Method Detail

buildSpawnDockerContainerFunction

public static List<String> buildSpawnDockerContainerFunction(BioModule module,
                                                             String startedFlag)
                                                      throws ConfigException,
                                                             DockerVolCreationException

Build the "spawnDockerContainer" method, which takes container name, in/out port, and optionally script path parameters.

Parameters:

module - BioModule

Returns:

Bash function to run docker

Throws:

ConfigNotFoundException - If required Config properties are undefined

ConfigViolationException - If "exe.docker" property name does not start with prefix "exe."

ConfigFormatException - If "docker.saveContainerOnExit" property value is not set as a boolean "Y" or "N"

ConfigPathException - If mounted Docker volumes are not found on host or container file-system

DockerVolCreationException

SpecialPropertiesException

ConfigException

workerContainerStopped

public static boolean workerContainerStopped(File mainStarted,
                                             File workerScript)

downloadDB

public static Long downloadDB(String[] args,
                              String label)

Download a database for a Docker container

Parameters:

args - Terminal command + args

label - Log file identifier for subprocess

Returns:

Thread ID

getDockerImage

public static String getDockerImage(BioModule module)
                             throws ConfigNotFoundException

Return the name of the Docker image needed for the given module.

Parameters:

module - BioModule

Returns:

Docker image name

Throws:

ConfigNotFoundException - if Docker image version is undefined

getMainDockerImage

public static String getMainDockerImage()

getDockerVolumePath

public static File getDockerVolumePath(String path,
                                       String containerPath)

Get Docker file path through mapped volume

Parameters:

path - Config file or directory path

containerPath - Local container path

Returns:

Docker file path

getVersionAsTag

public static String getVersionAsTag()

Get the docker image tag that represents the current BioLockJ version.

Returns:

inAwsEnv

public static boolean inAwsEnv()

Return TRUE if running in AWS (based on Config props).

Returns:

TRUE if pipeline.env=aws

inDockerEnv

public static boolean inDockerEnv()

Check runtime env for /.dockerenv

Returns:

TRUE if Java running in Docker container

touchDockerInfo

public static void touchDockerInfo()
                            throws DockerVolCreationException

Save a file with info about the current docker container. If not in docker, or if the file already exists, then do nothing.

Throws:

DockerVolCreationException

containerizePath

public static String containerizePath(String path)
                               throws DockerVolCreationException

If running in docker mode, convert this path to the form that can be used inside the docker container. If not in docker, return the input path unchanged.

Parameters:

path -

Returns:

Throws:

DockerVolCreationException

containerizePath

public static File containerizePath(File file)
                             throws DockerVolCreationException

containerizePath(String)

Parameters:

file -

Returns:

Throws:

DockerVolCreationException

deContainerizePath

public static String deContainerizePath(String innerPath)
                                 throws DockerVolCreationException

If running in docker mode, convert this path to the form that can be used on the host machine. If not in docker, return the input path unchanged.

Parameters:

innerPath -

Returns:

Throws:

DockerVolCreationException

deContainerizePath

public static File deContainerizePath(File innerFile)
                               throws DockerVolCreationException

deContainerizePath(String)

Parameters:

innerFile -

Returns:

Throws:

DockerVolCreationException

main

public static void main(String[] args)
                 throws DockerVolumeException

Even outside of a BioLockJ instance, access the containerize() and decontainerze() methods. This is ideal for some support programs, and especially for testing.

Parameters:

args -

Throws:

DockerVolCreationException

DockerVolumeException

getContainerId

@Deprecated
public static String getContainerId()
                                         throws IOException,
                                                DockerVolCreationException

Deprecated.

Throws:

IOException

DockerVolCreationException

getHostName

public static String getHostName()

checkDependencies

public static void checkDependencies(BioModule module)
                              throws BioLockJException,
                                     InterruptedException,
                                     IOException

Throws:

BioLockJException

InterruptedException

IOException

isLocalImage

public static boolean isLocalImage(BioModule module,
                                   String image)
                            throws SpecialPropertiesException,
                                   InterruptedException

Throws:

SpecialPropertiesException

InterruptedException

registerProps

public static void registerProps()
                          throws API_Exception

Register properties with the Properties class for API access.

Throws:

API_Exception

listProps

public static ArrayList<String> listProps()

Let modules see property names.

getMapper

public static DockerMountMapper getMapper(boolean initAsNeeded)
                                   throws DockerVolCreationException

Intended for diagnostic purposes only.

Parameters:

initAsNeeded -

Returns:

Throws:

DockerVolCreationException

makeMapper

public static void makeMapper()
                       throws RuntimeParamException

As version v1.3.18, the logic to do this mapping is not part of the DockerUtil class. The logic was moved to new classes that implement the DockerMountMapper interface, allowing for more agility if future docker versions do not use the same Mount notation.

Throws:

RuntimeParamException