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
- Simple API: Get random images through simple API calls
- User-Friendly Upload Interface: Drag-and-drop upload interface with dark mode support and real-time preview
- 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)
- Security: API key verification mechanism ensures secure access to image upload functionality
- Format Conversion: Automatically converts uploaded images to WebP and AVIF formats, reducing file size by 30-50%
- Device Adaptation: Provides the most suitable image orientation for different devices
- Hot Reload: Uploaded images are immediately available without service restart
- Concurrent Processing: Efficiently handles image conversion using Go's concurrency features
- Scalability: Modular design for easy extension and customization
- Responsive Design: Perfect adaptation for desktop and mobile devices
- Dark Mode Support: Automatically adapts to system theme with manual toggle option
- Flexible Storage: Supports local and S3-compatible storage, easily configured via .env file
- Go 1.16 or higher
- WebP tools (
cwebp) - AVIF tools (
avifenc) - Docker and Docker Compose (optional, for containerized deployment)
- Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow- Initialize Go modules
go mod init github.com/Yuri-NagaSaki/ImageFlow
go mod tidy- Build the project
go build -o imageflow- 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
[Install]
WantedBy=multi-user.target- Enable the service
sudo systemctl enable imageflow
sudo systemctl start imageflow- Clone the repository and enter the directory
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow- Configure the
.envfile
cp .env.example .env
# Edit the .env file with your configuration- Start the service using Docker Compose
docker compose up -dThe service will start at http://localhost:8686.
Configure the system by creating and editing the .env file:
# API Keys
API_KEY=your_api_key_here
# Storage Configuration
STORAGE_TYPE=local # Options: local, s3
LOCAL_STORAGE_PATH=static/images
# S3 Configuration (required when STORAGE_TYPE=s3)
S3_ENDPOINT=
S3_REGION=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=
# Custom Domain (optional)
CUSTOM_DOMAIN=- Service runs on port 8686 by default
- Image files are persisted through volumes
.envfile is mounted via volumes for system configuration- WebP and AVIF conversion tools are automatically included
- Health check support
- Storage type (local or s3) configured via
STORAGE_TYPEin.envfile
Image upload functionality requires API key authentication. You can:
- Set the API key in the
.envfile - Enter the API key through the web interface
- The API key will be saved after successful verification
Access the upload interface at http://localhost:8686/. You can:
- Drag and drop images to the upload area
- Click to select images for upload
- Preview selected images in real-time
- System automatically detects if images are landscape or portrait
- After upload, images are automatically converted to WebP and AVIF formats
Get random images through the API (no API key required):
GET http://localhost:8686/api/random
The system returns the most suitable image based on the device type and browser support in request headers.
| Endpoint | Method | Description | Parameters | Authentication |
|---|---|---|---|---|
/api/random |
GET | Get a random image | orientation: Optional, specify "landscape" or "portrait" |
Not required |
/upload |
POST | Upload new images | Form data, field name "images[]" | API key required |
/validate-api-key |
POST | Validate API key | API key in request header | Not required |
ImageFlow/
├── config/ # Configuration related code
├── handlers/ # HTTP handlers
├── scripts/ # Utility scripts
├── static/ # Static files and image storage
│ ├── favicon.ico # Favicon
│ ├── favicon.svg # SVG favicon
│ ├── favicon-16.png # 16px favicon
│ ├── favicon-32.png # 32px favicon
│ ├── favicon-48.png # 48px favicon
│ ├── imageflow1.png # Preview image 1
│ ├── imageflow2.png # Preview image 2
│ ├── images/ # Image storage directory
│ │ ├── landscape/ # Landscape images
│ │ │ ├── avif/ # AVIF format
│ │ │ └── webp/ # WebP format
│ │ ├── portrait/ # Portrait images
│ │ │ ├── avif/ # AVIF format
│ │ │ └── webp/ # WebP format
│ │ └── original/ # Original uploaded images
│ ├── index.html # Homepage
│ ├── styles.css # Stylesheet
│ └── upload.js # Upload functionality script
├── utils/ # Utility functions
├── main.go # Main program entry
├── Dockerfile # Docker build file
├── docker-compose.yml # Docker Compose configuration
├── .env # Environment variables
└── README.md # Project documentation
Contributions are welcome! Feel free to submit code, report issues, or suggest improvements!
This project is licensed under the MIT License - see the LICENSE file for details.
Yuri NagaSaki - @YuriNagaSaki
Project Link: https://github.com/Yuri-NagaSaki/ImageFlow
⭐ If you like this project, please give it a star! ⭐
Made with ❤️ by Yuri NagaSaki