Config-driven web scanning platform that wraps SANE scanners behind a modern Vue 3 UI with real-time job tracking, workflows, and pluggable integrations (Paperless-ngx, Home Assistant, and more).
- 🚀 Fast setup with a published Docker image: ghcr.io/mindcollaps/scanit:latest
- 🧠 Config-first behavior with live reload
- 📷 ADF + flatbed support with real-time page previews
- 🧩 Integrations for Paperless-ngx and Home Assistant
- 🐳 Works as a single container with host networking for scanner discovery
| Scan Workflow | History |
|---|---|
 |
 |
| Integrations |
|---|
 |
Suggested real captures:
- Main scan page during an active multi-page scan
- Job history with mixed statuses and actions visible
- Job detail page with page thumbnails and final PDF download
- Integrations/config page showing Paperless and Home Assistant setup
Requirements:
- Linux host (required for network_mode: host)
- Docker + Docker Compose v2
- Create a folder and move into it:
mkdir -p scanit && cd scanit- Create docker-compose.yml and paste this:
services:
scanit:
image: ghcr.io/mindcollaps/scanit:latest
restart: unless-stopped
network_mode: host
environment:
SCANIT_CONFIG_DIR: /config
volumes:
- ./config:/config
- ./.data/output:/data/output
- ./.data/db:/data/db
- sane_config:/etc/sane.d
- /var/run/dbus:/var/run/dbus
- /run/avahi-daemon/socket:/run/avahi-daemon/socket
volumes:
sane_config:- Start it:
docker compose up -d- Open: http://localhost:8863
On first start, ScanIt automatically creates /config/00-system.yaml and /config/scanit.yaml for you.
If you prefer a plain docker command:
mkdir -p scanit/config scanit/.data/output scanit/.data/db && cd scanit
docker volume create scanit_sane_config
docker run -d --name scanit \
--restart unless-stopped \
--network host \
-e SCANIT_CONFIG_DIR=/config \
-v "$PWD/config:/config" \
-v "$PWD/.data/output:/data/output" \
-v "$PWD/.data/db:/data/db" \
-v scanit_sane_config:/etc/sane.d \
-v /var/run/dbus:/var/run/dbus \
-v /run/avahi-daemon/socket:/run/avahi-daemon/socket \
ghcr.io/mindcollaps/scanit:latestUseful commands:
docker logs -f scanit
docker stop scanit
docker rm scanit- Open the Scan page.
- Select scanner and preset.
- Start scan and watch real-time progress.
- Download PDF or route to your configured destination.
Config is loaded from /config and merged alphabetically.
| File | Purpose |
|---|---|
| 00-system.yaml | System defaults (keep as provided) |
| scanit.yaml | Your scanners, presets, workflows, integrations |
Tips:
- Changes hot-reload automatically.
- Use examples/ for complete scenarios.
- Full schema: docs/CONFIG_SCHEMA.md
ScanIt ships with two built-in integration paths for automation and document archiving.
Home Assistant integration uses MQTT Discovery to create scan trigger buttons and status entities directly in HA.
- Best for one-tap scans from dashboards or mobile.
- Supports multiple scan buttons mapped to different presets.
- Works with mode cycling for held workflows (default, double_sided, endless).
Minimal structure in scanit.yaml:
integrations:
homeassistant:
enabled: true
mqtt:
brokerUrl: "mqtt://localhost:1883"
username: "${MQTT_USER}"
password: "${MQTT_PASS}"
discovery:
prefix: "homeassistant"
deviceName: "ScanIt"
deviceId: "scanit"
buttons:
- id: "scan_quick"
label: "Quick Scan"
presetId: "doc_300_color"Full example: examples/scanit.homeassistant.yaml
Paperless integration uploads completed scans as PDF documents to one or more Paperless-ngx instances.
- Supports multiple named Paperless instances.
- Uses tokenEnv values so API tokens stay in environment variables.
- Consumer type format: paperless:id
Minimal structure in scanit.yaml:
integrations:
paperless:
- id: shared
label: "Shared Archive"
baseUrl: "https://paperless.example.com"
tokenEnv: "PAPERLESS_SHARED_TOKEN"
timeoutMs: 30000
verifyTls: trueFull example: examples/scanit.paperless.yaml
Use this mode when you want to modify source code or build your own image.
git clone https://github.com/MindCollaps/ScanIt.git
cd ScanIt
docker compose -f docker-compose.build.yml up --build -dRepo compose files:
- docker-compose.yml: run the published GHCR image
- docker-compose.build.yml: build from local source
- docker-compose.dev.yml: development stack with hot reload
Configured scripts from package.json:
| Script | Description |
|---|---|
| bun run build | Build server and client |
| bun run build:server | Compile server TypeScript |
| bun run build:client | Build client with Vite |
| bun dev | Start development compose stack |
| bun run dev:inside | Run server and client concurrently |
| bun run dev:server | Watch server |
| bun run dev:client | Vite dev server on 0.0.0.0:5173 |
| bun run typecheck | Type-check server + client |
| bun run lint | ESLint + Stylelint |
| bun run lint:fix | Auto-fix linting issues |
| bun run format | Prettier write |
| bun run format:check | Prettier check |
| bun run ci | typecheck + lint + format:check |
| bun run start | Run dist/server/index.js |
Health and Config
- GET /healthz
- GET /readyz
- GET /api/config/status
- GET /api/config/runtime
Scanners and Presets
- GET /api/scanners
- POST /api/scanners/discover
- GET /api/scanners/discovered
- GET /api/scanners/discovered/:id/capabilities
- GET /api/scanners/diagnostics
- GET /api/presets
- GET /api/presets/user
- POST /api/presets
- PUT /api/presets/:id
- DELETE /api/presets/:id
Jobs and History
- POST /api/jobs
- GET /api/jobs/:id
- GET /api/jobs/:id/pages
- GET /api/jobs/:id/pages/:index
- GET /api/jobs/:id/pages/by-name/:filename
- GET /api/jobs/:id/pdf
- PUT /api/jobs/:id/filename
- POST /api/jobs/:id/append
- PUT /api/jobs/:id/pages/reorder
- POST /api/jobs/:id/pages/interleave
- DELETE /api/jobs/:id
- POST /api/jobs/batch-delete
- GET /api/history
Realtime
- GET /api/events
- docs/ARCHITECTURE.md - architecture and module boundaries
- docs/CONFIG_SCHEMA.md - configuration reference
- docs/PROJECT_PLAN.md - implementation plan
- docs/AI_GUIDE.md - contributor guide for AI assistants
- Runtime: Bun
- Backend: Express 5, TypeScript, Zod v4, pino
- Frontend: Vue 3 (Composition API), Vite 7, vue-router
- Database: bun:sqlite
- Scanner: SANE (scanimage and scanadf)
- Container: Docker
ISC