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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/yuri-nagasaki-imageflow
Generated for open source discovery and AI-assisted research.

ImageFlow is a modern, full-stack image management and distribution platform. It automatically optimizes images for various devices and browsers, combining a high-performance Go backend with a Next.js frontend. This system offers intelligent image conversion, device-aware serving, and flexible storage options for self-hosting.

GitHub: https://github.com/Yuri-NagaSaki/ImageFlow
OSRepos URL: https://osrepos.com/repo/yuri-nagasaki-imageflow

## Summary

ImageFlow is a modern, full-stack image management and distribution platform. It automatically optimizes images for various devices and browsers, combining a high-performance Go backend with a Next.js frontend. This system offers intelligent image conversion, device-aware serving, and flexible storage options for self-hosting.

## Topics

- photos
- self-hosted
- TypeScript
- Go
- image-management
- image-optimization
- full-stack
- web-service

## Repository Information

Last analyzed by OSRepos: Fri Feb 20 2026 21:14:11 GMT+0000 (Western European Standard Time)
Detail views: 7
GitHub clicks: 14

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:**
    bash
    git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
    cd ImageFlow
    
2.  **Create a configuration file:**
    bash
    cp .env.example .env
    
3.  **Edit your configuration:**
    Open the `.env` file and set your `API_KEY` and other desired settings.
    bash
    nano .env
    
4.  **Start all services:**
    bash
    docker-compose up -d
    
    For development or local builds, you can use:
    bash
    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
bash
curl "http://localhost:8686/api/random"


### Filter by Multiple Tags
Retrieve a random image that has both "nature" and "landscape" tags.
bash
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.
bash
curl "http://localhost:8686/api/random?tag=wallpaper&exclude=nsfw,private"


### Force Orientation and Format
Request a portrait-oriented image in WebP format.
bash
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](https://github.com/Yuri-NagaSaki/ImageFlow)
*   **Docker Hub:** [https://hub.docker.com/r/soyorins/imageflow-backend](https://hub.docker.com/r/soyorins/imageflow-backend)
*   **CattoPic (Serverless Version):** [https://github.com/Yuri-NagaSaki/CattoPic](https://github.com/Yuri-NagaSaki/CattoPic)