{"id":13469801,"url":"https://github.com/jesec/flood","last_synced_at":"2026-02-07T10:10:06.606Z","repository":{"id":38382249,"uuid":"284712323","full_name":"jesec/flood","owner":"jesec","description":"A modern web UI for various torrent clients with a Node.js backend and React frontend.","archived":false,"fork":false,"pushed_at":"2025-03-03T08:26:38.000Z","size":40178,"stargazers_count":2395,"open_issues_count":67,"forks_count":146,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-23T17:10:21.699Z","etag":null,"topics":["collaborate","nodejs","qbittorrent","react","rtorrent","transmission","webui"],"latest_commit_sha":null,"homepage":"https://flood.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jesec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-03T13:48:43.000Z","updated_at":"2025-04-23T10:43:07.000Z","dependencies_parsed_at":"2023-10-05T00:34:09.360Z","dependency_job_id":"d145368b-708b-4dba-a982-bf63297d6b09","html_url":"https://github.com/jesec/flood","commit_stats":{"total_commits":2388,"total_committers":111,"mean_commits":"21.513513513513512","dds":0.5749581239530988,"last_synced_commit":"3b520944ceb37900178af63aad629c213c7f85b3"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesec%2Fflood","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesec%2Fflood/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesec%2Fflood/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesec%2Fflood/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jesec","download_url":"https://codeload.github.com/jesec/flood/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253748180,"owners_count":21957880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collaborate","nodejs","qbittorrent","react","rtorrent","transmission","webui"],"created_at":"2024-07-31T16:00:16.701Z","updated_at":"2026-02-07T10:10:06.601Z","avatar_url":"https://github.com/jesec.png","language":"TypeScript","readme":"# Flood\n\n[![Flood logo](https://github.com/jesec/flood/raw/master/flood.svg)](https://flood.js.org)\n\n[![Build](https://github.com/jesec/flood/actions/workflows/build.yml/badge.svg)](https://github.com/jesec/flood/actions/workflows/build.yml)\n[![Crowdin](https://badges.crowdin.net/flood/localized.svg)](https://crowdin.com/project/flood)\n[![Discord server badge](https://img.shields.io/discord/418267176873623553.svg?style=flat-square)](https://discord.gg/Z7yR5Uf)\n\nFlood is a monitoring service for various torrent clients. It's a Node.js service that communicates with your favorite torrent client and serves a decent web UI for administration. [Flood-UI](https://github.com/Flood-UI) organization hosts related projects.\n\n#### Supported Clients\n\n| Client                                                          | Support                                                                                                        |\n| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| [rTorrent](https://github.com/rakshasa/rtorrent)                | :white_check_mark: ([tested](https://github.com/jesec/flood/blob/master/server/.vitest/rtorrent.setup.ts))     |\n| [qBittorrent](https://github.com/qbittorrent/qBittorrent) v4.1+ | :white_check_mark: ([tested](https://github.com/jesec/flood/blob/master/server/.vitest/qbittorrent.setup.ts))  |\n| [Transmission](https://github.com/transmission/transmission)    | :white_check_mark: ([tested](https://github.com/jesec/flood/blob/master/server/.vitest/transmission.setup.ts)) |\n| [Deluge](https://github.com/deluge-torrent/deluge) v2+          | :alembic: Experimental                                                                                         |\n\n##### RTorrent Notes\n\nFor now, rakshasa/rtorrent and jesec/rtorrent are both supported.\n\nIf you are using rakshasa/rtorrent\u003e0.15.1 (upstream rtorrent with json-rpc support),\nyou will need to add these options to your config:\n\n```ini\nmethod.insert=d.down.sequential,value|const,0\nmethod.insert=d.down.sequential.set,value|const,0\n```\n\n#### Integrating with Flood\n\nAPIs are officially documented inline by the [comments](https://github.com/jesec/flood/blob/f7019001dd81ee8401c87d4c4cd6da6f5f520611/server/routes/api/torrents.ts#L106-L117) and [types](https://github.com/jesec/flood/blob/f7019001dd81ee8401c87d4c4cd6da6f5f520611/shared/schema/api/torrents.ts#L10-L32).\n\nYou can also check out:\n\n- [community documentation site](https://flood-api.netlify.app)\n- [list of unofficial client API libraries](https://github.com/jesec/flood/wiki/List-of-unofficial-client-API-libraries)\n- [list of unofficial API integrations](https://github.com/jesec/flood/wiki/List-of-unofficial-API-integrations)\n\nFlood conforms to [Semantic Versioning](https://semver.org) conventions.\n\n#### Feedback\n\nIf you have a specific issue or bug, please file a [GitHub issue](https://github.com/jesec/flood/issues). Please join the [Flood Discord server](https://discord.gg/Z7yR5Uf) to discuss feature requests and implementation details.\n\n#### More Information\n\nCheck out the [Wiki](https://github.com/jesec/flood/wiki) for more information.\n\n# Getting started\n\n### Pre-Requisites\n\nInstall [Node.js runtime](https://nodejs.org/). Flood tracks `Current` and provides support to `Active LTS` as well.\n\n- Debian, Ubuntu (`apt`/`.deb`) and Enterprise Linux (`yum`/`dnf`/`.rpm`) -based distributions users can install `nodejs` from [NodeSource](https://github.com/nodesource/distributions) software repository.\n- Windows users can use [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget), [Chocolatey](https://chocolatey.org/packages/nodejs) or installer.\n- macOS users can use [brew](https://brew.sh/) or installer.\n- Check [Node.js website](https://nodejs.org/en/download/package-manager) for more.\n\nAlternatively, download a single-executable build from [Releases](https://github.com/jesec/flood/releases) (or rolling build from [Actions](https://nightly.link/jesec/flood/workflows/publish-rolling/master)). It bundles `Node.js` and supports `Linux`, `macOS` and `Windows`.\n\n### Installation\n\n(sudo) `npm install --global flood` or `npx flood`\n\nOr use `@jesec/flood` for cutting-edge builds.\n\nOr [build from source](https://github.com/jesec/flood#Building-Flood).\n\n### Run\n\n`flood` or `npx flood` if you installed Flood via `npm`.\n\n`npm run start` if you compiled Flood from source.\n\nCheck [Wiki](https://github.com/jesec/flood/wiki) for how to install Flood as a service.\n\n### Configuration\n\nFlood uses a command line configuration interface.\n\nRun `flood --help`, `npx flood --help` or `npm run start -- --help` to get help about command line arguments.\n\nIf you want to know more about configurations, check [shared/schema/Config.ts](https://github.com/jesec/flood/blob/master/shared/schema/Config.ts).\n\nWhen Flood's builtin user management is enabled (default), you will be prompted to configure the connection to torrent client when loading the web interface.\n\n**What to configure**\n\n1. If you are proxying requests to Flood from your own web server, configure Flood's path from the host at the `--baseuri` (or `baseURI`) property. All requests will be prefixed with this value.\n   - For example, if serving Flood from `https://foo.bar/apps/flood`, you would set `baseURI` to `/apps/flood`. If serving flood from `https://foo.bar`, you do not need to configure `baseURI`.\n   - Read more about proxying requests to Flood in the [Wiki](https://github.com/jesec/flood/wiki).\n1. Check [Wiki](https://github.com/jesec/flood/wiki), especially `Security` sections.\n\n### Upgrade\n\nRun the installation command again.\n\n### Troubleshooting\n\n- Flood and filesystem:\n  - Flood server performs file operations itself. As such, Flood needs to have permissions/access to the files.\n  - Flood only uses the path provided by the torrent client so it needs to have the same filesystem context as the torrent client. If a file is \"/path/to/a/file\" to the torrent client, it has to be \"/path/to/a/file\" to Flood in order to get file operations working. It can't be \"/mnt/some/different/path/file\".\n- rTorrent:\n  - Linux users can download the latest static executable (available for `amd64` and `arm64`) from [jesec/rtorrent](https://github.com/jesec/rtorrent). Alternatively, use package managers such as `apt`, `yum`, `pacman` of the platform to install rTorrent.\n  - macOS users can use `brew` to install rTorrent.\n  - [Compile](https://github.com/rakshasa/rtorrent/wiki/Installing): XMLRPC support flag (`--with-xmlrpc-c`) is required during compilation.\n  - Certain features (sequential download, initial seeding, etc.) are not available in vanilla rTorrent.\n- Ask for help in the [Flood Discord server](https://discord.gg/Z7yR5Uf).\n\n### Docker\n\n`docker run -it jesec/flood --help`\n\nOr `jesec/flood:master` for cutting-edge builds.\n\nTo upgrade, `docker pull jesec/flood`.\n\nNote that you have to let Docker know which port should be exposed (e.g. `-p 3000:3000`) and folder mapping (e.g. `-v /data:/data`).\n\nDon't forget to pay attention to `flood`'s arguments like `--port` and `--allowedpath`.\n\nAlternatively, you can pass in environment variables instead (e.g. `-e FLOOD_OPTION_port=3000`).\n\nCheckout [Run Flood (and torrent clients) in containers](https://github.com/jesec/flood/discussions/120) discussion.\n\nFilesystem parts in [Troubleshooting](https://github.com/jesec/flood#troubleshooting) are especially important for containers.\n\n## Building Flood\n\n### Clone from repository\n\n`git clone https://github.com/jesec/flood.git`\n\n### Compiling assets and starting the server\n\nFrom the root of the Flood directory...\n\n1. Run `npm install`.\n1. Run `npm run build`.\n1. Run `npm start`.\n\nAccess the UI in your browser. With default settings, go to `http://localhost:3000`. You can configure the port via `--port` argument.\n\n**Notes**\n\n- When you use `npm run start` to execute Flood, you have to pass command line arguments after `--`. For example, `npm run start -- --host 0.0.0.0 --port 8080`. This applies to any `npm run` (e.g. `start:development:client`).\n\n### Updating\n\n1. To update, run `git pull` in this repository's directory.\n1. Kill the currently running Flood server.\n1. Run `npm install` to update dependencies.\n1. Run `npm run build` to transpile and bundle static assets.\n1. Start the Flood server with `npm start`.\n\n### Local Development\n\n1. Run `npm install`.\n1. Run `npm run start:development:server` and `npm run start:development:client` in separate terminal instances.\n   - `npm run start:development:server` uses [ts-node-dev](https://www.npmjs.com/package/ts-node-dev) to watch for changes to the server-side source. Or open the folder with VS code and then `Run -\u003e Start Debugging`. You may use a [Javascript IDE](https://code.visualstudio.com/) to debug server codes.\n   - `npm run start:development:client` watches for changes in the client-side source. Access the UI in your browser. Defaults to `localhost:4200`. You may use browser's [DevTools](https://developers.google.com/web/tools/chrome-devtools) to debug client codes.\n\n`--help --show-hidden` shows advanced arguments.\n\n`--proxy` proxies requests from a development client to a URL of your choice (usually URL to a Flood server). It is useful when you wish to do development on the frontend but not the backend. Or when the frontend and backend are being developed on different hosts.\n\n### Environment Variables\n\n1. `DEV_SERVER_PORT`: webpackDevServer's port, used when developing Flood. Defaults to `4200`.\n1. `DEV_SERVER_HOST`: webpackDevServer's host, used when developing Flood. Defaults to `0.0.0.0`.\n1. `DEV_SERVER_HTTPS`: webpackDevServer's protocol, used when developing Flood. Defaults to `http`.\n\n### Building Docker\n\n1. `docker build --pull --rm -f Dockerfile -t flood:latest .`\n1. `docker run -it flood --help`\n","funding_links":[],"categories":["TypeScript","Apps","BT"],"sub_categories":["Download","BT Frontends"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesec%2Fflood","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjesec%2Fflood","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesec%2Fflood/lists"}