ericthedev/tinyimage-server repository overview

⁠TinyImage Server

A simple, lightweight image processing and compression server built with Go and Fiber. This server provides both HTTP and WebSocket APIs to queue and process image compression tasks, supporting WebP, PNG, and JPEG formats.

⁠Features

• Asynchronous Processing: Uses a worker pool to handle image compression tasks without blocking the main server thread.
• Multiple Formats: Supports converting and compressing images to WebP, PNG, and JPEG.
• WebSocket API: Enables real-time, bidirectional communication for image uploads and instant previews of processed images.
• Efficient Compression: Leverages bimg (a Go wrapper for libvips) and pngquant for high-quality, efficient compression.
• Configurable: Easily customize server port, task concurrency, and maximum upload size via a config.yaml file.
• Automatic Cleanup: Periodically deletes old processed files to manage disk space.

⁠Deployment

The easiest way to deploy this server is by using the provided Dockerfile and Docker Compose.

⁠Prerequisites

• Docker: Install Docker⁠ on your system.
• Docker Compose: Install Docker Compose⁠ (comes with Docker Desktop).

⁠Steps

1. Clone the Repository

   git clone https://github.com/your-username/your-repo-name.git
   cd your-repo-name
   

   Copy

2. Configure the Server Edit the config.yaml file to set your desired options.

   • server.port: The port the server will listen on.
   • server.output_dir: The directory to save processed images.
   • upload.max_upload_size: The maximum file size for uploads (e.g., 10MB, 500KB).
   • upload.max_concurrent_tasks: The number of concurrent image processing workers.
   • upload.max_age: The maximum number of hours an uploaded image is kept before being automatically deleted.

   # config.yaml example
   server:
     port: 8080
     output_dir: "output"
   
   upload:
     max_upload_size: 10MB
     max_concurrent_tasks: 3
     max_age: 24
   
   download:
     download_url: "download/"
   

   Copy

3. Build and Run with Docker Compose Create a docker-compose.yaml file in the project root with the following content:

   version: '3.8'
   services:
     tinyimage-server:
       build:
         context: .
         dockerfile: Dockerfile
       ports:
         - "8080:8080"
       volumes:
         - ./config.yaml:/config/config.yaml
         - ./output:/output
   

   Copy

   Then, run the following command to build and start the server:

   docker-compose up --build -d
   

   Copy

   Or with prebuilt image ghcr.io/humanutopia/tinyimage-server:latest⁠

   version: '3.8'
   services:
     tinyimage-server:
       image: ghcr.io/humanutopia/tinyimage-server
       container_name: tinyimage-server
       ports:
         - "8080:8080"
       volumes:
         - ./config.yaml:/config/config.yaml
         - ./output:/app/output
   

   Copy

   docker-compose up  -d
   

   Copy

   The server will now be running at http://localhost:8080.

⁠API Documentation

The server provides a RESTful API and a WebSocket API.

⁠1. HTTP API

⁠GET / - Server Status

Description: Get server configuration and version info. Example:

curl http://localhost:8080/

Response:

{
  "version": "v0.0.1",
  "download_url": "download/",
  "max_upload_size_bytes": "10MB",
  "max_concurrent_tasks": 3,
  "max_age": 24
}

⁠POST /upload - Upload Image

Description: Upload an image for processing. The server queues the task and returns a unique MD5 hash. Request: multipart/form-data

• picture: (file, required) The image file.
• format: (string, optional) Output format (webp, png, jpg). Default is webp.
• quality: (int, optional) For jpg format, 1-100. Default is 80.

Example:

curl -X POST http://localhost:8080/upload \
  -F "picture=@/path/to/your/image.jpg" \
  -F "format=png"

Response:

{
  "message": "Your image is queued for processing",
  "md5": "a1b2c3d4e5f6...",
  "format": "png",
  "quality": 0
}

Error:

{"message": "Image already processed for this format/quality",
  "md5": "213d21f...",
  "format": "png",
  "quality": 80
}

⁠GET /status/:md5 - Check Task Status

Description: Check the processing status of an image. Example:

curl http://localhost:8080/status/a1b2c3d4e5f6...

Response:

[
  {
    "md5": "a1b2c3d4e5f6...",
    "status": "processing",
    "format": "png",
    "quality": 0
  }
]

⁠GET /download/:md5 - Download Processed Image

Description: Download the processed image file. Example:

curl -o processed_image.png http://localhost:8080/download/a1b2c3d4e5f6...

Response: The raw image file.

⁠2. WebSocket API

The WebSocket API allows for real-time communication, providing instant feedback and the processed image file directly over the connection.

⁠Endpoint: ws://localhost:8080/ws

Client to Server (Request): Send a JSON object containing the Base64-encoded image data.

{
  "filename": "my_image.jpeg",
  "format": "jpg",
  "data": "iVBORw0KGgo...",
  "quality": 80
}

Server to Client (Response): The server will send messages with status updates. When the image is processed, a done message with the Base64-encoded output file is sent.

• Queued:

  {"status": "queued", "md5": "a1b2c3d4...", "format": "jpg", "quality": 80}
  

  Copy
• Processing:

  {"status": "processing", "md5": "a1b2c3d4...", "format": "jpg", "quality": 80}
  

  Copy
• Done:

  {
    "status": "done",
    "md5": "a1b2c3d4...",
    "format": "jpg",
    "quality": 80,
    "file": "iVBORw0KGgo..."
  }
  

  Copy
• Error:

  {"status": "error", "message": "invalid_json"}
  

  Copy

  {"status": "error", "message": "unsupported_format"}
  

  Copy

  {"status": "size_exceeded", "message": "file too large"}
  

  Copy

  {"status": "unsupported_format", "message": "only webp/png/jpg supported"}
  

  Copy