⚠️ DISCLAIMER: EXPERIMENTAL / UNDER DEVELOPMENTThis project is currently in a very early stage of development. It is intended for educational purposes, prototyping, or local experimentation only. It is NOT ready for production use. Features may be incomplete, unstable, or subject to breaking changes. Use at your own risk.
Immagic is a self-hosted web application for intelligent image management. Inspired by Immich & Nextcloud, it features powerful OCR text extraction, lightning-fast full-text search, and a masonry grid interface.
- Real-time OCR: Automatically extracts text from images using Tesseract, making screenshots and documents searchable.
- Reference-Based Library: Scans your existing folder structures without moving or duplicating files.
- Sequential Processing Pipeline: Efficiently crawls directories first, then processes OCR in background batches to ensure UI responsiveness.
- Full-Text Search: Find images instantly by searching for text inside the image or by filename.
- Instant Results: Optimized database queries deliver search results in milliseconds.
- Masonry Grid: Responsive, gap-free image layout that adapts to any screen size.
- Lightbox Viewer: Immersive full-screen viewer with zoom capabilities and metadata inspection (OCR text, file path).
- System Console: A dedicated "Job Queue" dashboard with real-time logs, status indicators, and split-view console for monitoring background tasks.
- Secure Authentication: JWT-based stateless authentication with secure password hashing (Argon2).
- Scalable Architecture: Built on FastAPI and Tortoise ORM (Async), capable of handling massive libraries.
- Background Workers: Heavy lifting is offloaded to Celery workers backed by Redis.
- Backend: Python 3.11+, FastAPI, Tortoise ORM (Async), Celery, Redis, PostgreSQL (Production) / SQLite (Dev).
- Frontend: React 18, Vite, TypeScript, Tailwind CSS, Shadcn/ui, Lucide Icons.
- DevOps: Docker, Docker Compose.
The easiest way to run Immagic is with Docker Compose.
-
Clone the repository
git clone https://github.com/yourusername/immagic.git cd immagic -
Start the stack
docker-compose up --build -d
-
Access the application
- Frontend:
http://localhost:3000 - Backend API:
http://localhost:8000/docs
- Frontend:
-
Initial Setup
- The system will auto-create the database schemas on first run.
- You may need to create an initial admin user (see below).
If you prefer running locally without Docker (e.g., on Windows), follow these steps.
- Python 3.11+
- Node.js 18+
- Redis (Required for background tasks)
- Tesseract OCR (Installed on system path)
cd backend
python -m venv venv
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate
pip install -r requirements.txt
# Create .env file (See backend/.env.example if available, or use defaults)
# Ensure Redis is running locally on port 6379
# Create Admin User
python create_user.py
# Start API Server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadcd backend
# Windows
celery -A app.worker.celery_app worker --pool=solo --loglevel=info
# Linux/Mac
celery -A app.worker.celery_app worker --loglevel=infocd frontend
npm install
npm run dev- Navigate to Settings in the sidebar.
- Enter the Absolute Path to a folder on your server/computer containing images.
- Click Add Path. The system will begin scanning immediately.
- Go to Job Queue.
- Select the active "Scan Directory" job to see real-time logs in the console view.
- Once scanning is complete, go back to Settings and click Start OCR Processing to extract text from the newly found images.
- Use the search bar in the top header.
- Type any text (e.g., "receipt", "error", or text visible in a screenshot).
- Press Enter to filter the gallery.
Contributions are welcome! Please open an issue or submit a pull request.
This project is licensed under the MIT License.