ImageFlow: A Modern Self-Hosted Image Service System with Auto-Optimization

Introduction

ImageFlow is a robust, full-stack image management and distribution platform designed for modern web applications. It automatically optimizes images for different devices and browsers, ensuring fast loading times and efficient delivery. Built with a high-performance Go backend and a responsive Next.js frontend, ImageFlow provides intelligent image conversion, device-aware serving, and powerful filtering capabilities. It's an excellent solution for anyone looking to self-host a sophisticated image service.

Installation

Getting ImageFlow up and running is straightforward with Docker Compose.

Prerequisites

• Docker and Docker Compose installed
• Minimum 1GB RAM recommended
• Sufficient disk space for image storage

Quick Start

1. Clone the repository:

   git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
   cd ImageFlow
   

2. Create a configuration file:

   cp .env.example .env
   

3. Edit your configuration:

   Open the .env file and set your API_KEY and other desired settings.

   nano .env
   

4. Start all services:

   docker-compose up -d
   

   For development or local builds, you can use:

   docker-compose -f docker-compose.build.yaml up --build -d
   

After deployment, you can access the frontend at http://localhost:3000 and the backend API at http://localhost:8686.

Examples

ImageFlow provides a powerful API for image retrieval and management. Here are a few examples of using the public /api/random endpoint to fetch images.

Get a Basic Random Image

curl "http://localhost:8686/api/random"

Filter by Multiple Tags

Retrieve a random image that has both "nature" and "landscape" tags.

curl "http://localhost:8686/api/random?tags=nature,landscape"

Exclude Specific Content

Fetch a wallpaper image, ensuring it does not have "nsfw" or "private" tags.

curl "http://localhost:8686/api/random?tag=wallpaper&exclude=nsfw,private"

Force Orientation and Format

Request a portrait-oriented image in WebP format.

curl "http://localhost:8686/api/random?orientation=portrait&format=webp"

For authenticated endpoints like upload or deletion, an Authorization: Bearer your-api-key header is required. Refer to the official documentation for more details.

Why Use It

ImageFlow stands out as a comprehensive solution for image management due to several key features:

• Automatic Image Optimization: It converts images to modern formats like WebP and AVIF, leveraging libvips for high-performance processing and configurable quality settings. This ensures images are delivered in the most efficient format for each user.
• Intelligent Distribution: The system intelligently serves images based on the user's device orientation and browser capabilities, optimizing for mobile or desktop views and negotiating the best format (AVIF > WebP > Original).
• Flexible Storage Options: ImageFlow supports both local filesystem storage and S3-compatible object storage, offering versatility for different deployment scenarios.
• Modern User Interface: A responsive Next.js frontend provides a seamless experience with features like drag-and-drop batch upload, dark mode, and a masonry layout.
• Robust API and Security: It offers a well-documented API for both public access and authenticated management, including features like API key authentication, automatic cleanup of expired images, and configurable CORS policies.
• Self-Hosted Control: By self-hosting ImageFlow, you maintain full control over your image assets and infrastructure.

Links

• GitHub Repository: https://github.com/Yuri-NagaSaki/ImageFlow
• Docker Hub: https://hub.docker.com/r/soyorins/imageflow-backend
• CattoPic (Serverless Version): https://github.com/Yuri-NagaSaki/CattoPic