🐋 Whalebag

Docker Image Exporter Service

v1.0.0

Export Docker Image

Enter the full image name including tag (e.g., nginx:latest, ubuntu:22.04)

Pulling and exporting image... This may take a whaaale.

Popular Images

  • nginx:latest
  • alpine:latest
  • ubuntu:22.04
  • postgres:15
  • redis:7-alpine
  • node:20-alpine

API Documentation

Use the Whalebag API to programmatically export Docker images to tar files.

Base URL

http://localhost:5000

Endpoints

POST /api/export
Export a Docker image to a tar file.

Request Body

image string required
The Docker image name with optional tag (e.g., "nginx:latest", "ubuntu:22.04")

cURL Example

curl -X POST http://localhost:5000/api/export \
  -H "Content-Type: application/json" \
  -d '{"image":"nginx:latest"}' \
  -o nginx_latest.tar

Python Example

import requests

response = requests.post(
    'http://localhost:5000/api/export',
    json={'image': 'nginx:latest'}
)

if response.status_code == 200:
    with open('nginx_latest.tar', 'wb') as f:
        f.write(response.content)
    print('Image exported successfully!')
else:
    print(f'Error: {response.json()}')

JavaScript Example

fetch('http://localhost:5000/api/export', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image: 'nginx:latest' })
})
  .then(response => response.blob())
  .then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'nginx_latest.tar';
    a.click();
  });

Responses

200 OK Returns the tar file as binary data
400 Bad Request 
{"error": "Missing 'image' parameter"}
404 Not Found 
{"error": "Image not found: invalid:image"}
500 Internal Server Error 
{"error": "Export failed: ..."}
GET /api/health
Check service health and Docker connection status.

cURL Example

curl http://localhost:5000/api/health

Response Example

200 OK 
{
  "status": "healthy",
  "service": "Whalebag",
  "version": "1.0.0",
  "docker": {
    "connected": true,
    "version": "24.0.7",
    "images": 15,
    "containers": 3
  },
  "cleanup": {
    "enabled": true,
    "interval_minutes": 30,
    "max_age_hours": 1
  }
}
GET /api/stats
Get storage statistics and list of exported files.

cURL Example

curl http://localhost:5000/api/stats

Response Example

200 OK 
{
  "temp_directory": "/tmp",
  "total_files": 3,
  "total_size_mb": 456.78,
  "cleanup_config": {
    "interval_minutes": 30,
    "max_age_hours": 1
  },
  "files": [
    {
      "name": "nginx_latest.tar",
      "size_mb": 142.5,
      "created": "2025-10-14T18:30:00",
      "age_hours": 0.5
    }
  ]
}
POST /api/cleanup
Manually trigger cleanup of old tar files.

cURL Example

curl -X POST http://localhost:5000/api/cleanup

Response Example

200 OK 
{
  "status": "success",
  "message": "Cleanup completed successfully"
}

Rate Limits

Currently, there are no rate limits. However, consider implementing them for production use.

Error Handling

All error responses follow this format:

{
  "error": "Description of the error"
}

Best Practices

  • Always specify the image tag to avoid pulling unexpected versions
  • Handle network timeouts gracefully (large images may take time to pull)
  • Check the /api/health endpoint before making requests
  • Use /api/stats to monitor storage usage
  • Exported files are automatically cleaned up after 1 hour