ImageFlow is an efficient image service system designed for modern websites and applications. It automatically provides the most suitable images based on device type and supports modern image formats like WebP and AVIF, significantly improving website performance and user experience.
- API Key Authentication: Secure API key verification mechanism to protect your image upload functionality
- Adaptive Image Service: Automatically provides landscape or portrait images based on device type (desktop/mobile)
- Modern Format Support: Automatically detects browser compatibility and serves WebP or AVIF format images
- Image Expiration: Set expiration times for images with automatic deletion when expired (works with both local and S3 storage)
- Simple API: Get random images through simple API calls with tag filtering support
- User-Friendly Upload Interface: Drag-and-drop upload interface with dark mode support, real-time preview, and tag management
- Image Management: View, filter, and delete images with an intuitive management interface
- Automatic Image Processing: Automatically detects image orientation and converts to multiple formats after upload
- Asynchronous Processing: Image conversion happens in the background without affecting the main service
- High Performance: Optimized for network performance to reduce loading time
- Easy Deployment: Simple configuration and deployment process
- Multiple Storage Support: Supports local storage and S3-compatible storage (like R2)
- Redis Support: Optional Redis integration for metadata and tags storage with improved performance
- Go 1.22 or higher
- Node.js 18 or higher (for frontend build)
- WebP tools (
libwebp-tools) - AVIF tools (
libavif-apps) - Redis (optional, for metadata and tags storage)
- Docker and Docker Compose (optional, for containerized deployment)
- Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow- Build frontend
cd frontend
bash build.sh- Build backend
go mod tidy
go build -o imageflow- Configure environment variables
cp .env.example .env
# Edit the .env file with your configuration- Set up system service (example using systemd)
[Unit]
Description=ImageFlow Service
After=network.target
[Service]
ExecStart=/path/to/imageflow
WorkingDirectory=/path/to/imageflow/directory
Restart=always
User=youruser
EnvironmentFile=/path/to/imageflow/.env
[Install]
WantedBy=multi-user.target- Enable the service
sudo systemctl enable imageflow
sudo systemctl start imageflow- Using pre-built image (recommended)
# 1. Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow
# 2. Configure environment
cp .env.example .env
# Edit the .env file
# 3. Start service
docker compose -f docker-compose-separate.yaml up -d- Local build deployment
# 1. Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow
# 2. Configure environment
cp .env.example .env
# Edit the .env file
# 3. Build and start
docker compose -f docker-compose-separate-build.yaml up --build -d# 1. Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow
# 2. Configure environment
cp .env.example .env
# Edit the .env file
# 3. Start service
docker compose -f docker-compose.yaml up -dConfigure the system by creating and editing the .env file. Here are the main configuration options:
# API Key Configuration
API_KEY=your_api_key_here # Set your API key
# Storage Configuration
STORAGE_TYPE=local # Storage type: local or s3 (S3-compatible storage)
METADATA_STORE_TYPE=redis # Type of metadata storage to use (currently only redis is supported)
LOCAL_STORAGE_PATH=static/images # Local storage path
# Redis Configuration
REDIS_ENABLED=true # Enable Redis for metadata and tags storage
REDIS_HOST=localhost # Redis server host
REDIS_PORT=6379 # Redis server port
REDIS_PASSWORD= # Redis password
REDIS_DB=0 # Redis database number
REDIS_TLS_ENABLED=false # Enable TLS for Redis connection
# S3 Storage Configuration (required when STORAGE_TYPE=s3)
S3_ENDPOINT= # S3 endpoint address
S3_REGION= # S3 region
S3_ACCESS_KEY= # Access key
S3_SECRET_KEY= # Secret key
S3_BUCKET= # Bucket name
CUSTOM_DOMAIN= # Custom domain
# Image Processing Configuration
MAX_UPLOAD_COUNT=20 # Maximum upload count per request
IMAGE_QUALITY=80 # Image quality (1-100)
WORKER_THREADS=4 # Number of parallel processing threads
SPEED=5 # Encoding speed (0-8)
# Parameters needed only for frontend-backend separation
#NEXT_PUBLIC_API_URL=http://localhost:8686 # Backend URL
NEXT_PUBLIC_API_URL=
# Backend URL and image domain (not needed if using local storage)
NEXT_PUBLIC_REMOTE_PATTERNS=If you enable Redis after previously using file-based metadata storage, you can migrate your metadata to Redis:
# Run the migration tool
bash migrate.sh
# Force migration even if it was already completed
bash migrate.sh --force
# Specify a custom .env file
bash migrate.sh --env /path/to/.envGet random images through the API (no API key required):
GET http://localhost:8686/api/random
GET http://localhost:8686/api/random?tag=nature
The system returns the most suitable image based on the device type and browser support in request headers. You can also filter random images by tags.
| Endpoint | Method | Description | Parameters | Authentication |
|---|---|---|---|---|
/api/random |
GET | Get a random image | tag: Optional, filter by tag |
Not required |
/api/upload |
POST | Upload new images | Form data, field name "images[]" Optional: expiryMinutes (expiration time in minutes)Optional: tags (array of tags) |
API key required |
/api/delete-image |
POST | Delete an image and all its formats | JSON with id and storageType |
API key required |
/api/validate-api-key |
POST | Validate API key | API key in request header | |
/api/images |
GET | List all uploaded images | Optional: tag (filter by tag) |
API key required |
/api/config |
GET | Get system configuration | None | API key required |
/api/trigger-cleanup |
POST | Manually trigger cleanup of expired images | None | API key required |
/api/tags |
GET | Get all available tags | None | API key required |
/api/debug/tags |
GET | Get detailed tag information | None | API key required |
ImageFlow/
โโโ .github/ # GitHub related configurations
โโโ cmd/ # Command-line tools
โ โโโ migrate/ # Metadata migration tool
โโโ config/ # Configuration related code
โ โโโ config.go # Main configuration definitions
โโโ docs/ # Documentation and images
โ โโโ img/ # Documentation images
โโโ favicon/ # Favicon assets
โโโ frontend/ # Next.js frontend application
โ โโโ app/ # Next.js app directory
โ โ โโโ components/ # React components
โ โ โ โโโ ImageDetail/ # Image detail components
โ โ โ โโโ ui/ # UI common components
โ โ โ โโโ upload/ # Upload related components
โ โ โโโ hooks/ # React hooks
โ โ โโโ manage/ # Management page
โ โ โโโ types/ # TypeScript type definitions
โ โ โโโ utils/ # Frontend utility functions
โ โโโ public/ # Public assets
โ โโโ next.config.mjs # Next.js configuration file
โ โโโ package.json # Frontend dependencies
โ โโโ build.sh # Unix build script
โ โโโ build.bat # Windows build script
โโโ handlers/ # HTTP request handlers
โ โโโ auth.go # Authentication handlers
โ โโโ config_handler.go # Configuration API handlers
โ โโโ debug.go # Debug information handlers
โ โโโ delete.go # Image deletion handlers
โ โโโ image.go # Image handlers
โ โโโ list.go # Listing handlers
โ โโโ random.go # Random image handlers
โ โโโ tags.go # Tag handlers
โ โโโ upload.go # Upload handlers
โโโ logs/ # Application logs directory
โโโ scripts/ # Utility scripts
โโโ static/ # Static files and image storage
โ โโโ _next/ # Next.js static assets
โ โโโ images/ # Image storage directory
โ โโโ landscape/ # Landscape images
โ โ โโโ avif/ # AVIF format
โ โ โโโ webp/ # WebP format
โ โโโ portrait/ # Portrait images
โ โ โโโ avif/ # AVIF format
โ โ โโโ webp/ # WebP format
โ โโโ original/ # Original images
โ โ โโโ landscape/ # Original landscape
โ โ โโโ portrait/ # Original portrait
โ โโโ gif/ # GIF format images
โ โโโ metadata/ # Image metadata (including expiration information)
โโโ utils/ # Backend utility functions
โ โโโ cleaner.go # Expired image cleanup
โ โโโ converter_bimg.go # Image conversion
โ โโโ device.go # Device detection
โ โโโ helpers.go # Helper functions
โ โโโ image.go # Image processing
โ โโโ metadata.go # Metadata handling
โ โโโ redis.go # Redis client and operations
โ โโโ s3client.go # S3 storage client
โ โโโ storage.go # Storage interface
โ โโโ worker_pool.go # Asynchronous worker pool
โ โโโ errors/ # Error handling
โ โโโ logger/ # Logging system
โโโ .cursor/ # Cursor editor rules and configurations
โโโ .env # Environment variables
โโโ .env.example # Example environment configuration
โโโ Dockerfile # Main Docker configuration
โโโ Dockerfile.backend # Backend Docker configuration
โโโ Dockerfile.frontend # Frontend Docker configuration
โโโ docker-compose.yaml # Docker Compose configuration
โโโ docker-compose-build.yml # Docker Compose build configuration
โโโ docker-compose-separate.yaml # Frontend-Backend separated configuration
โโโ docker-compose-separate-build.yaml # Frontend-Backend separated build
โโโ migrate.sh # Metadata migration script
โโโ go.mod # Go module file
โโโ go.sum # Go module checksum
โโโ main.go # Main application entry
โโโ README.md # English project documentation
โโโ README_zh.md # Chinese project documentation
โโโ contributing.md # Contribution guidelines
โโโ LICENSE # License information
This project is licensed under the MIT License - see the LICENSE file for details.
Blog - ็ซ็ซๅๅฎข
Project Link: https://github.com/Yuri-NagaSaki/ImageFlow
YXVM sponsored this project
NodeSupport sponsored this project
โญ If you like this project, please give it a star! โญ
Made with โค๏ธ by Yuri NagaSaki