image-resize

🖼️ Image Resize API

A high-performance, production-ready Go API for image processing with resize, crop, and advanced processing capabilities.

✨ Features

• 🔄 Image Resizing: High-quality image resizing with multiple algorithms.
• ✂️ Cropping: Precise image cropping with coordinate-based positioning.
• 💧 Watermarking: Text watermarks with opacity and position control.
• 📦 Batch Processing: Concurrent processing of multiple images.
• ⚡ Caching: Redis-based result caching for improved performance.
• ☁️ Cloud Storage: Supabase integration for scalable storage.
• 📊 Monitoring: Health checks and basic service status.
• 🔒 Security: Input validation, CORS, and security headers.
• 🐳 Docker Ready: Complete containerization setup.

🚀 Tech Stack

• Language: Go
• Web Framework: Gin Gonic
• Image Processing: disintegration/imaging
• Configuration: godotenv
• Logging: Zap
• Cache: Redis
• Cloud Storage: Supabase

📋 Table of Contents

• Project Title & Badges
• Description
• Features
• Tech Stack
• Table of Contents
• Installation
  • Prerequisites
  • Steps
• Usage
  • API Endpoints
  • Example: Single Image Resize
  • Example: Advanced Processing
  • Example: Batch Resize
• Docker Setup
• Configuration
• License
• Footer

📝 Description

A high-performance, production-ready Go API designed for efficient image processing. It offers functionalities such as resizing, cropping, and batch processing, leveraging external services like Redis for caching and Supabase for cloud storage to ensure scalability and speed.

🛠️ Installation

Prerequisites

• Go: Version 1.23.6 or later.
• Docker: For containerized development and deployment.
• Redis: For caching image processing results.
• Supabase: For cloud storage of processed images.
• RabbitMQ: (Optional, but configured in .env.example) for asynchronous job queueing (though not fully implemented in current handlers).

Steps

1. Clone the repository:

   git clone https://github.com/phambaophuc/image-resize.git
   cd image-resize
   

2. Set up environment variables:
   Copy the example environment file and configure your credentials:

   cp .env.example .env
   

   Edit the .env file with your Supabase URL, key, bucket, and any other necessary configurations.

3. Build the Docker image:

   docker compose build
   

4. Run the application with Docker Compose:
   This command will start the API, Redis, and potentially other services defined in docker-compose.yaml.

   docker compose up -d
   

Alternatively, to run directly without Docker (after setting up dependencies and environment variables):

1. Download Go dependencies:

   go mod download
   

2. Run the application:

   go run server/main.go
   

   The API will be available at http://localhost:8080.

💡 Usage

This API provides endpoints for various image manipulation tasks. All requests should be made to the base URL http://localhost:8080/api/v1.

API Endpoints

• GET /health: Checks the health status of the API and its dependencies (Supabase, Redis).
• POST /images/resize: Resizes a single image.
• POST /images/batch/resize: Resizes multiple images concurrently.
• POST /images/process: Performs advanced image processing (resize, crop, watermark) based on a JSON payload.

Example: Single Image Resize

Resize an image to a specific width and height.

Request:

POST /api/v1/images/resize
Content-Type: multipart/form-data

Parameters:
- image: Image file (required)
- width: Target width in pixels (required)
- height: Target height in pixels (required)
- quality: JPEG quality 1-100 (optional, default: 75)
- format: Output format jpeg|png|webp (optional)

Using curl:

curl -X POST http://localhost:8080/api/v1/images/resize \
  -F "image=@./path/to/your/photo.jpg" \
  -F "width=800" \
  -F "height=600" \
  -F "quality=90" \
  -F "format=jpeg"

Example: Advanced Processing

Perform multiple operations (resize, crop, watermark) using a JSON payload.

Request:

POST /api/v1/images/process
Content-Type: multipart/form-data

Parameters:
- image: Image file (required)
- payload: JSON string defining processing steps (e.g., resize, crop, watermark)

Using curl:

curl -X POST http://localhost:8080/api/v1/images/process \
  -F "image=@./path/to/your/photo.jpg" \
  -F 'payload={"resize": {"width": 800, "height": 600, "quality": 90}, "crop": {"x": 0, "y": 0, "width": 400, "height": 300}, "watermark": {"text": "© Your Company", "position": "bottom-right", "opacity": 0.7}}'

Example: Batch Resize

Process multiple images concurrently. The width, height, quality, and format parameters apply to all images in the batch.

Request:

POST /api/v1/images/batch/resize
Content-Type: multipart/form-data

Parameters:
- images: Multiple image files (required)
- width: Target width in pixels (required)
- height: Target height in pixels (required)
- quality: JPEG quality 1-100 (optional, default: 75)
- format: Output format jpeg|png|webp (optional)

Using curl:

curl -X POST http://localhost:8080/api/v1/images/batch/resize \
  -F "images=@./path/to/image1.jpg" \
  -F "images=@./path/to/image2.png" \
  -F "width=400" \
  -F "height=300"

🐳 Docker Setup

Using Docker Compose (Recommended)

For a complete setup including dependencies like Redis:

docker compose up -d --build

This command will build the necessary images and start the containers in detached mode.

Using Docker Only

If you only want to build and run the application container without other services:

# Build the image
docker build -t image-resize-api .

# Run the container
docker run -p 8080:8080 image-resize-api

⚙️ Configuration

Configuration is managed via environment variables, with defaults provided in .env.example.

Environment Variables

Variable	Description	Default
PORT	Server port	8080
READ_TIMEOUT	Server read timeout	10s
WRITE_TIMEOUT	Server write timeout	10s
SUPABASE_URL	Supabase project URL	-
SUPABASE_KEY	Supabase project anonymous or service role key	-
SUPABASE_BUCKET	Supabase storage bucket name	-
REDIS_ADDR	Redis server address	localhost:6379
REDIS_PASSWORD	Redis password (if required)	``
REDIS_DB	Redis database number	0
RABBITMQ_URL	RabbitMQ connection URL	amqp://guest:guest@localhost:5672/
MAX_FILE_SIZE	Maximum allowed upload file size in bytes	10485760 (10MB)
UPLOAD_PATH	Local path for uploads (if not using cloud)	./uploads
CACHE_DURATION	Duration for caching results (e.g., 24h)	24h
GIN_MODE	Gin framework mode (release or debug)	release

Supported Image Formats

• Input: JPEG, PNG, WebP, GIF
• Output: JPEG, PNG, WebP

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Crafted with ❤️ by phambaophuc

⭐ Star this repo if it helped you build something awesome!

---