Create Volume

Create a new Docker volume in a specific environment

POST /api/volumes

cURL - Basic

curl -X POST 'https://your-dockhand.com/api/volumes?env=1' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=your-session-cookie' \
  -d '{
    "name": "postgres-data",
    "driver": "local"
  }'

400 Validation Error

{
  "error": "Volume name is required"
}

Overview

Creates a new Docker volume with the specified configuration. This endpoint supports the local driver and third-party volume plugins for network-attached storage, cloud storage, and distributed filesystems.

Authentication

This endpoint requires authentication via cookies. The user must have the volumes:create permission for the specified environment.

Query Parameters

env · integer · required

The environment ID where the volume will be created. Required parameter.

Request Body

name · string · required

Volume name. Must be unique within the environment. Can contain letters, numbers, underscores, periods, and hyphens.

driver · string · default: "local"

Volume driver to use. Default is local. Can be a third-party plugin name (e.g., nfs, cifs, rexray, portworx).

driverOpts · object

Volume driver options as key-value pairs. Options vary by driver.

Show Common Driver Options

Local Driver with NFS:

• type: "nfs"
• device: NFS server and path (e.g., ":/data/shared")
• o: Mount options (e.g., "addr=192.168.1.100,rw,nfsvers=4")

Local Driver with CIFS/SMB:

• type: "cifs"
• device: SMB share path (e.g., "//server/share")
• o: Mount options (e.g., "username=user,password=pass,vers=3.0")

Local Driver with tmpfs:

• type: "tmpfs"
• device: "tmpfs"
• o: Mount options (e.g., "size=1G,mode=1777")

Third-Party Plugins:

• Options are plugin-specific. Refer to plugin documentation.

labels · object

User-defined labels as key-value pairs for organizing and identifying volumes.

Response

success · boolean

Whether the volume was created successfully

name · string

The name of the newly created volume

Error Responses

400 Validation Error

{
  "error": "Volume name is required"
}

cURL - Basic

curl -X POST 'https://your-dockhand.com/api/volumes?env=1' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=your-session-cookie' \
  -d '{
    "name": "postgres-data",
    "driver": "local"
  }'

200 Success

{
  "success": true,
  "name": "postgres-data"
}

Examples

Basic Local Volume

Create a standard local volume for persistent data:

{
  "name": "postgres-data",
  "driver": "local",
  "labels": {
    "app": "database",
    "environment": "production"
  }
}

NFS Volume

Create a volume backed by NFS for shared storage:

{
  "name": "shared-storage",
  "driver": "local",
  "driverOpts": {
    "type": "nfs",
    "device": ":/data/shared",
    "o": "addr=192.168.1.100,rw,nfsvers=4"
  },
  "labels": {
    "app": "file-server",
    "tier": "storage"
  }
}

CIFS/SMB Volume

Create a volume backed by Windows SMB share:

{
  "name": "windows-share",
  "driver": "local",
  "driverOpts": {
    "type": "cifs",
    "device": "//192.168.1.50/shared",
    "o": "username=shareuser,password=sharepass,vers=3.0"
  },
  "labels": {
    "app": "legacy-app",
    "storage": "windows"
  }
}

Tmpfs Volume (RAM-based)

Create a volume in memory for fast temporary storage:

{
  "name": "temp-cache",
  "driver": "local",
  "driverOpts": {
    "type": "tmpfs",
    "device": "tmpfs",
    "o": "size=1G,mode=1777"
  },
  "labels": {
    "app": "cache-service",
    "type": "temporary"
  }
}

Volume with Backup Label

Create a volume with metadata for backup automation:

{
  "name": "backup-data",
  "driver": "local",
  "labels": {
    "app": "backup",
    "tier": "storage",
    "retention": "30-days",
    "backup-schedule": "daily"
  }
}

Driver Options Reference

Local Driver

The local driver supports different mount types through driver options:

Option	Description	Example
type	Mount type (nfs, cifs, tmpfs, bind)	"nfs"
device	Device or remote path to mount	":/data/shared"
o	Comma-separated mount options	"addr=192.168.1.100,rw"

NFS Mount Options

Common NFS mount options in the o field:

• addr=<IP>: NFS server IP address
• rw / ro: Read-write or read-only
• nfsvers=<version>: NFS version (3 or 4)
• soft / hard: Failure handling
• timeo=<seconds>: Timeout value
• retrans=<count>: Number of retries

CIFS/SMB Mount Options

Common CIFS mount options in the o field:

• username=<user>: SMB username
• password=<pass>: SMB password
• vers=<version>: SMB version (1.0, 2.0, 2.1, 3.0, 3.1.1)
• domain=<domain>: Windows domain
• file_mode=<mode>: File permissions (e.g., 0777)
• dir_mode=<mode>: Directory permissions (e.g., 0777)

Tmpfs Mount Options

Common tmpfs mount options in the o field:

• size=<size>: Maximum size (e.g., 1G, 512M)
• mode=<permissions>: Directory permissions (e.g., 1777)
• uid=<uid>: Owner user ID
• gid=<gid>: Owner group ID

Notes

• Volume names must be unique within the environment
• The name field is required; all other fields are optional
• Default driver is local if not specified
• Driver options vary by driver; consult driver documentation
• Volume creation is audited with the user, action, and volume details
• Volumes persist even after all containers using them are removed
• Use driverOpts (camelCase) in the request body, not driver_opts
• For NFS/CIFS volumes, ensure the network storage is accessible from the Docker host
• Third-party volume plugins must be installed before use