ImageMagick WebGUI

A modern, beautiful web interface for ImageMagick with AI-powered features

Features • Quick Start • Configuration • Documentation • Contributing

---

📽️ Demo Video

imagemagick.mp4

---

✨ Features

🎨 Image Processing

• Resize & Crop - Precise dimensions, percentage scaling, aspect ratio lock
• Format Conversion - WebP, AVIF, JPEG, PNG, GIF, TIFF, PDF support
• Filters & Effects - Blur, Sharpen, Grayscale, Sepia, Brightness, Contrast, Saturation
• Watermark & Text - Custom text overlays with position, opacity, and font size control
• Rotate & Flip - 90°, 180°, 270° rotation with horizontal/vertical flip
• Batch Processing - Process multiple images simultaneously

🤖 AI-Powered Features

• Background Removal - One-click AI background removal using rembg
• Auto Enhance - Automatic image enhancement (normalize, saturation, sharpening)
• Smart Upscaling - 2x/4x resolution upscaling with LANCZOS algorithm

🖥️ User Interface

• Notion-inspired Design - Ultra-clean, minimalist white interface
• Real-time Preview - See changes before applying
• Drag & Drop Upload - Easy multi-file upload
• Image Editor - Full-featured editor with live preview
• Terminal Mode - Direct ImageMagick command input for power users
• Dark/Light Mode - Automatic or manual theme switching
• PWA Support - Install as desktop/mobile app

🔧 Technical

• Docker Ready - One command deployment
• Type-Safe - Full TypeScript + Pydantic validation
• Secure - Command whitelist, timeouts, resource limits
• Queue System - Redis-based job queue for heavy operations
• History - Track all processed images with re-download option

---

🚀 Quick Start

mkdir imagemagick-webgui && cd imagemagick-webgui
curl -O https://raw.githubusercontent.com/PrzemekSkw/imagemagick-webui/main/docker-compose.example.yml
mv docker-compose.example.yml docker-compose.yml
docker compose up -d

Access: http://localhost:3000

📖 Need custom ports, authentication, or reverse proxy? See Installation Guide

⚠️ Production: Change SECRET_KEY and JWT_SECRET in docker-compose.yml before deploying!

📖 Documentation

Default Ports

Service	Port	Description
Frontend	3000	Next.js web interface
Backend	8000	FastAPI REST API
PostgreSQL	5432	Database (internal)
Redis	6379	Queue system (internal)

API Documentation

Once running, access the interactive API docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Architecture

┌─────────────────┐     ┌─────────────────┐
│   Next.js 15    │────▶│    FastAPI      │
│   (Frontend)    │     │   (Backend)     │
│   Port: 3000    │     │   Port: 8000    │
└─────────────────┘     └────────┬────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
              ┌─────▼─────┐           ┌───────▼───────┐
              │ PostgreSQL│           │     Redis     │
              │   (DB)    │           │   (Queue)     │
              │ Port: 5432│           │  Port: 6379   │
              └───────────┘           └───────────────┘
                                              │
                                      ┌───────▼───────┐
                                      │  RQ Worker    │
                                      │ (Background)  │
                                      └───────────────┘

Supported Operations

Operation	Parameters	Example
resize	width, height, percent, fit	{"width": 800, "height": 600}
crop	x, y, width, height	{"x": 0, "y": 0, "width": 500, "height": 500}
rotate	degrees	{"degrees": 90}
flip	direction	{"direction": "horizontal"}
blur	sigma	{"sigma": 10}
sharpen	sigma	{"sigma": 2}
brightness	value	{"value": 120}
contrast	value	{"value": 110}
saturation	value	{"value": 130}
grayscale	-	{}
sepia-tone	threshold	{"threshold": 80}
watermark	text, position, font_size, opacity	{"text": "©2024", "position": "southeast"}
format	format, quality	{"format": "webp", "quality": 85}

Terminal Mode

For advanced users, use Terminal Mode to run raw ImageMagick commands:

# Convert to WebP with quality
magick input.jpg -quality 80 output.webp

# Create thumbnail
magick input.jpg -thumbnail 300x300 output.jpg

# Add border
magick input.jpg -border 10x10 -bordercolor "#ff0000" output.jpg

# Composite images
magick base.jpg overlay.png -composite output.jpg

---

📸 Screenshots

Click to view screenshots

Dashboard

Image Editor

Dark Mode

Settings

---

🛠️ Development

Local Development (without Docker)

Backend:

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Project Structure

imagemagick-webui/
├── backend/
│   ├── app/
│   │   ├── api/          # API endpoints
│   │   ├── core/         # Config, security, database
│   │   ├── models/       # SQLAlchemy models
│   │   ├── services/     # Business logic
│   │   └── workers/      # Background tasks
│   ├── tests/
│   └── requirements.txt
├── frontend/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   │   ├── features/     # Feature components
│   │   ├── layout/       # Layout components
│   │   └── ui/           # UI primitives (shadcn/ui)
│   └── lib/              # Utilities, API client, store
├── docker-compose.yml
├── Dockerfile
└── README.md

---

🔒 Security

• Command Whitelist - Only allowed ImageMagick operations
• Input Validation - Pydantic models for all inputs
• Resource Limits - Memory (2GB), timeout (300s), disk limits
• File Validation - MIME type and extension checking
• Rate Limiting - Configurable request limits
• Non-root Container - Runs as unprivileged user

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💖 Support

If you find this project useful, please consider supporting its development:

Your support helps maintain and improve this project. Thank you! ❤️

---

⭐ Star History

---

🙏 Acknowledgments

• ImageMagick - The powerful image processing library
• rembg - AI background removal
• Next.js - React framework
• FastAPI - Python web framework
• shadcn/ui - Beautiful UI components
• Tailwind CSS - Utility-first CSS

---

Made with ❤️ by PrzemekSkw