pyPhotoAlbum/INSTALLATION.md

# pyPhotoAlbum Installation Guide

This guide provides multiple installation methods for pyPhotoAlbum on Linux systems, with specific instructions for Fedora and Arch/CachyOS.

## Table of Contents

- [Quick Install (Recommended)](#quick-install-recommended)
- [Manual Installation](#manual-installation)
- [Distribution-Specific Packages](#distribution-specific-packages)
  - [Fedora (RPM)](#fedora-rpm)
  - [Arch/CachyOS (PKGBUILD)](#archcachyos-pkgbuild)
- [Development Installation](#development-installation)
- [Troubleshooting](#troubleshooting)

---

## Quick Install (Recommended)

The easiest way to install pyPhotoAlbum is using the provided installation script:

```bash
# Clone the repository
git clone https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum.git
cd pyPhotoAlbum

# Run the installation script
./install.sh
```

The script will:
1. Detect your distribution (Fedora, Arch, Ubuntu, etc.)
2. Offer to install system dependencies
3. Install pyPhotoAlbum
4. Set up desktop integration (icon and menu entry)

### Installation Modes

**User installation (default):**
```bash
./install.sh
```
- Installs to `~/.local/`
- No root privileges required
- Only affects current user

**System-wide installation:**
```bash
sudo ./install.sh --system
```
- Installs to `/usr/`
- Requires root privileges
- Available to all users

---

## Manual Installation

### Step 1: Install Dependencies

**Fedora:**
```bash
sudo dnf install python3 python3-pip python3-qt6 python3-pyopengl \
    python3-numpy python3-pillow python3-reportlab python3-lxml
```

**Arch/CachyOS:**
```bash
sudo pacman -S python python-pip python-pyqt6 python-pyopengl \
    python-numpy python-pillow python-reportlab python-lxml
```

**Ubuntu/Debian:**
```bash
sudo apt install python3 python3-pip python3-pyqt6 python3-opengl \
    python3-numpy python3-pil python3-reportlab python3-lxml
```

**Other distributions:**

If your distribution isn't listed, install these Python packages via pip:
```bash
pip install --user PyQt6 PyOpenGL numpy Pillow reportlab lxml
```

### Step 2: Install pyPhotoAlbum

**For current user only:**
```bash
cd pyPhotoAlbum
pip install --user .
```

**System-wide:**
```bash
cd pyPhotoAlbum
sudo pip install .
```

### Step 3: Desktop Integration (Optional)

**User installation:**
```bash
# Create directories
mkdir -p ~/.local/share/applications
mkdir -p ~/.local/share/icons/hicolor/256x256/apps

# Install files
cp pyphotoalbum.desktop ~/.local/share/applications/
cp pyPhotoAlbum/icons/icon.png ~/.local/share/icons/hicolor/256x256/apps/pyphotoalbum.png

# Update caches
update-desktop-database ~/.local/share/applications
gtk-update-icon-cache ~/.local/share/icons/hicolor/
```

**System-wide:**
```bash
sudo install -Dm644 pyphotoalbum.desktop /usr/share/applications/pyphotoalbum.desktop
sudo install -Dm644 pyPhotoAlbum/icons/icon.png /usr/share/icons/hicolor/256x256/apps/pyphotoalbum.png
sudo update-desktop-database /usr/share/applications
sudo gtk-update-icon-cache /usr/share/icons/hicolor/
```

---

## Distribution-Specific Packages

### Fedora (RPM)

Build and install an RPM package for Fedora:

#### Prerequisites

```bash
sudo dnf install rpm-build rpmdevtools
```

#### Build Source Tarball

```bash
# From the project root
cd ..
tar czf pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
mv pyphotoalbum-0.1.0.tar.gz ~/rpmbuild/SOURCES/
```

#### Build RPM

```bash
cd pyPhotoAlbum
rpmbuild -ba pyphotoalbum.spec
```

The RPM will be created in `~/rpmbuild/RPMS/noarch/`

#### Install RPM

```bash
sudo dnf install ~/rpmbuild/RPMS/noarch/pyphotoalbum-0.1.0-1.*.noarch.rpm
```

#### Create Local Repository (Optional)

To create a local yum repository:

```bash
# Create repository directory
sudo mkdir -p /var/local-repo

# Copy RPM
sudo cp ~/rpmbuild/RPMS/noarch/pyphotoalbum-*.rpm /var/local-repo/

# Create repository metadata
sudo createrepo /var/local-repo

# Add repository configuration
sudo tee /etc/yum.repos.d/local.repo << EOF
[local]
name=Local Repository
baseurl=file:///var/local-repo
enabled=1
gpgcheck=0
EOF

# Install from local repository
sudo dnf install pyphotoalbum
```

---

### Arch/CachyOS (PKGBUILD)

Build and install using the provided PKGBUILD:

#### Build Source Tarball

```bash
# From the project root
cd ..
tar czf pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
mv pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
cd pyPhotoAlbum
```

#### Build Package

```bash
makepkg -si
```

This will:
- Build the package
- Install it automatically (`-i` flag)
- Sync dependencies (`-s` flag)

#### Build Without Installing

```bash
makepkg
```

The package will be created as `pyphotoalbum-0.1.0-1-any.pkg.tar.zst`

#### Install Package

```bash
sudo pacman -U pyphotoalbum-0.1.0-1-any.pkg.tar.zst
```

#### Create Local Repository (Optional)

To create a local pacman repository:

```bash
# Create repository directory
mkdir -p ~/local-repo

# Copy package
cp pyphotoalbum-*.pkg.tar.zst ~/local-repo/

# Create repository database
cd ~/local-repo
repo-add local.db.tar.gz pyphotoalbum-*.pkg.tar.zst

# Add repository to pacman.conf
sudo tee -a /etc/pacman.conf << EOF

[local]
SigLevel = Optional TrustAll
Server = file:///home/$USER/local-repo
EOF

# Update and install
sudo pacman -Sy pyphotoalbum
```

---

## Development Installation

For development work, install in editable mode:

```bash
# Clone repository
git clone https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum.git
cd pyPhotoAlbum

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run application
pyphotoalbum
# or
python pyPhotoAlbum/main.py
```

### Development Tools

The development installation includes:
- **pytest** - Testing framework
- **pytest-qt** - Qt testing support
- **pytest-cov** - Coverage reporting
- **pytest-mock** - Mocking utilities
- **flake8** - Linting
- **black** - Code formatting
- **mypy** - Type checking

### Running Development Tools

```bash
# Format code
black pyPhotoAlbum tests

# Run linter
flake8 pyPhotoAlbum tests

# Type checking
mypy pyPhotoAlbum

# Run tests with coverage
pytest --cov=pyPhotoAlbum --cov-report=html
```

---

## Troubleshooting

### Command not found: pyphotoalbum

**Issue:** After user installation, the `pyphotoalbum` command is not found.

**Solution:** Add `~/.local/bin` to your PATH:

```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### Application doesn't appear in menu

**Issue:** Desktop entry not showing in application menu.

**Solution:** Update desktop database:

```bash
# For user installation
update-desktop-database ~/.local/share/applications

# For system installation
sudo update-desktop-database /usr/share/applications
```

You may need to log out and back in or restart your desktop environment.

### Icon not displaying

**Issue:** Application icon not showing in menu or taskbar.

**Solution:** Update icon cache:

```bash
# For user installation
gtk-update-icon-cache ~/.local/share/icons/hicolor/

# For system installation
sudo gtk-update-icon-cache /usr/share/icons/hicolor/
```

### PyQt6 import errors

**Issue:** `ImportError: cannot import name 'xxx' from 'PyQt6'`

**Solution:** Ensure PyQt6 is properly installed:

```bash
# Uninstall and reinstall
pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6
```

### OpenGL errors

**Issue:** OpenGL-related errors when starting the application.

**Solution:** Install OpenGL libraries:

**Fedora:**
```bash
sudo dnf install mesa-libGL mesa-libGL-devel
```

**Arch/CachyOS:**
```bash
sudo pacman -S mesa libglvnd
```

### Permission denied errors

**Issue:** Permission errors during system-wide installation.

**Solution:** Use `sudo` or switch to user installation:

```bash
# User installation (no sudo needed)
pip install --user .
./install.sh  # Without --system flag
```

### Building RPM fails

**Issue:** Missing build dependencies for RPM.

**Solution:** Install all build requirements:

```bash
sudo dnf install rpm-build rpmdevtools python3-devel python3-setuptools \
    python3-pip desktop-file-utils
```

### Building on Arch fails

**Issue:** Missing dependencies when running makepkg.

**Solution:** Install build dependencies:

```bash
sudo pacman -S base-devel python-build python-installer python-wheel
```

---

## Verifying Installation

After installation, verify it works:

```bash
# Check if command is available
which pyphotoalbum

# Check Python package
python -c "import pyPhotoAlbum; print(pyPhotoAlbum.__file__)"

# Run application
pyphotoalbum --version  # If version flag is implemented
pyphotoalbum
```

---

## Uninstallation

### User Installation

```bash
pip uninstall pyphotoalbum
rm ~/.local/share/applications/pyphotoalbum.desktop
rm ~/.local/share/icons/hicolor/256x256/apps/pyphotoalbum.png
update-desktop-database ~/.local/share/applications
```

### System Installation

```bash
sudo pip uninstall pyphotoalbum
sudo rm /usr/share/applications/pyphotoalbum.desktop
sudo rm /usr/share/icons/hicolor/256x256/apps/pyphotoalbum.png
sudo update-desktop-database /usr/share/applications
```

### RPM (Fedora)

```bash
sudo dnf remove pyphotoalbum
```

### Pacman (Arch/CachyOS)

```bash
sudo pacman -R pyphotoalbum
```

---

## Getting Help

If you encounter issues not covered here:

1. Check the [README.md](README.md) for general information
2. Search existing issues: https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum/issues
3. Create a new issue with:
   - Your distribution and version
   - Installation method used
   - Complete error messages
   - Output of `python --version` and `pip list | grep -i pyqt`

---

## Next Steps

After installation, see:
- [README.md](README.md) - General usage and features
- [EMBEDDED_TEMPLATES.md](pyPhotoAlbum/EMBEDDED_TEMPLATES.md) - Template system
- Examples in the `examples/` directory

Enjoy using pyPhotoAlbum!