rob thijssen
f63a8d7647
- Add COPR build status badge at the top - Add "Install from COPR" as the first section - Add systemd service install instructions for headless server - Add listen_addr to server config example - Consolidate build instructions (no tauri-cli needed for release) - Add monsoon-server to manual install section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
172 lines
5.6 KiB
Markdown
172 lines
5.6 KiB
Markdown
# Monsoon
|
|
|
|
[](https://copr.fedorainfracloud.org/coprs/grenade/monsoon/package/monsoon/)
|
|
|
|
A fast BitTorrent client for the GNOME desktop and headless servers, built on the [Vortex](https://github.com/Nehliin/vortex) io-uring engine.
|
|
|
|
Two interfaces:
|
|
- **Desktop app** -- Tauri + Svelte GUI with GNOME integration
|
|
- **Headless server** -- REST API + WebSocket + web GUI for remote/LAN deployment
|
|
|
|
## Install from COPR (Fedora)
|
|
|
|
```bash
|
|
sudo dnf copr enable grenade/monsoon
|
|
sudo dnf install monsoon # desktop app
|
|
sudo dnf install monsoon-server # headless server
|
|
```
|
|
|
|
## Screenshots
|
|
|
|
### Torrent List
|
|
|
|
|
|
### Activity
|
|
|
|
|
|
### Details
|
|
|
|
|
|
### Files
|
|
|
|
|
|
## Building from Source
|
|
|
|
### Dependencies (Fedora)
|
|
|
|
```bash
|
|
sudo dnf install rust cargo gcc nodejs pnpm \
|
|
gtk3-devel webkit2gtk4.1-devel libsoup3-devel \
|
|
pango-devel gdk-pixbuf2-devel glib2-devel libappindicator-gtk3-devel
|
|
```
|
|
|
|
The GTK dependencies are only needed for the desktop app. The headless server only requires `rust`, `cargo`, and `gcc`.
|
|
|
|
### Desktop App
|
|
|
|
```bash
|
|
pnpm install && pnpm build # build frontend
|
|
cargo build --release -p monsoon # build desktop binary (embeds frontend)
|
|
```
|
|
|
|
For development with hot-reload: `cargo install tauri-cli && cargo tauri dev`
|
|
|
|
### Headless Server
|
|
|
|
```bash
|
|
cd monsoon-web && pnpm install && pnpm build && cd ..
|
|
cargo build --release -p monsoon-server
|
|
```
|
|
|
|
### Manual Install
|
|
|
|
```bash
|
|
sudo install -Dm755 target/release/monsoon /usr/local/bin/monsoon
|
|
sudo install -Dm755 target/release/monsoon-server /usr/local/bin/monsoon-server
|
|
sudo install -Dm644 data/cafe.lair.monsoon.desktop /usr/share/applications/cafe.lair.monsoon.desktop
|
|
sudo install -Dm644 data/cafe.lair.monsoon.metainfo.xml /usr/share/metainfo/cafe.lair.monsoon.metainfo.xml
|
|
sudo install -Dm644 src-tauri/icons/icon.png /usr/share/icons/hicolor/256x256/apps/cafe.lair.monsoon.png
|
|
sudo install -Dm644 src-tauri/icons/128x128.png /usr/share/icons/hicolor/128x128/apps/cafe.lair.monsoon.png
|
|
sudo install -Dm644 src-tauri/icons/32x32.png /usr/share/icons/hicolor/32x32/apps/cafe.lair.monsoon.png
|
|
sudo gtk-update-icon-cache /usr/share/icons/hicolor/
|
|
```
|
|
|
|
## Headless Server
|
|
|
|
### Running
|
|
|
|
```bash
|
|
# With web GUI (run from the repo root, or set MONSOON_WEB_DIR)
|
|
monsoon-server
|
|
|
|
# Or with explicit web asset path
|
|
MONSOON_WEB_DIR=/path/to/monsoon-web/dist monsoon-server
|
|
```
|
|
|
|
The server listens on `0.0.0.0:3000` by default. Open `http://server-ip:3000` in a browser for the web GUI.
|
|
|
|
### Systemd
|
|
|
|
```bash
|
|
sudo install -Dm644 data/monsoon-server.service /usr/lib/systemd/system/monsoon-server.service
|
|
sudo systemctl enable --now monsoon-server
|
|
```
|
|
|
|
### REST API
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/api/torrents` | List all torrents |
|
|
| `GET` | `/api/torrents/:id` | Get torrent details |
|
|
| `POST` | `/api/torrents` | Add torrent (JSON: magnet or file path) |
|
|
| `POST` | `/api/torrents/upload` | Upload a .torrent file (multipart) |
|
|
| `DELETE` | `/api/torrents/:id` | Remove torrent |
|
|
| `POST` | `/api/torrents/:id/pause` | Pause torrent |
|
|
| `POST` | `/api/torrents/:id/resume` | Resume torrent |
|
|
| `GET` | `/api/config` | Get server configuration |
|
|
| `PUT` | `/api/config` | Update server configuration |
|
|
|
|
#### Examples
|
|
|
|
```bash
|
|
# Add a magnet link
|
|
curl -X POST http://localhost:3000/api/torrents \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"type": "magnet", "magnet": "magnet:?xt=urn:btih:..."}'
|
|
|
|
# Upload a .torrent file
|
|
curl -X POST http://localhost:3000/api/torrents/upload \
|
|
-F "file=@/path/to/file.torrent"
|
|
|
|
# List torrents
|
|
curl http://localhost:3000/api/torrents | jq
|
|
|
|
# Pause a torrent
|
|
curl -X POST http://localhost:3000/api/torrents/TORRENT_ID/pause
|
|
```
|
|
|
|
### WebSocket
|
|
|
|
Connect to `ws://server-ip:3000/ws` for real-time event streaming. Events are JSON:
|
|
|
|
```json
|
|
{"type": "metrics", "id": "...", "downloadSpeed": 1234, "uploadSpeed": 56, "numPeers": 12, "piecesCompleted": 42}
|
|
{"type": "stateChanged", "id": "...", "newState": "seeding", "name": "..."}
|
|
{"type": "metadataComplete", "id": "...", "name": "...", "totalPieces": 100, "totalSize": 1073741824}
|
|
```
|
|
|
|
### Queue Management
|
|
|
|
Configure in `~/.config/monsoon/config.toml`:
|
|
|
|
```toml
|
|
[server]
|
|
listen_addr = "0.0.0.0:3000"
|
|
max_concurrent_downloads = 3
|
|
min_peers_before_queue = 2
|
|
seed_completed_by_default = true
|
|
webhook_url = "http://localhost:8080/hook"
|
|
```
|
|
|
|
- **listen_addr** -- HTTP API and web GUI listen address (default `0.0.0.0:3000`)
|
|
- **max_concurrent_downloads** -- new torrents are queued when all slots are full; the next queued torrent auto-starts when a slot frees up
|
|
- **min_peers_before_queue** -- if a torrent has fewer peers than this and download speed is below 1 KiB/s for 30 consecutive seconds, it rotates to the back of the queue
|
|
- **seed_completed_by_default** -- when `false`, completed torrents are paused instead of seeding
|
|
- **webhook_url** -- POST a JSON payload to this URL when a torrent completes (for automation: Jellyfin scans, file movers, etc.)
|
|
|
|
## Configuration
|
|
|
|
Monsoon follows XDG directory conventions:
|
|
|
|
| Purpose | Path |
|
|
|---------|------|
|
|
| Config | `~/.config/monsoon/config.toml` |
|
|
| Downloads | `~/.local/share/monsoon/downloads/` |
|
|
| Torrent registry | `~/.local/share/monsoon/torrents.json` |
|
|
| Logs | `~/.local/state/monsoon/monsoon.log` |
|
|
| DHT cache | `~/.cache/monsoon/dht_bootstrap_nodes` |
|
|
|
|
## License
|
|
|
|
GPL-3.0-or-later
|