mirror of
https://github.com/StuffAnThings/qbit_manage.git
synced 2025-10-11 22:36:35 +08:00
156291723f
# Improvements - **ci(docker)**: add OCI labels and build metadata to Docker images - **Web UI**: Show an "Update available" badge next to the version and a toast notification when a newer version is detected - **Web UI**: Add integrated docs with collapsible sections - **ci(build)**: Publish to PyPI - **Category**: Allow category changes regardless of the "Category Update All" status (Fixes #913) # Bug Fixes - Fixes container hanging when using run command with QBT_RUN flag (Fixes #911) - Fixes bug on interval scheduler not displaying the correct next run time - Fix bug on webAPI requests not being queued correctly when called during a scheduled run **Full Changelog**: https://github.com/StuffAnThings/qbit_manage/compare/v4.5.4...v4.5.5 --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Actionbot <actions@github.com> Co-authored-by: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: ineednewpajamas <73252768+ineednewpajamas@users.noreply.github.com>
212 lines
6.3 KiB
Markdown
212 lines
6.3 KiB
Markdown
# Installation Options
|
|
|
|
qbit_manage offers multiple installation methods to suit different use cases:
|
|
|
|
## Installation Methods
|
|
|
|
### 1. Desktop App (Recommended for most users)
|
|
- **Windows**: Download and run the `.exe` installer
|
|
- **macOS**: Download and install the `.dmg` package
|
|
- **Linux**: Download and install the `.deb` package
|
|
|
|
The desktop app provides a graphical interface and automatically handles configuration file setup.
|
|
|
|
### 2. Standalone Binary (Command-line)
|
|
- **Windows**: `qbit-manage-windows-amd64.exe`
|
|
- **macOS**: `qbit-manage-macos-arm64` (Apple Silicon) or `qbit-manage-macos-x86_64` (Intel)
|
|
- **Linux**: `qbit-manage-linux-amd64`
|
|
|
|
Perfect for server environments, automation, or users who prefer command-line tools.
|
|
|
|
### 3. Docker Container
|
|
- Multi-architecture support (amd64, arm64, arm/v7)
|
|
- Ideal for containerized environments and NAS systems
|
|
|
|
### 4. Python Installation
|
|
- Install from source or PyPI
|
|
- For developers or users who want to modify the code
|
|
|
|
## Detailed Installation Guides
|
|
|
|
- [Desktop App Installation](#desktop-app-installation)
|
|
- [Standalone Binary Installation](#standalone-binary-installation)
|
|
- [Python/Source Installation](#pythonsource-installation)
|
|
- [Docker Installation](Docker-Installation)
|
|
- [unRAID Installation](Unraid-Installation)
|
|
|
|
## Desktop App Installation
|
|
|
|
### Windows
|
|
1. Download `qbit-manage-*-desktop-installer-setup.exe` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
|
|
2. Run the installer and follow the setup wizard
|
|
3. Launch qbit_manage from the Start Menu or desktop shortcut
|
|
4. The app will automatically create the configuration directory and files
|
|
|
|
### macOS
|
|
1. Download `qbit-manage-*-desktop-installer.dmg` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
|
|
2. Open the DMG file and drag qbit_manage to your Applications folder
|
|
3. Launch qbit_manage from Applications (you may need to allow it in System Preferences > Security & Privacy)
|
|
4. The app will automatically create the configuration directory and files
|
|
|
|
### Linux
|
|
1. Download `qbit-manage-*-desktop-installer.deb` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
|
|
2. Install using your package manager:
|
|
```bash
|
|
sudo dpkg -i qbit-manage-*-desktop-installer.deb
|
|
sudo apt-get install -f # Fix any dependency issues
|
|
```
|
|
3. Launch qbit_manage from your applications menu or run `qbit-manage` in terminal
|
|
4. The app will automatically create the configuration directory and files
|
|
|
|
## Standalone Binary Installation
|
|
|
|
### Windows
|
|
1. Download `qbit-manage-windows-amd64.exe` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
|
|
2. Place the executable in a directory of your choice (e.g., `C:\Program Files\qbit-manage\`)
|
|
3. Add the directory to your PATH environment variable (optional)
|
|
4. Run from Command Prompt or PowerShell:
|
|
```cmd
|
|
qbit-manage-windows-amd64.exe --help
|
|
```
|
|
|
|
### macOS
|
|
1. Download the appropriate binary from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases):
|
|
- `qbit-manage-macos-arm64` for Apple Silicon Macs (M1, M2, M3, etc.)
|
|
- `qbit-manage-macos-x86_64` for Intel Macs
|
|
2. Make the binary executable:
|
|
```bash
|
|
chmod +x qbit-manage-macos-*
|
|
```
|
|
3. Move to a directory in your PATH (optional):
|
|
```bash
|
|
sudo mv qbit-manage-macos-* /usr/local/bin/qbit-manage
|
|
```
|
|
4. Run the binary:
|
|
```bash
|
|
./qbit-manage-macos-* --help
|
|
```
|
|
|
|
### Linux
|
|
1. Download `qbit-manage-linux-amd64` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
|
|
2. Make the binary executable:
|
|
```bash
|
|
chmod +x qbit-manage-linux-amd64
|
|
```
|
|
3. Move to a directory in your PATH (optional):
|
|
```bash
|
|
sudo mv qbit-manage-linux-amd64 /usr/local/bin/qbit-manage
|
|
```
|
|
4. Run the binary:
|
|
```bash
|
|
./qbit-manage-linux-amd64 --help
|
|
```
|
|
|
|
## Python/Source Installation
|
|
|
|
For developers or users who want to modify the code, you can install from source or PyPI.
|
|
|
|
### Prerequisites
|
|
- Python 3.9 or higher
|
|
- Git (for source installation)
|
|
|
|
### Method 1: Install from PyPI
|
|
|
|
```bash
|
|
# Install uv first
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Install qbit-manage
|
|
uv tool install qbit-manage
|
|
```
|
|
|
|
### Method 2: Install from Source
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/StuffAnThings/qbit_manage.git
|
|
cd qbit_manage
|
|
|
|
# Install uv if not already installed
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Install the package
|
|
uv tool install .
|
|
```
|
|
|
|
### Running qbit-manage
|
|
|
|
After installation, you can run qbit-manage from anywhere:
|
|
|
|
```bash
|
|
# Show help and available options
|
|
qbit-manage --help
|
|
|
|
# Run once (without scheduler)
|
|
qbit-manage --run
|
|
|
|
# Run with web UI (default on desktop)
|
|
qbit-manage --web-server
|
|
```
|
|
|
|
### Usage
|
|
|
|
After installation, you can run qbit_manage using:
|
|
|
|
```bash
|
|
qbit-manage --help
|
|
```
|
|
|
|
> [!TIP]
|
|
> For Python installations, it's recommended to use a virtual environment to avoid conflicts with other packages.
|
|
|
|
### Development Installation
|
|
|
|
For development work or to contribute to the project:
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/StuffAnThings/qbit_manage.git
|
|
cd qbit_manage
|
|
|
|
# Install uv if not already installed
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Create virtual environment and install dependencies
|
|
uv venv
|
|
source .venv/bin/activate # Linux/macOS
|
|
# .venv\Scripts\activate # Windows
|
|
|
|
# Install in development mode
|
|
uv pip install -e .
|
|
```
|
|
|
|
### Updating
|
|
|
|
**Tool installation:**
|
|
```bash
|
|
uv tool upgrade qbit-manage
|
|
```
|
|
|
|
**Development installation:**
|
|
```bash
|
|
cd qbit_manage
|
|
git pull
|
|
uv pip install -e . --upgrade
|
|
```
|
|
|
|
## Quick Reference: Default Configuration File Locations
|
|
|
|
### Desktop App & Standalone Binary
|
|
- **Windows**: `%APPDATA%\qbit-manage\config.yml`
|
|
- **macOS**: `~/Library/Application Support/qbit-manage/config.yml`
|
|
- **Linux**: `~/.config/qbit-manage/config.yml`
|
|
|
|
### Docker Installation
|
|
- **Container Path**: `/app/config.yml`
|
|
- **Host Mount**: Typically mounted from `/path/to/your/config:/config`
|
|
|
|
### Custom Location
|
|
You can override the default location using the `--config-file` or `-c` command line option:
|
|
```bash
|
|
qbit-manage --config-file /path/to/your/config.yml
|
|
```
|