Volume-explorer NPM

Docker Volume Explorer

About

Docker Volume Explorer allows you to easily interact with Docker volumes in Windows and Linux systems (Macos support coming soon). You can read, copy, and list all files inside of the volume.

Quickstart

Simply initialize the VolumeExplorer object with your desired parameters (see documentation), access a volume, and perform your desired operation.

const volumeExplorer = require("volume-explorer");
const VolumeExplorer = new volumeExplorer();

const myVolume = VolumeExplorer.volume("your docker volume name")
myVolume.readDir("/").then(data => {
	console.log(data)
})

Examples

Click here

Documentation

Configuration Object

When initializing the VolumeExplorer object, a configuration object such as below can be passed in (not required).

const VolumeExplorer = new volumeExplorer({
	protocol: "http" || "https", // (optional) - specify Docker API endpoint protocol
	host: "localhost" || "127.0.0.1", // (optional) - specify Docker API hostname,
	port: 2375, // (optional) - specify Docker API port
	forcePlatformType: "win32" || "linux", // (optional),
	socketPath: "/path/to/socket/docker.sock" // (optional) - specify Docker socket path
})

Volume Object

Initialization

const volume = VolumeExplorer.volume("volume name")

Important: This does not query the API or do anything with the volume name. If the volume name doesn't exist, it WILL NOT fail here. Instead, it will fail when attempting an operation on this volume object.\ \ .inspect\ Inspect a volume and return information on it

volume.inspect().then(data => {
	console.log(data)
})

Returns an object similar to below:

{
	"Name": "tardis",
	"Driver": "custom",
	"Mountpoint": "/var/lib/docker/volumes/tardis",
	"Status": {
		"hello": "world"
	},
	"Labels": {
		"com.example.some-label": "some-value",
		"com.example.some-other-label": "some-other-value"
	},
	"Scope": "local",
	"CreatedAt": "2016-06-07T20:31:11.853781916Z"
}

.getLocalPath\ Returns the location of the volume on the host machine

volume.getLocalPath().then(path => {
	console.log(path)
})

.readDir\ Returns an array of files and directories in the specified path in the volume\ Arguments:

path (default="/") - Specify the path to the directory in the volume. Must begin with "/"

volume.readDir("/path/to/directory").then(entries => {
	console.log(entries)
})

Returned array may look like below:

[ { name: 'file.txt', type: 'file' }, { name: 'folder', type: 'directory' }]

.readFile\ Returns a Buffer or string representing the data in the file\ Arguments:

path (required) - The path to the file to be read
encoding (required) - The encoding used to read the file (utf-8)

volume.readFile("/myfile.txt", "utf-8").then(data => {
	console.log(data)
})

.copyFile\ Returns true if it successfully copied the file from the volume into the host machine\ Arguments:

Source (required) - The path to the file to be copied in the volume
Destination (required) - The path to the destination file in the host machine

volume.copyFile("./configuration.txt", "./hello.txt").then(status => {
	console.log(status)
})

.copyDirSync\ Copying a directory using standard synchronous functions. However, this function is still asynchronous! So, this is not recommended and users should consider using copyDir as this function is much faster. Arguments:

Source (required) - The path to the file to be copied in the volume
Destination (required) - The path to the destination file in the host machine

volume.copyDirSync("/", "./output").then(status=> {
    console.log("Completed: ", status)
})

.copyDir\ Copying a directory using custom asynchronous computing, resulting in a 40-50% performance improvement in large folders with many sub-folders (like node_modules). Recommended over copyDirSync Arguments:

Source (required) - The path to the file to be copied in the volume
Destination (required) - The path to the destination file in the host machine
Status callback (optional) - A function callback that gets executed to update the status (percentage discovered, percentage completed, and amount of queued up/running operations)

volume.copyDir("/", "./output", function(status) {
   // this gets run many times to update you on the current status.
    console.log(status.finished, status.jobs, status.runningOperations, status.status)
}).then(status => {
   // this gets run when everything is done
    console.log("Completed: ", status)
})

.stat\ Returns an object describing the file's metadata. Returns an fs.stat() object\ Arguments:

Path (required) - The path to the file

volume.stat("/myfile.txt").then(data => {
   console.log(data)
})

.writable\ Returns a WritableVolume object asynchronously Arguments:

None

Writable Volume object

.writeFile\ Synchronously writes a file into the docker volume. Returns a boolean regarding status.\ Arguments:

path (required) - The path in the volume to write to
data (required) - The data to be written
encoding (default=utf-8) - The encoding to use

VolumeExplorer.volume("my volume name").writable().then(writableVolume => {
    writableVolume.writeFile("/myfile.txt", "hello world!");
})

.unlink\ Synchronously removes a file from your volume. Returns a boolean regarding its status.\ Arguments:

path (required) - The path to the file in the volume to remove

VolumeExplorer.volume("my volume name").writable().then(writableVolume => {
    writableVolume.unlink("/myfile.txt");
})

.mkdir\ Synchronously creates a directory in your volume. Returns a boolean regarding its status.\ Arguments:

path (required) - The path to the file in the volume to remove
mode (default=false) - If true, will recursivly create the directory (see fs documentation)

VolumeExplorer.volume("my volume name").writable().then(writableVolume => {
    writableVolume.mkdir("/myfolder");
})

.rmdir\ Synchronously removes a directory from your volume. Returns a boolean regarding its status.\ Arguments:

path (required) - The path to the file in the volume to remove
mode (default={}) - If {recursive: true}, will delete a non-empty directory

VolumeExplorer.volume("my volume name").writable().then(writableVolume => {
    writableVolume.rmdir("/myfolder");
})

.copyFileIntoVolume\ Synchronously copies a file from host system into your volume. Returns a boolean regarding its status.\ Arguments:

src (required) - The path in the host to copy from
dest (required) - The path in the volume to copy to

VolumeExplorer.volume("my volume name").writable().then(writableVolume => {
	writableVolume.copyFileIntoVolume("./myFile.txt", "/destination.txt");
})

npm.io