StuffAnThings/qbit_manage
1
1
Fork 0
mirror of https://github.com/StuffAnThings/qbit_manage.git synced 2025-10-31 16:49:24 +08:00
Code Issues Projects Releases Packages Wiki Activity
qbit_manage/docs/Installation.md
bakerboy448 9be7bfc52d
Docs updates (#914) 
<!--
Thanks for opening a PR! Your contribution is much appreciated.
In order to make sure your PR is handled as smoothly as possible we
request that you follow the checklist sections below.
Choose the right checklist for the change that you're making:
-->

## Description

Please include a summary of the change and which issue is fixed.

Fixes # (issue)

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update


## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have added or updated the docstring for new or existing methods
- [ ] I have modified this PR to merge to the develop branch

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
2025-08-19 07:50:33 -04:00

6 KiB
Raw Blame History

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

Windows

  1. Download qbit-manage-*-desktop-installer-setup.exe from the releases page
  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
  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
  2. Install using your package manager: 
    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
  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: 
    qbit-manage-windows-amd64.exe --help

macOS

  1. Download the appropriate binary from the releases page:
    • 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: 
    chmod +x qbit-manage-macos-*
  3. Move to a directory in your PATH (optional): 
    sudo mv qbit-manage-macos-* /usr/local/bin/qbit-manage
  4. Run the binary: 
    ./qbit-manage-macos-* --help

Linux

  1. Download qbit-manage-linux-amd64 from the releases page
  2. Make the binary executable: 
    chmod +x qbit-manage-linux-amd64
  3. Move to a directory in your PATH (optional): 
    sudo mv qbit-manage-linux-amd64 /usr/local/bin/qbit-manage
  4. Run the binary: 
    ./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

# 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

# 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 .

Usage

After installation, you can run qbit_manage using:

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:

# 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:

uv tool upgrade qbit-manage

Development installation:

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:

qbit-manage --config-file /path/to/your/config.yml