Skip to content

Installation

Jump to bottom
Chris Purcell edited this page Feb 7, 2026 · 1 revision

Installation Guide

DFBU provides multiple installation methods to accommodate different use cases and user preferences.

System Requirements

Minimum Requirements

Component Requirement
Operating System Linux (64-bit)
Python 3.14+ (for source installation)
Disk Space 50 MB (application)
Memory 512 MB RAM minimum
Display X11 or Wayland display server

Recommended Requirements

Component Recommendation
Memory 1 GB+ RAM
Disk Space 100 MB+ (for backups)
Python Python 3.14 (latest stable)

Distribution Compatibility

DFBU is tested on:

  • Fedora 39+
  • Ubuntu 22.04+
  • Debian 12+
  • Arch Linux (rolling)
  • openSUSE Tumbleweed

Other distributions should work but are not explicitly tested.

Installation Methods

Method 1: AppImage (Recommended)

AppImage provides a self-contained, distribution-independent installation.

Download

# Download latest release
wget https://github.com/L3DigitalNet/DFBU-Dotfiles-Backup-Utility/releases/latest/download/DFBU-x86_64.AppImage

# Make executable
chmod +x DFBU-x86_64.AppImage

Run

# Run directly
./DFBU-x86_64.AppImage

# Optional: Move to ~/Applications or /usr/local/bin
mv DFBU-x86_64.AppImage ~/Applications/

Desktop Integration (Optional)

Create desktop entry for application launcher:

# Create desktop entry
cat > ~/.local/share/applications/dfbu.desktop <<EOF
[Desktop Entry]
Name=DFBU
Comment=DotFiles Backup Utility
Exec=$HOME/Applications/DFBU-x86_64.AppImage
Icon=dfbu
Terminal=false
Type=Application
Categories=Utility;System;
EOF

# Update desktop database
update-desktop-database ~/.local/share/applications/

AppImage Dependencies

Some distributions require additional libraries:

FUSE 2 (for AppImage runtime):

# Ubuntu/Debian
sudo apt install libfuse2

# Fedora
sudo dnf install fuse-libs

# Arch Linux
sudo pacman -S fuse2

OpenGL/EGL (for Qt rendering):

# Ubuntu/Debian
sudo apt install libegl1 libgl1

# Fedora
sudo dnf install mesa-libEGL mesa-libGL

# Arch Linux
sudo pacman -S mesa

Method 2: Running from Source

For development or customization, run DFBU from source.

Prerequisites

Install system dependencies:

Ubuntu/Debian:

sudo apt update
sudo apt install python3.14 python3.14-venv git

Fedora:

sudo dnf install python3.14 python3-pip git

Arch Linux:

sudo pacman -S python git

Clone Repository

git clone https://github.com/L3DigitalNet/DFBU-Dotfiles-Backup-Utility.git
cd DFBU-Dotfiles-Backup-Utility

Setup with UV (Recommended)

UV provides fast, reliable Python package management:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python 3.14
uv python install 3.14

# Create virtual environment and install dependencies
uv sync --all-extras --dev

# Run application
uv run python DFBU/dfbu_gui.py

Setup with pip (Alternative)

Traditional pip-based installation:

# Create virtual environment
python3.14 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -r DFBU/requirements.txt

# Run application
python DFBU/dfbu_gui.py

Method 3: Setup Script

Automated setup for source installation:

# Clone repository
git clone https://github.com/L3DigitalNet/DFBU-Dotfiles-Backup-Utility.git
cd DFBU-Dotfiles-Backup-Utility

# Run setup script (installs UV, creates venv, installs dependencies)
./scripts/setup.sh

# Activate virtual environment
source .venv/bin/activate

# Run application
python DFBU/dfbu_gui.py

Post-Installation

First Launch

On first launch, DFBU creates configuration directories:

AppImage Installation:

  • Configuration: ~/.config/dfbu/
  • Data: ~/.local/share/dfbu/

Source Installation:

  • Configuration: DFBU/data/ (development default)
  • Can be changed to ~/.config/dfbu/ via settings

Initial Configuration

  1. Set Backup Paths: Configure mirror and archive directories
  2. Add Dotfiles: Add first configuration files to backup library
  3. Configure Options: Set compression level, verification, etc.
  4. Test Backup: Run a test backup to verify functionality

See User Guide for detailed configuration instructions.

Verify Installation

# AppImage
./DFBU-x86_64.AppImage --version

# Source installation
python DFBU/dfbu_gui.py --version

Expected output: DFBU v1.2.2

Updating

AppImage Updates

Manual Update

# Download latest version
wget https://github.com/L3DigitalNet/DFBU-Dotfiles-Backup-Utility/releases/latest/download/DFBU-x86_64.AppImage

# Replace old version
chmod +x DFBU-x86_64.AppImage
mv DFBU-x86_64.AppImage ~/Applications/DFBU-x86_64.AppImage

AppImageUpdate (Delta Updates)

DFBU supports delta updates via AppImageUpdate (v1.2.1+):

# Install AppImageUpdate
# Download from https://github.com/AppImage/AppImageUpdate/releases

# Update DFBU
./appimageupdatetool-x86_64.AppImage DFBU-x86_64.AppImage

Benefits:

  • Downloads only changed portions
  • Significantly faster than full download
  • Verifies integrity automatically

Source Installation Updates

# Navigate to repository
cd DFBU-Dotfiles-Backup-Utility

# Pull latest changes
git pull origin main

# Update dependencies (UV)
uv sync --all-extras --dev

# Or with pip
source .venv/bin/activate
pip install -r DFBU/requirements.txt --upgrade

Troubleshooting Installation

Common Issues

AppImage Won't Launch

Symptoms: Double-click does nothing or shows error

Solutions:

  1. Verify executable permissions: chmod +x DFBU-x86_64.AppImage
  2. Install libfuse2: sudo apt install libfuse2 (Ubuntu/Debian)
  3. Try running from terminal to see error messages

Qt Platform Plugin Errors

Symptoms: "Could not find the Qt platform plugin" error

Solutions:

# Install Qt platform dependencies
# Ubuntu/Debian
sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xkb1 libxkbcommon-x11-0

# Fedora
sudo dnf install qt6-qtbase xcb-util-*

OpenGL/EGL Errors

Symptoms: "EGL display not available" or rendering errors

Solutions:

# Install OpenGL libraries
# Ubuntu/Debian
sudo apt install libegl1 libgl1 libglu1-mesa

# Fedora
sudo dnf install mesa-libEGL mesa-libGL mesa-libGLU

Python Version Issues

Symptoms: "Python 3.14+ required" error

Solutions:

  1. Install Python 3.14:

    # Using UV
uv python install 3.14

# Or system package manager
# Ubuntu (via deadsnakes PPA)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.14 python3.14-venv

  2. Verify Python version:

    python3.14 --version

Missing PySide6

Symptoms: "No module named 'PySide6'" error

Solutions:

# Reinstall dependencies
# UV
uv sync --all-extras

# pip
pip install PySide6>=6.6

Getting Help

If installation issues persist:

  1. Check Troubleshooting page
  2. Search GitHub Issues
  3. Ask in GitHub Discussions
  4. Report bug with system details

Uninstallation

AppImage Uninstallation

# Remove AppImage
rm ~/Applications/DFBU-x86_64.AppImage

# Remove desktop entry (if created)
rm ~/.local/share/applications/dfbu.desktop
update-desktop-database ~/.local/share/applications/

# Remove configuration (optional)
rm -rf ~/.config/dfbu/
rm -rf ~/.local/share/dfbu/

Source Installation Uninstallation

# Remove repository
cd ..
rm -rf DFBU-Dotfiles-Backup-Utility/

# Remove configuration (optional)
rm -rf ~/.config/dfbu/
rm -rf ~/.local/share/dfbu/

Note: Configuration removal is optional. Keep configuration if you plan to reinstall later.

Next Steps

After installation:

  1. Read User Guide for usage instructions
  2. Review Configuration for file format details
  3. Check FAQ for common questions

Navigation: Home | Features | User Guide | Configuration

Clone this wiki locally