qb fix - System Repair

The qb fix functions provide a powerful and user-friendly toolkit to address common issues and perform system repairs effortlessly. With a focus on simplicity and effectiveness, these functions enable you to troubleshoot and resolve various problems that may arise on your server, ensuring smooth and uninterrupted operations.

Fix Python

Fix Python configuration and install missing extensions:

qb fix python

What it does (per script):

• Installs/repairs Python build deps and runtime packages (pip, docopt, virtualenv, etc.)
• Ensures compiled Python 3.11 and 3.13 are present and functional (skips where native), with pip/bootstrap synced
• Applies PEP 668 safeguards (--break-system-packages when needed) and avoids downgrading system pip
• Syncs baseline modules across 3.11/3.13 and system python; logs FIX_PYTHON to system_log and reports installed versions

When to use:

• Python apps won’t start or show ModuleNotFoundError
• After distro/OS upgrades that changed Python
• Broken virtualenvs or missing compiled Python runtimes (3.11/3.13)
• Before/after installing Python-based QuickBox apps

Fix PHP

Repair and update the QuickBox-supported PHP stack (currently PHP 8.1):

qb fix php

What it does (per script):

• Temporarily unholds PHP packages, refreshes apt, and reinstalls/repairs the entire supported chain (FPM, CLI, common extensions like memcached/msgpack/xmlrpc/zip/opcache)
• Removes Apache to avoid conflicts, regenerates php8.1-fpm pool config, and re-enables required modules
• Re-holds PHP packages to pin the supported version and updates alternatives/symlinks, then restarts PHP-FPM and logs FIX_PHP

When to use:

• PHP apps show 502/504 errors or missing extensions
• After distro/OS upgrades or manual apt changes touching PHP
• When QuickBox publishes a newer supported PHP version (delivered via this command)

Fix Database

Repair the QuickBox database backend and prune duplicate app rows:

qb fix database

What it does:

• Detects backend from /srv/quickbox/inc/constants.php (defaults to SQLite if unset)
• For SQLite: repairs the /srv/quickbox/db/qbpro.db → /opt/quickbox/config/db/qbpro.db symlink (creates backup, ensures www-data can read)
• For MySQL: skips symlink repair but still runs duplicate cleanup
• Removes the earliest duplicate entry per software_name for the current user_id (keeps the newest record)
• Logs actions to system_log (e.g., FIX_DATABASE_SYMLINK, PRUNE_FIRST_DUPLICATE_PER_APP or NO_DUPLICATES_FOUND)

When to use:

• Dashboard shows inconsistent app lists or missing installs
• You suspect /srv/quickbox/db/qbpro.db symlink drift (moved/renamed/mounted)
• Duplicate apps appear for a user after failed installs or restores

Fix Permissions (per-user apps)

Normalize system groups and application directories for a user:

qb fix permissions -u username
# or
qb fix perms -u username

What it does:

• Preserves existing groups from /etc/group, then ensures www-data is present; adds sudo only for shell users (shell_level = 1)
• Recursively sets ownership of /opt/<username> to the user and group
• Sets directories under /opt/<username> to 0755
• Logs FIX_PERMISSIONS <username> to system_log

How it differs from qb fix home:

• qb fix home -u username targets /home/<username> (files 0664, dirs 0755, home 0750, special handling for .ssh, .bin, rclone, Nextcloud)
• qb fix permissions -u username targets /opt/<username> and group membership — use it if/when app installs/upgrades change ownership/ACLs. QuickBox handles this automatically during installs/reinstalls/updates, but this command is available when something fails or manual changes break the flow.

Fix Version

Force update QuickBox to the latest upstream version:

qb fix version

What it does:

• Downloads latest QuickBox code from upstream
• Updates QuickBox core system files
• Refreshes CLI commands (qb)
• Updates dashboard files
• Repairs and synchronizes all components
• Updates dependencies and libraries
• Refreshes Nginx configuration
• Updates database schema
• Re-links system commands

When to use this:

What’s preserved:

• ✅ User accounts and passwords
• ✅ All installed applications
• ✅ Application configurations and data
• ✅ Database content
• ✅ User files and downloads
• ✅ Custom settings and preferences

What gets updated:

• 🔄 QuickBox core system files
• 🔄 CLI commands and utilities
• 🔄 Dashboard interface
• 🔄 System libraries (Python, PHP)
• 🔄 Configuration templates
• 🔄 Database schema (preserves data)
• 🔄 Nginx and web server config

Example usage:

# Force update to latest version
qb fix version
 
# System will:
# 1. Download latest QuickBox code
# 2. Update all components
# 3. Refresh dependencies
# 4. Synchronize configurations
# 5. Restart services

Common Workflows

Use these as quick checklists. Details and caveats live in the sections above so we avoid repeating full instructions.

Application Won’t Start

Systematic troubleshooting approach:

# 1. Check if it's a permission issue
qb fix home -u username
 
# 2. Restart the application
systemctl restart [application]@username
 
# 3. If PHP-based, fix PHP
qb fix php
 
# 4. If Python-based, fix Python
qb fix python
 
# 5. Check logs for errors
journalctl -u [application]@username -f

After System Upgrade

Post-upgrade maintenance routine:

# 1. Fix Python (often breaks during upgrades)
qb fix python
 
# 2. Fix PHP
qb fix php
 
# 3. Fix user permissions
qb fix home -u username
 
# 4. Update QuickBox if needed
qb update quickbox

Dashboard Not Working

Dashboard troubleshooting steps:

# 1. Fix database (removes duplicate entries)
qb fix database
 
# 2. Fix PHP
systemctl status php8.1-fpm
systemctl restart php8.1-fpm
qb fix php
 
# 3. Fix permissions
qb fix home -u username
 
# 4. Check Nginx is running
systemctl status nginx
nginx -t
systemctl restart nginx
 
# 5. If still broken, fix QuickBox
qb fix version

Multiple Users Having Issues

When all users experience problems:

# 1. Fix PHP (system-wide)
qb fix php
 
# 2. Fix Python (system-wide)
qb fix python
 
# 3. Fix each user's permissions
for user in user1 user2 user3; do
  echo "Fixing $user..."
  qb fix home -u $user
done
 
# 4. If issues persist, fix QuickBox
qb fix version

Troubleshooting Guide

”Command Not Found” After Fix

# Reload shell configuration
source ~/.bashrc
 
# Or logout and login again
exit

Fix Commands Don’t Resolve Issue

# 1. Check system logs
journalctl -xe
 
# 2. Generate support logs
qb generate logs
 
# 3. Ask for help in Discord
# Include the generated support logs

Permission Fix Doesn’t Work

# 1. Check if user exists
id username
 
# 2. Verify home directory
ls -la /home/username
 
# 3. Manual permission fix
chown -R username:username /home/username
chmod 755 /home/username
 
# 4. Try automated fix again
qb fix home -u username

PHP Fix Fails

# Check PHP version
php -v
 
# Check installed extensions
php -m
 
# Reinstall PHP manually
apt-get install --reinstall php8.1 php8.1-fpm php8.1-cli
 
# Try fix again
qb fix php

Python Fix Doesn’t Help

# Check Python version
python3 --version
 
# Check pip
pip3 --version
 
# Update pip manually
python3 -m pip install --upgrade pip
 
# Try fix again
qb fix python

Best Practices

Prevention Tips

Avoid Permission Issues

# Always use proper commands for file operations
# Instead of: cp /source /home/user/
# Use: sudo -u username cp /source /home/username/
 
# Or fix after copying
cp /source /home/username/
qb fix home -u username

Maintain Healthy System

# Regular maintenance prevents issues
qb clean memory          # Weekly
qb update check          # Weekly
qb fix php               # After updates
qb fix python            # After updates

Before Major Changes

Preparation checklist:

• ✅ Create system snapshot or backup
• ✅ Document current working state
• ✅ Test changes in isolation first
• ✅ Have rollback plan ready
• ✅ Note which applications are currently working
• ✅ Backup critical configurations manually

Related Commands

Need Help?