Initial commit

README.md

@@ -0,0 +1,77 @@
+# Sortarr
+
+Sortarr is a self-hosted Jellyfin media organizer and dashboard. It watches `/downloads`, plans safe Jellyfin-friendly moves, chooses one of four mounted media drives, exposes storage, downloads, and library state, and ships with a fully editable vanilla dashboard.
+
+The project is intentionally source-first: backend logic is plain Python, the UI is HTML/CSS/JS, and runtime behavior is configured with `.env`, TOML config files, and optional CSS overrides.
+
+## Quick Start
+
+1. Copy the environment template:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` and set `DOWNLOADS_PATH`, `DRIVE1_PATH`, `DRIVE2_PATH`, `DRIVE3_PATH`, and `DRIVE4_PATH`.
+
+3. Review `config/app.toml`. Keep `SORTARR_DRY_RUN=true` until the generated plans look right.
+
+4. Start the stack:
+
+   ```bash
+   docker compose up --build
+   ```
+
+5. Open `http://localhost:8088`.
+
+Production mode:
+
+```bash
+docker compose -f compose.yaml -f compose.prod.yaml up -d --build
+```
+
+Optional profiles:
+
+```bash
+docker compose --profile cache up -d
+docker compose --profile database up -d
+docker compose --profile tools up -d
+```
+
+## Services
+
+- `web`: nginx serving the editable dashboard from `web/src`.
+- `backend`: Python API plus 24/7 worker loop.
+- `redis`: optional cache profile for future workflow extensions.
+- `postgres`: optional database profile for installations that outgrow JSON state.
+- `media-tools`: optional ffmpeg tools container.
+
+## Mounted Host Paths
+
+- `/downloads`: incoming files.
+- `/media/drive1` through `/media/drive4`: Jellyfin media drives.
+- `/config`: TOML config and custom CSS.
+- `/logs`: rotating backend logs.
+- `/data`: JSON state and scan history.
+
+## Safety Model
+
+Sortarr defaults to dry-run mode. In dry-run mode it scans, parses, chooses drives, computes destination paths, and records planned actions without moving files.
+
+When dry-run is disabled, moves use a temporary `.sorting` destination before the final rename. Existing destinations follow the configured collision rule: `keep-both`, `skip`, or `replace`.
+
+## Permissions
+
+The default Compose file runs the backend with the container default user so a fresh checkout can create logs, state, and media folders without a bootstrap script. On a hardened media host, set ownership on the mounted paths and add a `user: "${SORTARR_UID}:${SORTARR_GID}"` line to the backend service in a local override.
+
+## Customization
+
+Edit these files directly:
+
+- `config/app.toml`: runtime organizer rules and provider settings.
+- `.env`: deployment paths, ports, and intervals.
+- `backend/sortarr/*.py`: parsing, drive choice, scanner, API, provider integrations.
+- `web/src/*.html`, `*.css`, `*.js`: dashboard layout, styling, themes, routes.
+- `config/custom-theme.css`: host-side CSS variable overrides loaded at runtime.
+
+See `docs/configuration.md`, `docs/api.md`, and `docs/operations.md`.