Skip to main content
POST
/
api
/
volumes
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"
  }'

{
  "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.
​
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

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

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"
  }'

{
  "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:
OptionDescriptionExample
typeMount type (nfs, cifs, tmpfs, bind)"nfs"
deviceDevice or remote path to mount":/data/shared"
oComma-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

Build docs developers (and LLMs) love

Get started for freeTalk to us