A modern, self-hosted Linux ISO download manager with real-time progress tracking and verification.
Grid view showing completed ISO downloads
List view with sortable columns
Real-time download progress tracking
Statistics dashboard with charts
Add new ISO download form
HTTP file browser for direct downloads
ISOMan is a web-based application that allows you to download, verify, and serve Linux ISOs (and other disk images) over HTTP. It provides a clean, modern interface to manage your ISO downloads with features like automatic checksum verification, real-time progress updates via WebSocket, and organized file storage.
Perfect for:
- Homelab enthusiasts managing multiple Linux distributions
- System administrators maintaining ISO libraries
- DevOps teams needing centralized ISO storage
- Anyone tired of manually downloading and organizing ISOs
- Multiple File Format Support: Download ISO, QCOW2, VMDK, VDI, IMG, and other disk image formats
- Organized Storage: Automatic organization by distribution name, version, and architecture
- Checksum Verification: Automatic SHA256/SHA512/MD5 verification during download
- Real-time Progress: WebSocket-based live progress updates for all downloads
- Concurrent Downloads: Configurable worker pool for parallel downloads
- Modern UI: Clean, responsive interface with dark mode support
- Grid and List Views: Flexible viewing options with sorting and pagination
- Apache-style Directory Listing: Browse and download files directly via HTTP
- RESTful API: Full API access for automation and integration
- Single Container Deployment: Easy deployment with Docker
- Go - High-performance backend server
- Gin - HTTP web framework
- SQLite (modernc.org/sqlite) - Pure Go, CGO-free database
- WebSocket - Real-time progress updates
- React + TypeScript - Modern UI framework
- Vite + Rsbuild - Fast build tooling
- Tailwind CSS - Utility-first styling
- Zustand - Global state management
- TanStack Query - Server state management
- TanStack Table - Advanced data grid
- React Router - Client-side routing
- Bun - Fast JavaScript runtime and package manager
- Go 1.22+ (for backend development)
- Bun (for frontend development)
- Docker (for containerized deployment)
-
Clone the repository
git clone https://github.com/yourusername/isoman.git cd isoman -
Start the backend
cd backend go run main.goBackend will be available at
http://localhost:8080 -
Start the frontend (in a new terminal)
cd ui bun install bun run devFrontend will be available at
http://localhost:3000
-
Build the image
docker build -t isoman . -
Run the container
docker run -d \ -p 8080:8080 \ -v isoman-data:/data \ --name isoman \ isoman
-
Access the application Open
http://localhost:8080in your browser
- Click the "Add ISO" button
- Fill in the details:
- Name: Distribution name (e.g., "Ubuntu")
- Version: Version number (e.g., "24.04")
- Architecture: CPU architecture (e.g., "x86_64")
- Edition (optional): Variant (e.g., "desktop", "server")
- Download URL: Direct link to the ISO file
- Checksum URL (optional): Link to checksum file for verification
- Click "Download" to start
- Watch real-time progress in the ISO cards
- See download status: pending, downloading, verifying, complete, or failed
- Retry failed downloads with one click
- Via UI: Click "Download" button on completed ISOs
- Via HTTP: Navigate to
/images/for directory listing - Direct Link: Use the copy button to get direct download URLs
┌─────────────┐
│ Browser │
└──────┬──────┘
│ HTTP/WS
▼
┌─────────────────────────────────────┐
│ Gin Web Server │
│ ┌──────────┐ ┌────────────────┐ │
│ │ REST API │ │ WebSocket Hub │ │
│ └──────────┘ └────────────────┘ │
└───────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Download Manager │
│ ┌──────────────────────────────┐ │
│ │ Worker Pool (concurrent) │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │Worker 1│ │Worker 2│ │ │
│ │ └────────┘ └────────┘ │ │
│ └──────────────────────────────┘ │
└───────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ SQLite Database │
│ (Pure Go, no CGO required) │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ File System Storage │
│ data/isos/{name}/{version}/{arch}/│
└─────────────────────────────────────┘
data/isos/
├── alpine/
│ └── 3.19.1/
│ └── x86_64/
│ ├── alpine-3.19.1-x86_64.iso
│ └── alpine-3.19.1-x86_64.iso.sha256
├── ubuntu/
│ └── 24.04/
│ └── x86_64/
│ ├── ubuntu-24.04-desktop-x86_64.iso
│ └── ubuntu-24.04-server-x86_64.iso
See docs/API.md for complete API documentation.
Quick example:
# Create a download
curl -X POST http://localhost:8080/api/isos \
-H "Content-Type: application/json" \
-d '{
"name": "Alpine Linux",
"version": "3.19.1",
"arch": "x86_64",
"download_url": "https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-standard-3.19.1-x86_64.iso",
"checksum_url": "https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-standard-3.19.1-x86_64.iso.sha256"
}'
# List all ISOs
curl http://localhost:8080/api/isos- API Reference - Complete REST API documentation
- Deployment Guide - Production deployment instructions
- CLAUDE.md - AI assistant context and project structure
Backend:
PORT- HTTP server port (default:8080)DATA_DIR- Base data directory (default:./data)WORKER_COUNT- Number of concurrent download workers (default:2)
Frontend:
PUBLIC_API_URL- Backend API URL (default:http://localhost:8080)PUBLIC_WS_URL- WebSocket URL (default:ws://localhost:8080/ws)
cd backend
go run main.go # Run development server
go build -o server . # Build production binary
go test ./... # Run tests
go mod tidy # Clean up dependenciescd ui
bun install # Install dependencies
bun run dev # Start dev server
bun run build # Production build
bun run preview # Preview production build
bun run lint # Lint codeContributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details
For issues, questions, or suggestions, please open an issue on GitHub.