> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Finsys/dockhand/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Volume

> Create a new Docker volume in a specific environment

## 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

<ParamField query="env" type="integer" required>
  The environment ID where the volume will be created. Required parameter.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  Volume name. Must be unique within the environment. Can contain letters, numbers, underscores, periods, and hyphens.
</ParamField>

<ParamField body="driver" type="string" default="local">
  Volume driver to use. Default is `local`. Can be a third-party plugin name (e.g., `nfs`, `cifs`, `rexray`, `portworx`).
</ParamField>

<ParamField body="driverOpts" type="object" default={{}}>
  Volume driver options as key-value pairs. Options vary by driver.

  <Expandable title="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.
  </Expandable>
</ParamField>

<ParamField body="labels" type="object" default={{}}>
  User-defined labels as key-value pairs for organizing and identifying volumes.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the volume was created successfully
</ResponseField>

<ResponseField name="name" type="string">
  The name of the newly created volume
</ResponseField>

## Error Responses

<ResponseExample>
  ```json 400 Validation Error theme={null}
  {
    "error": "Volume name is required"
  }
  ```

  ```json 403 Permission Denied theme={null}
  {
    "error": "Permission denied"
  }
  ```

  ```json 403 Environment Access Denied theme={null}
  {
    "error": "Access denied to this environment"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "error": "Failed to create volume",
    "details": "volume with name postgres-data already exists"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL - Basic theme={null}
  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"
    }'
  ```

  ```bash cURL - NFS Volume theme={null}
  curl -X POST 'https://your-dockhand.com/api/volumes?env=1' \
    -H 'Content-Type: application/json' \
    -H 'Cookie: session=your-session-cookie' \
    -d '{
      "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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-dockhand.com/api/volumes?env=1', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'postgres-data',
      driver: 'local',
      driverOpts: {},
      labels: {
        app: 'database',
        environment: 'production'
      }
    })
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://your-dockhand.com/api/volumes',
      params={'env': 1},
      cookies={'session': 'your-session-cookie'},
      json={
          'name': 'postgres-data',
          'driver': 'local',
          'driverOpts': {},
          'labels': {
              'app': 'database',
              'environment': 'production'
          }
      }
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "name": "postgres-data"
  }
  ```
</ResponseExample>

## Examples

### Basic Local Volume

Create a standard local volume for persistent data:

```json theme={null}
{
  "name": "postgres-data",
  "driver": "local",
  "labels": {
    "app": "database",
    "environment": "production"
  }
}
```

### NFS Volume

Create a volume backed by NFS for shared storage:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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