Volume Disk Quotas

Overview

Lightd supports OS-level disk quotas for volumes to prevent containers from consuming unlimited disk space. Quotas are enforced at the filesystem level using platform-specific mechanisms.

Features

OS-Level Enforcement

Uses native OS mechanisms (disk images on macOS, loop devices on Linux)

Default 1GB Quota

Volumes default to 1GB if no size specified

Customizable Size

Specify size in MB during creation

Real-time Monitoring

Check quota usage at any time

Resizable

Expand or shrink volume quotas

WebSocket Alerts

Get notified when volume is out of space

Platform Support

macOS
Linux
Other Platforms

Uses sparse disk images (.sparseimage)
Mounted via hdiutil
Supports dynamic resizing
Efficient space usage (sparse allocation)

Uses loop devices with ext4 filesystem
Mounted via mount -o loop
Supports resizing with resize2fs
Efficient sparse file allocation

Create Volume with Quota

Create a new volume with specified disk quota.

curl -X POST http://localhost:8070/volumes \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"size": 2048}'

Request Body:

{
  "size": 2048
}

Fields:

size (optional) - Disk quota in MB (default: 1024 = 1GB)

Examples:

{"size": 1024} = 1GB
{"size": 2048} = 2GB
{"size": 10240} = 10GB
{} or no body = 1GB default

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/path/to/volume",
  "created_at": 1706400000,
  "quota_mb": 2048
}

Get Quota Usage

Check current disk usage for a volume.

curl -X GET http://localhost:8070/volumes/550e8400/quota \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"

Response:

{
  "size_mb": 2048,
  "used_mb": 512,
  "available_mb": 1536,
  "percentage_used": 25.0
}

Fields:

size_mb - Total quota size in MB
used_mb - Currently used space in MB
available_mb - Available space in MB
percentage_used - Percentage of quota used (0-100)

Resize Volume

Change the disk quota for an existing volume.

curl -X POST http://localhost:8070/volumes/550e8400/resize \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"size": 4096}'

Request Body:

{
  "size": 4096
}

Fields:

size (required) - New quota size in MB

Can increase or decrease size
Decreasing below current usage may fail
Volume is temporarily unmounted during resize

WebSocket Notifications

When a container’s volume runs out of space, Lightd sends a WebSocket event:

{
  "event": "daemon_message",
  "data": "System out of storage"
}

This allows applications to handle disk full scenarios gracefully.

Quota Monitoring

Lightd automatically monitors volume quotas and considers a volume “out of space” when:

Less than 10MB available, OR
More than 95% of quota used

Applications should monitor quota usage and handle low disk space appropriately.

Size Reference

Common size conversions:

Size	MB Value	JSON Example
512MB	512	`{"size": 512}`
1GB	1024	`{"size": 1024}`
2GB	2048	`{"size": 2048}`
5GB	5120	`{"size": 5120}`
10GB	10240	`{"size": 10240}`
20GB	20480	`{"size": 20480}`
50GB	51200	`{"size": 51200}`
100GB	102400	`{"size": 102400}`

Formula: MB = GB × 1024

Complete Example

Here’s a complete workflow for managing volume quotas:

// Create 10GB volume
const createResponse = await fetch('http://localhost:8070/volumes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer lightd_token',
    'Accept': 'Application/vnd.pkglatv1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ size: 10240 })
});

const { id } = await createResponse.json();
console.log('Volume created:', id);

// Monitor quota usage
const checkQuota = async () => {
  const response = await fetch(`http://localhost:8070/volumes/${id}/quota`, {
    headers: {
      'Authorization': 'Bearer lightd_token',
      'Accept': 'Application/vnd.pkglatv1+json'
    }
  });
  
  const quota = await response.json();
  console.log(`Usage: ${quota.used_mb}MB / ${quota.size_mb}MB (${quota.percentage_used}%)`);
  
  // Alert if over 80% used
  if (quota.percentage_used > 80) {
    console.warn('Volume is running low on space!');
    
    // Resize to 20GB
    await fetch(`http://localhost:8070/volumes/${id}/resize`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer lightd_token',
        'Accept': 'Application/vnd.pkglatv1+json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ size: 20480 })
    });
    
    console.log('Volume resized to 20GB');
  }
};

// Check quota every 5 minutes
setInterval(checkQuota, 5 * 60 * 1000);

Best Practices

Set Appropriate Quotas

Estimate application needs and add buffer space. Better to start larger than to resize frequently.

Monitor Usage

Regularly check quota usage via API. Set up alerts when usage exceeds 80%.

Handle Disk Full

Implement error handling for disk full scenarios. Listen to WebSocket events for storage alerts.

Plan for Growth

Resize volumes before hitting limits. Don’t wait until 95% full.

Use WebSocket Events

Subscribe to storage alerts to get real-time notifications when volumes are running low.

Technical Implementation

macOS
Linux

# Create sparse disk image
hdiutil create -size 2048m -fs HFS+ -volname volume-id \
  -type SPARSE /path/to/volume.dmg

# Mount disk image
hdiutil attach /path/to/volume.dmg.sparseimage \
  -mountpoint /path/to/mount -nobrowse

# Resize disk image
hdiutil resize -size 4096m /path/to/volume.dmg.sparseimage

# Unmount
hdiutil detach /path/to/mount -force

# Create sparse file
dd if=/dev/zero of=/path/to/volume.img bs=1M count=0 seek=2048

# Create filesystem
mkfs.ext4 -F /path/to/volume.img

# Mount loop device
mount -o loop /path/to/volume.img /path/to/mount

# Resize
dd if=/dev/zero of=/path/to/volume.img bs=1M count=0 seek=4096
resize2fs /path/to/volume.img

# Unmount
umount /path/to/mount

Limitations

macOS: Requires hdiutil (included in macOS)
Linux: Requires mount, mkfs.ext4, resize2fs (usually pre-installed)
Permissions: May require elevated permissions for mount operations
Performance: Slight overhead compared to direct filesystem access
Resize Downtime: Volume temporarily unavailable during resize

Error Handling

Failed to create disk image

Causes:

Insufficient disk space on host
Permission issues
Missing system tools

Solutions:

Check available disk space
Verify permissions
Ensure hdiutil (macOS) or mount (Linux) is available

Failed to mount

Causes:

Mount point already in use
Disk image/file doesn’t exist
System mount limits reached

Solutions:

Check if mount point is in use
Verify disk image/file exists
Check system mount limits

Resize failed

Causes:

Cannot shrink below current usage
Invalid new size
Insufficient host disk space

Solutions:

Ensure new size is larger than current usage
Verify new size is valid
Check available host disk space

Security Considerations

DoS Prevention: Quotas prevent disk exhaustion attacks
Isolation: Each volume is isolated from others
Host Protection: Host filesystem protected from container abuse
OS-Level Enforcement: Quota enforcement at OS level (cannot be bypassed)

Getting Started

API Reference

Examples

Overview

Features

OS-Level Enforcement

Default 1GB Quota

Customizable Size

Real-time Monitoring

Resizable

WebSocket Alerts

Platform Support

Create Volume with Quota

Get Quota Usage

Resize Volume

WebSocket Notifications

Quota Monitoring

Size Reference

Complete Example

Best Practices

Technical Implementation

Limitations

Error Handling

Security Considerations

Getting Started

API Reference

Examples

​Overview

​Features

OS-Level Enforcement

Default 1GB Quota

Customizable Size

Real-time Monitoring

Resizable

WebSocket Alerts

​Platform Support

​Create Volume with Quota

​Get Quota Usage

​Resize Volume

​WebSocket Notifications

​Quota Monitoring

​Size Reference

​Complete Example

​Best Practices

​Technical Implementation

​Limitations

​Error Handling

​Security Considerations

Overview

Features

Platform Support

Create Volume with Quota

Get Quota Usage

Resize Volume

WebSocket Notifications

Quota Monitoring

Size Reference

Complete Example

Best Practices

Technical Implementation

Limitations

Error Handling

Security Considerations