{"name":"ImageFlow: A Modern Self-Hosted Image Service System with Auto-Optimization","description":"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","url":"https://osrepos.com/repo/yuri-nagasaki-imageflow","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/yuri-nagasaki-imageflow","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/yuri-nagasaki-imageflow.md","json":"https://osrepos.com/repo/yuri-nagasaki-imageflow.json","topics":["photos","self-hosted","TypeScript","Go","image-management","image-optimization","full-stack","web-service"],"keywords":["photos","self-hosted","TypeScript","Go","image-management","image-optimization","full-stack","web-service"],"stars":null,"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.","content":"## Introduction\n\nImageFlow 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.\n\n## Installation\n\nGetting ImageFlow up and running is straightforward with Docker Compose.\n\n### Prerequisites\n*   Docker and Docker Compose installed\n*   Minimum 1GB RAM recommended\n*   Sufficient disk space for image storage\n\n### Quick Start\n\n1.  **Clone the repository:**\n    bash\n    git clone https://github.com/Yuri-NagaSaki/ImageFlow.git\n    cd ImageFlow\n    \n2.  **Create a configuration file:**\n    bash\n    cp .env.example .env\n    \n3.  **Edit your configuration:**\n    Open the `.env` file and set your `API_KEY` and other desired settings.\n    bash\n    nano .env\n    \n4.  **Start all services:**\n    bash\n    docker-compose up -d\n    \n    For development or local builds, you can use:\n    bash\n    docker-compose -f docker-compose.build.yaml up --build -d\n    \n\nAfter deployment, you can access the frontend at `http://localhost:3000` and the backend API at `http://localhost:8686`.\n\n## Examples\n\nImageFlow provides a powerful API for image retrieval and management. Here are a few examples of using the public `/api/random` endpoint to fetch images.\n\n### Get a Basic Random Image\nbash\ncurl \"http://localhost:8686/api/random\"\n\n\n### Filter by Multiple Tags\nRetrieve a random image that has both \"nature\" and \"landscape\" tags.\nbash\ncurl \"http://localhost:8686/api/random?tags=nature,landscape\"\n\n\n### Exclude Specific Content\nFetch a wallpaper image, ensuring it does not have \"nsfw\" or \"private\" tags.\nbash\ncurl \"http://localhost:8686/api/random?tag=wallpaper&exclude=nsfw,private\"\n\n\n### Force Orientation and Format\nRequest a portrait-oriented image in WebP format.\nbash\ncurl \"http://localhost:8686/api/random?orientation=portrait&format=webp\"\n\n\nFor authenticated endpoints like upload or deletion, an `Authorization: Bearer your-api-key` header is required. Refer to the official documentation for more details.\n\n## Why Use It\n\nImageFlow stands out as a comprehensive solution for image management due to several key features:\n\n*   **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.\n*   **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).\n*   **Flexible Storage Options:** ImageFlow supports both local filesystem storage and S3-compatible object storage, offering versatility for different deployment scenarios.\n*   **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.\n*   **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.\n*   **Self-Hosted Control:** By self-hosting ImageFlow, you maintain full control over your image assets and infrastructure.\n\n## Links\n\n*   **GitHub Repository:** [https://github.com/Yuri-NagaSaki/ImageFlow](https://github.com/Yuri-NagaSaki/ImageFlow)\n*   **Docker Hub:** [https://hub.docker.com/r/soyorins/imageflow-backend](https://hub.docker.com/r/soyorins/imageflow-backend)\n*   **CattoPic (Serverless Version):** [https://github.com/Yuri-NagaSaki/CattoPic](https://github.com/Yuri-NagaSaki/CattoPic)","metrics":{"detailViews":7,"githubClicks":14},"dates":{"published":null,"modified":"2026-02-20T21:14:11.000Z"}}