🎯 Paikary Media Server

📦 Features

• ✅ 3 Format Upload: Original, Medium (80%), Thumbnail
• ✅ Fast Delivery: CDN-like caching, compression, optimized
• ✅ Secure: API key, domain whitelist, rate limiting
• ✅ Production Ready: Docker, persistent storage, monitoring
• ✅ Image Optimization: Sharp library, WebP support
• ✅ Public Access: Fast static file serving

🔑 API Documentation

Content-Type: multipart/form-data
x-api-key: NIATkdZDNRl5aaUDdFrIg39n

file: [File] (required)
folder: [String] (optional, default: "media")

{
  "success": true,
  "uid": "550e8400-e29b-41d4-a716-446655440000",
  "folder": "media",
  "originalName": "product.jpg",
  "mimeType": "image/jpeg",
  "size": 1048576,
  "extension": "jpg",
  "files": {
    "original": {
      "filename": "550e8400-original.jpg",
      "path": "/uploads/media/550e8400-original.jpg",
      "url": "http://localhost:5001/uploads/media/550e8400-original.jpg",
      "size": 1048576
    },
    "medium": {
      "filename": "550e8400-medium.jpg",
      "path": "/uploads/media/550e8400-medium.jpg",
      "url": "http://localhost:5001/uploads/media/550e8400-medium.jpg",
      "size": 209715,
      "width": 1200,
      "height": 800
    },
    "thumbnail": {
      "filename": "550e8400-small.jpg",
      "path": "/uploads/media/550e8400-small.jpg",
      "url": "http://localhost:5001/uploads/media/550e8400-small.jpg",
      "size": 15728,
      "width": 300,
      "height": 300
    }
  },
  "uploadedAt": "2026-02-25T12:00:00.000Z"
}

🖼️ Public Access

All uploaded files are publicly accessible:

Original:   http://localhost:5001/uploads/[folder]/[uid]-original.[ext]
Medium:     http://localhost:5001/uploads/[folder]/[uid]-medium.[ext]
Thumbnail:  http://localhost:5001/uploads/[folder]/[uid]-small.[ext]

Default folder: "media"
Example: http://localhost:5001/uploads/media/550e8400-original.jpg

Example Usage in HTML

<!-- Thumbnail for listing -->
<img src="http://localhost:5001/uploads/media/550e8400-small.jpg" 
     alt="Product" 
     width="300" 
     height="300">

<!-- Medium for product page -->
<img src="http://localhost:5001/uploads/media/550e8400-medium.jpg" 
     alt="Product" 
     loading="lazy">

<!-- Original for zoom/download -->
<a href="http://localhost:5001/uploads/media/550e8400-original.jpg" 
   target="_blank">
   View Full Size
</a>

💻 Usage Examples

JavaScript/TypeScript

async function uploadImage(file: File, folder = 'media') {
    const formData = new FormData()
    formData.append('file', file)
    formData.append('folder', folder)

    const response = await fetch('http://localhost:5001/api/upload', {
        method: 'POST',
        headers: {
            'x-api-key': 'NIATkdZDNRl5aaUDdFrIg39n'
        },
        body: formData
    })

    if (!response.ok) {
        throw new Error('Upload failed')
    }

    return await response.json()
}

// Usage
const file = document.querySelector('input[type="file"]').files[0]
const result = await uploadImage(file, 'products')

console.log('Folder:', result.folder)
console.log('Original:', result.files.original.url)
console.log('Medium:', result.files.medium.url)
console.log('Thumbnail:', result.files.thumbnail.url)

cURL

# Upload
curl -X POST http://localhost:5001/api/upload \
  -H "x-api-key: NIATkdZDNRl5aaUDdFrIg39n" \
  -F "file=@product.jpg" \
  -F "folder=products"

# View
curl http://localhost:5001/uploads/products/550e8400-medium.jpg --output image.jpg

🔒 Security

• API Key Authentication: Required for all uploads
• Domain Whitelist: Only allowed origins can upload
• File Size Limit: Maximum 10MB per file
• File Type Validation: Only allowed extensions accepted
• Rate Limiting: Prevents abuse

⚙️ Configuration

Configure via environment variables in .env.local:

# Security
API_KEY=your-secret-api-key-here
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com

# File Upload
UPLOAD_DIR=./uploads
DEFAULT_FOLDER=media
MAX_FILE_SIZE=10485760
ALLOWED_EXTENSIONS=jpg,jpeg,png,gif,webp,svg,pdf

# Image Processing
IMAGE_QUALITY_MEDIUM=80
IMAGE_QUALITY_THUMBNAIL=70
THUMBNAIL_WIDTH=300
THUMBNAIL_HEIGHT=300
MEDIUM_MAX_WIDTH=1200
MEDIUM_MAX_HEIGHT=1200

📊 Health Check

Check server status:

GET http://localhost:5001/api/health