qbit_manage/docs/Local-Installations.md

Python/Source Installation

This guide covers installing qbit_manage from source code or PyPI for development purposes or when you need the latest features.

Note: For most users, we recommend using the Desktop App or Standalone Binary instead, as they're easier to install and use.

Prerequisites

• Python 3.9.0 or higher
• pip (Python package installer)
• Git (for source installation)

Installation Methods

Method 1: Install from PyPI (Recommended)

pip install qbit-manage

Method 2: Install from Source

Navigate to the directory where you'd like to clone the repository:

# Clone the repository
git clone https://github.com/StuffAnThings/qbit_manage
cd qbit_manage

# Install the package
pip install .

If you encounter dependency issues, try:

pip install . --ignore-installed

Method 3: Development Installation

For development or to get the latest unreleased features:

# Clone the repository
git clone https://github.com/StuffAnThings/qbit_manage
cd qbit_manage

# Install in development mode
pip install -e .

Configuration File Setup

After installation, qbit_manage will look for configuration files in platform-specific locations:

• Windows: %APPDATA%\qbit-manage\config.yml
• macOS: ~/Library/Application Support/qbit-manage/config.yml
• Linux/Unix: ~/.config/qbit-manage/config.yml

Setting up the Configuration

1. Create the configuration directory:

   # Windows (PowerShell)
   New-Item -ItemType Directory -Force -Path "$env:APPDATA\qbit-manage"
   
   # macOS/Linux
   mkdir -p ~/.config/qbit-manage  # Linux
   mkdir -p ~/Library/Application\ Support/qbit-manage  # macOS
   

2. Copy the sample configuration:

   # From the cloned repository
   cp config/config.yml.sample ~/.config/qbit-manage/config.yml  # Linux
   cp config/config.yml.sample ~/Library/Application\ Support/qbit-manage/config.yml  # macOS
   copy config\config.yml.sample "%APPDATA%\qbit-manage\config.yml"  # Windows
   

3. Edit the configuration file as outlined in the Config-Setup guide.

Alternative: You can place the config file anywhere and specify its location using the --config-file option.

Usage

Running the Script

Basic Usage

Run the script with -h to see all available commands:

qbit-manage -h
# or if installed from source
python qbit_manage.py -h

Common Usage Examples

Run with default configuration:

qbit-manage

Run specific commands:

qbit-manage --cat-update --tag-update

Run with Web API and Web UI:

qbit-manage --web-server

You can then access the Web UI in your browser at http://localhost:8080.

Use custom configuration file:

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

Run in dry-run mode (preview changes without applying them):

qbit-manage --dry-run --cat-update --tag-update

Run on a schedule:

qbit-manage --schedule 1440  # Run every 24 hours (1440 minutes)

Command Line Options

Option	Description
--config-file, -c	Specify custom config file location
--log-file, -lf	Specify custom log file location
--web-server, -ws	Start the web server for API and UI
--port, -p	Web server port (default: 8080)
--dry-run, -dr	Preview changes without applying them
--schedule, -sch	Run on a schedule (minutes)
--run, -r	Run once and exit (no scheduler)

For a complete list of commands and options, see the Commands documentation.

Virtual Environment (Recommended)

For Python installations, it's recommended to use a virtual environment:

# Create virtual environment
python -m venv qbit-manage-env

# Activate virtual environment
# Linux/macOS:
source qbit-manage-env/bin/activate
# Windows:
qbit-manage-env\Scripts\activate

# Install qbit-manage
pip install qbit-manage

# Run qbit-manage
qbit-manage --help

Updating

PyPI installation:

pip install --upgrade qbit-manage

Source installation:

cd qbit_manage
git pull
pip install . --upgrade