# Linux Software Installation Methods & System Maintenance Guide

**A Comprehensive Guide to Installing, Managing, and Maintaining Software on Linux**

*For Linux Mint / Ubuntu-based systems*  
*Created: October 2025*

---

## Table of Contents

1. [Introduction: The Linux Software Landscape](#introduction-the-linux-software-landscape)
2. [Installation Method 1: APT/DPKG (Native Packages)](#installation-method-1-aptdpkg-native-packages)
3. [Installation Method 2: Flatpak](#installation-method-2-flatpak)
4. [Installation Method 3: Snap Packages](#installation-method-3-snap-packages)
5. [Installation Method 4: AppImage](#installation-method-4-appimage)
6. [Installation Method 5: Tarball Archives](#installation-method-5-tarball-archives)
7. [Installation Method 6: Source Compilation](#installation-method-6-source-compilation)
8. [Installation Method 7: Third-Party Scripts](#installation-method-7-third-party-scripts)
9. [Quick Reference: Choosing the Right Method](#quick-reference-choosing-the-right-method)
10. [System Maintenance Best Practices](#system-maintenance-best-practices)
11. [Troubleshooting Common Issues](#troubleshooting-common-issues)
12. [Advanced Tips & Tricks](#advanced-tips--tricks)

---

## Introduction: The Linux Software Landscape

### Why So Many Installation Methods?

Unlike Windows (`.exe` installers) or macOS (`.dmg` files), Linux has multiple ways to install software. This diversity exists because:

1. **Different distributions** have different package managers
2. **Different use cases** require different approaches (system-wide vs. user-only vs. portable)
3. **Different priorities** (stability vs. latest versions vs. security)
4. **Historical evolution** - newer methods solve problems in older approaches

### The Core Philosophy

Linux software installation follows these principles:

- **Package managers** handle dependencies automatically
- **System files** are separated from user files
- **Multiple versions** can coexist (with care)
- **Removal should be clean** - no leftover cruft

### Installation Method Comparison

| Method | Root Required | Auto-Updates | Dependencies | Sandboxed | Portability | Speed |
|--------|---------------|--------------|--------------|-----------|-------------|-------|
| **APT** | ✅ Yes | ✅ Yes | ✅ Automatic | ❌ No | ❌ No | ⚡ Fast |
| **Flatpak** | ❌ No | ✅ Yes | ✅ Bundled | ✅ Yes | ❌ No | 🐌 Slower |
| **Snap** | ❌ No | ✅ Yes | ✅ Bundled | ✅ Yes | ❌ No | 🐌 Slowest |
| **AppImage** | ❌ No | ⚠️ Manual | ✅ Bundled | ❌ No | ✅ Yes | ⚡ Fast |
| **Tarball** | ⚠️ Maybe | ❌ No | ❌ Manual | ❌ No | ⚠️ Sometimes | ⚡ Fast |
| **Source** | ✅ Yes | ❌ No | ❌ Manual | ❌ No | ❌ No | ⚡ Fast |

---

## Installation Method 1: APT/DPKG (Native Packages)

### What It Is

APT (Advanced Package Tool) is Debian/Ubuntu's native package manager. It's the **gold standard** for installing software on these systems.

**How it works:**
1. Software is packaged as `.deb` files
2. Packages are hosted in **repositories** (online databases)
3. APT downloads and installs packages
4. Dependencies are resolved automatically
5. All installations are tracked in a central database

### When to Use

✅ **Use APT when:**
- Software is available in official repositories
- You want automatic security updates
- You need the most stable, tested version
- You want the lightest system impact

❌ **Don't use APT when:**
- You need the absolute latest version (repos lag behind)
- Software isn't available in repos
- You want to test multiple versions

### Basic Commands

```bash
# Update package list
sudo apt update

# Search for package
apt search package-name
apt search "keyword"

# Get package info
apt show package-name

# Install package
sudo apt install package-name

# Install specific version
sudo apt install package-name=1.2.3-1

# Install local .deb file (handles dependencies)
sudo apt install ./package.deb

# Remove package (keep config files)
sudo apt remove package-name

# Remove package completely (purge config)
sudo apt purge package-name

# Remove unused dependencies
sudo apt autoremove

# Upgrade all packages
sudo apt upgrade

# Upgrade to new distribution version
sudo apt full-upgrade
```

### File Locations

APT installs files in standard Linux directories:

```
/usr/bin/              # Executable binaries
/usr/lib/              # Libraries
/usr/share/            # Data files (icons, docs, etc.)
/etc/                  # System-wide configuration
~/.config/package/     # User configuration
~/.local/share/package/ # User data
```

### Finding What's Installed

```bash
# List all installed packages
dpkg -l

# Search for specific package
dpkg -l | grep package-name

# List files installed by package
dpkg -L package-name

# Find which package owns a file
dpkg -S /path/to/file

# Check package status
dpkg -s package-name
```

### Adding External Repositories (PPAs)

```bash
# Add PPA (Personal Package Archive)
sudo add-apt-repository ppa:user/repo-name
sudo apt update

# Remove PPA
sudo add-apt-repository --remove ppa:user/repo-name

# List all added repos
ls /etc/apt/sources.list.d/

# Remove PPA manually
sudo rm /etc/apt/sources.list.d/ppa-name.list
```

⚠️ **PPA Warning:** PPAs are third-party repositories. Only add PPAs from trusted sources as they have root access to your system.

### Cleaning Up

```bash
# Remove packages no longer needed
sudo apt autoremove --purge

# Clean package cache (saved .deb files)
sudo apt clean

# Clean only obsolete packages
sudo apt autoclean

# Show disk space used by cache
du -sh /var/cache/apt/archives/
```

### Complete Removal Example

```bash
# Example: Completely remove Firefox
sudo apt purge firefox
sudo apt autoremove
rm -rf ~/.mozilla/firefox/
rm -rf ~/.cache/mozilla/
```

---

## Installation Method 2: Flatpak

### What It Is

Flatpak is a **universal package manager** that works across all Linux distributions. Each app runs in a sandbox with bundled dependencies.

**How it works:**
1. Apps are packaged with all dependencies
2. Apps share common "runtimes" (GNOME, KDE, etc.)
3. Each app runs in its own sandbox
4. Files are stored in `~/.var/app/`

### When to Use

✅ **Use Flatpak when:**
- You need the latest version of software
- The app isn't in APT repos
- You want sandboxed security
- You want automatic updates

❌ **Don't use Flatpak when:**
- APT version is sufficient
- You're tight on disk space (larger than native)
- You need maximum performance
- You need deep system integration

### Basic Commands

```bash
# Add Flathub repository (usually pre-configured)
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Search for apps
flatpak search app-name

# Install app
flatpak install flathub org.example.AppName

# List installed apps
flatpak list

# List only apps (not runtimes)
flatpak list --app

# Run app
flatpak run org.example.AppName

# Update all apps
flatpak update

# Update specific app
flatpak update org.example.AppName

# Uninstall app
flatpak uninstall org.example.AppName

# Uninstall and delete data
flatpak uninstall --delete-data org.example.AppName

# Remove unused runtimes
flatpak uninstall --unused

# Repair Flatpak installation
flatpak repair
```

### File Locations

```
~/.var/app/org.example.AppName/    # App's sandboxed home
~/.local/share/flatpak/            # User's Flatpak data
/var/lib/flatpak/                  # System-wide Flatpak data
```

### Understanding Sandboxing

Flatpak apps are **sandboxed** by default with limited access:

```bash
# View app permissions
flatpak info --show-permissions org.example.AppName

# Override permissions (use carefully)
flatpak override --filesystem=home org.example.AppName

# Reset permissions
flatpak override --reset org.example.AppName
```

Common permission levels:
- `--filesystem=host` - Access all files
- `--filesystem=home` - Access home directory
- `--share=network` - Network access
- `--device=all` - Hardware access

### Flatpak in Software Manager

Linux Mint integrates Flatpak into the Software Manager:
- Flatpak apps show "Flatpak" badge
- Updates appear in Update Manager
- Can enable/disable Flatpak in preferences

### Disk Space Management

```bash
# Check Flatpak disk usage
du -sh ~/.local/share/flatpak/
du -sh /var/lib/flatpak/

# See what's using space
flatpak list --app --columns=application,size

# Clean up after uninstall
flatpak uninstall --unused
flatpak repair --user
```

### Complete Removal Example

```bash
# Example: Remove GIMP
flatpak uninstall --delete-data org.gimp.GIMP
flatpak uninstall --unused

# Verify removal
flatpak list | grep -i gimp
ls ~/.var/app/ | grep -i gimp
```

---

## Installation Method 3: Snap Packages

### What It Is

Snap is Ubuntu/Canonical's universal package manager, similar to Flatpak but with different design choices.

**How it works:**
1. Apps are fully self-contained
2. Each app includes all dependencies
3. Automatic updates in background
4. Sandboxed with AppArmor

### When to Use (Or Not)

⚠️ **Linux Mint removes Snap by default** because:
- Slower startup times
- Proprietary backend (Snap Store)
- Automatic updates can't be disabled
- Higher resource usage

✅ **Use Snap when:**
- Required by specific software
- No other option available

❌ **Avoid Snap when:**
- APT or Flatpak versions available
- On modest hardware (performance impact)
- You value system control

### Basic Commands

```bash
# List installed snaps
snap list

# Search for snap
snap find app-name

# Install snap
sudo snap install app-name

# Install from specific channel
sudo snap install app-name --channel=edge

# Update all snaps
sudo snap refresh

# Update specific snap
sudo snap refresh app-name

# Remove snap
sudo snap remove app-name

# Remove snap and data
sudo snap remove --purge app-name
```

### Disabling Snap (Linux Mint)

```bash
# Check if Snap is installed
which snap

# Remove all snaps
sudo snap list  # Note what's installed
for snap in $(snap list | awk 'NR>1 {print $1}'); do
    sudo snap remove --purge "$snap"
done

# Remove snapd
sudo apt purge snapd

# Remove snap directories
sudo rm -rf /snap /var/snap /var/lib/snapd ~/snap
```

---

## Installation Method 4: AppImage

### What It Is

AppImage is a **portable application format** - think of it like a Windows `.exe` file. One file contains everything needed to run the app.

**How it works:**
1. Download AppImage file
2. Make executable
3. Run directly - no installation
4. Delete file to "uninstall"

### When to Use

✅ **Use AppImage when:**
- You want a portable app
- Testing software before installing
- Running multiple versions
- No root access needed
- You want the simplest removal

❌ **Don't use AppImage when:**
- APT version is sufficient
- You want automatic updates
- You need system-wide installation

### Quick Start

```bash
# Download AppImage
cd ~/Downloads
wget https://example.com/app-name.AppImage

# Make executable
chmod +x app-name.AppImage

# Run it
./app-name.AppImage
```

### Proper Installation

Create organized structure:

```bash
# 1. Create Applications directory
mkdir -p ~/Applications

# 2. Move AppImage
mv ~/Downloads/app-name.AppImage ~/Applications/
chmod +x ~/Applications/app-name.AppImage

# 3. Extract icon (optional)
cd ~/Applications
./app-name.AppImage --appimage-extract
find squashfs-root -name "*.png" | head -1
cp squashfs-root/path/to/icon.png ~/Applications/app-name-icon.png
rm -rf squashfs-root

# 4. Create desktop entry
nano ~/.local/share/applications/app-name.desktop
```

Desktop entry template:

```ini
[Desktop Entry]
Type=Application
Name=Application Name
Comment=Brief description
Icon=/home/USERNAME/Applications/app-name-icon.png
Exec=/home/USERNAME/Applications/app-name.AppImage
Terminal=false
Categories=Office;  # Or: Network;Development;Graphics;AudioVideo;Game;Utility;
```

Make it visible:

```bash
chmod +x ~/.local/share/applications/app-name.desktop
update-desktop-database ~/.local/share/applications/
```

### Updating AppImages

```bash
# Download new version
wget https://example.com/app-name-new.AppImage -O ~/Downloads/app-name.AppImage

# Backup old version
mv ~/Applications/app-name.AppImage ~/Applications/app-name.AppImage.old

# Install new version
mv ~/Downloads/app-name.AppImage ~/Applications/
chmod +x ~/Applications/app-name.AppImage

# Test
~/Applications/app-name.AppImage

# Remove backup
rm ~/Applications/app-name.AppImage.old
```

### Complete Removal

```bash
# Remove AppImage
rm ~/Applications/app-name.AppImage
rm ~/Applications/app-name-icon.png

# Remove desktop entry
rm ~/.local/share/applications/app-name.desktop
update-desktop-database ~/.local/share/applications/

# Remove app data (if any)
rm -rf ~/.config/app-name/
rm -rf ~/.local/share/app-name/
```

### Troubleshooting AppImages

```bash
# FUSE error
sudo apt install fuse libfuse2

# Extract and run without FUSE
./app-name.AppImage --appimage-extract
./squashfs-root/AppRun

# Check missing libraries
ldd app-name.AppImage
```

---

## Installation Method 5: Tarball Archives

### What It Is

Tarballs (`.tar.gz`, `.tar.xz`, `.tar.bz2`) are **compressed archives** containing pre-compiled software. Common for proprietary software that doesn't fit package manager models.

**How it works:**
1. Download archive
2. Extract to chosen location
3. Run executable from extracted directory
4. Create shortcuts manually

### When to Use

✅ **Use Tarballs when:**
- Official releases provide only tarballs
- Software doesn't fit other formats
- You want specific installation location

❌ **Avoid when:**
- Any other method is available
- You're unsure about installation location

### Installation Process

```bash
# 1. Extract archive
cd ~/Downloads
tar -xzf app-name.tar.gz  # .tar.gz
tar -xJf app-name.tar.xz  # .tar.xz
tar -xjf app-name.tar.bz2 # .tar.bz2

# 2. Move to Applications
sudo mv app-name/ /opt/
# Or for user-only:
mv app-name/ ~/Applications/

# 3. Find executable
ls -la /opt/app-name/
# Look for: bin/, app-name, app-name.sh, etc.

# 4. Create symlink (optional)
sudo ln -s /opt/app-name/app-name /usr/local/bin/app-name

# 5. Create desktop entry (same as AppImage method)
```

### Common Locations

```
/opt/app-name/          # System-wide, industry standard
~/Applications/         # User-only, no root needed
~/.local/share/apps/    # Alternative user location
```

### Complete Removal

```bash
# Remove installation
sudo rm -rf /opt/app-name/

# Remove symlink
sudo rm /usr/local/bin/app-name

# Remove desktop entry
rm ~/.local/share/applications/app-name.desktop

# Remove user data
rm -rf ~/.config/app-name/
rm -rf ~/.local/share/app-name/
```

---

## Installation Method 6: Source Compilation

### What It Is

**Compiling from source** means downloading the program's source code and building it into an executable. This gives maximum control but requires technical knowledge.

**How it works:**
1. Install build dependencies
2. Download source code
3. Configure build
4. Compile
5. Install

### When to Use

✅ **Compile from source when:**
- You need bleeding-edge features
- Specific compile-time options required
- Contributing to development
- Learning about the software

❌ **Avoid when:**
- Any packaged version is acceptable
- You're unfamiliar with compilation
- Time is important (compilation is slow)

### Prerequisites

```bash
# Install build tools
sudo apt install build-essential

# Common dependencies
sudo apt install cmake autoconf automake libtool pkg-config \
                 git wget curl

# Programming language compilers
sudo apt install gcc g++ gfortran  # C/C++/Fortran
sudo apt install python3-dev       # Python headers
sudo apt install default-jdk       # Java
```

### Typical Build Process

```bash
# 1. Download source
git clone https://github.com/user/project.git
cd project/

# OR download tarball
wget https://example.com/project-1.2.3.tar.gz
tar -xzf project-1.2.3.tar.gz
cd project-1.2.3/

# 2. Read instructions
less README.md
less INSTALL.md

# 3. Configure
./configure --prefix=/usr/local
# Or with CMake:
mkdir build && cd build
cmake ..

# 4. Compile
make -j$(nproc)  # Use all CPU cores

# 5. Install
sudo make install

# 6. Update library cache
sudo ldconfig
```

### Using Checkinstall

**checkinstall** creates a `.deb` package from `make install`, making later removal easy:

```bash
# Install checkinstall
sudo apt install checkinstall

# Use instead of 'make install'
sudo checkinstall

# Now you can uninstall with apt
sudo apt remove package-name
```

### Common Installation Prefixes

```bash
--prefix=/usr/local    # Default, system-wide
--prefix=/opt/app      # Isolated system location
--prefix=$HOME/local   # User-only, no root needed
```

### Finding Installed Files

```bash
# After 'make install', files typically go to:
/usr/local/bin/         # Executables
/usr/local/lib/         # Libraries
/usr/local/share/       # Data files
/usr/local/include/     # Headers

# List what make install will do (without installing)
make -n install
```

### Uninstallation

```bash
# Option 1: make uninstall (if available)
cd ~/source/project/build/
sudo make uninstall

# Option 2: Checkinstall package
sudo apt remove package-name

# Option 3: Manual removal
sudo find /usr/local -name "*program*" -ls
sudo rm -rf /usr/local/bin/program
sudo rm -rf /usr/local/lib/libprogram*
sudo rm -rf /usr/local/share/program/

# Update system
sudo ldconfig
sudo mandb
```

---

## Installation Method 7: Third-Party Scripts

### What It Is

**Installation scripts** (usually `install.sh` or downloaded via `curl | bash`) are custom scripts that handle installation automatically.

**How it works:**
1. Download script
2. Script installs software anywhere it wants
3. May modify system files
4. Difficult to track changes

### When to Use

⚠️ **Extreme caution required**

✅ **Only use when:**
- From highly trusted source (official site)
- No other installation method exists
- You've reviewed the script

❌ **Never use when:**
- From unknown sources
- You haven't read the script
- Any alternative exists

### Safe Installation Process

```bash
# 1. Download script (DON'T RUN YET)
curl -fsSL https://example.com/install.sh -o install.sh

# 2. REVIEW THE SCRIPT
less install.sh
cat install.sh

# Look for:
# - Where files are installed
# - What system changes are made
# - If it requires root
# - If it modifies system files

# 3. If safe, make executable and run
chmod +x install.sh
./install.sh

# Or with sudo if needed
sudo ./install.sh
```

### Common Installation Locations

Scripts often install to:
```
~/.local/bin/           # User binaries
~/.local/share/         # User data
/opt/app-name/          # System-wide app
/usr/local/bin/         # System binaries
```

### Examples

**PyEnv (Python version manager):**
```bash
curl https://pyenv.run | bash
```

**NVM (Node version manager):**
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

**Docker:**
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

### Uninstallation

```bash
# 1. Check if uninstall script exists
ls ~/.local/bin/ | grep uninstall
ls /opt/program/ | grep uninstall

# 2. Check documentation
cat ~/.local/share/program/README.md

# 3. Manual removal (if no uninstaller)
# Find installed files
find ~ -name "*program*" 2>/dev/null
find /opt -name "*program*" 2>/dev/null

# Remove directories
rm -rf ~/.local/share/program/
rm -rf /opt/program/

# Check shell configs
grep -n "program" ~/.bashrc
grep -n "program" ~/.zshrc

# Remove added lines
nano ~/.bashrc
```

---

## Quick Reference: Choosing the Right Method

### Decision Tree

```
Do you need this software?
│
├─ YES → Is it in APT repos?
│         │
│         ├─ YES → Do you need latest version?
│         │         │
│         │         ├─ NO → ✅ Use APT
│         │         └─ YES → Is it in Flatpak?
│         │                   │
│         │                   ├─ YES → ✅ Use Flatpak
│         │                   └─ NO → Check AppImage/Tarball
│         │
│         └─ NO → Is it in Flatpak?
│                 │
│                 ├─ YES → ✅ Use Flatpak
│                 └─ NO → Is there an AppImage?
│                         │
│                         ├─ YES → ✅ Use AppImage
│                         └─ NO → Check official site
│
└─ NO → Don't install it!
```

### Priority Order

For most users:

1. **APT** - If available and version is acceptable
2. **Flatpak** - If you need latest version or APT unavailable
3. **AppImage** - For portable apps or testing
4. **Tarball** - Only if official releases use this
5. **Source** - Only if you need specific features
6. **Scripts** - Last resort, extreme caution

### Special Cases

**For developers:**
```
Programming tools → APT or Source
Version managers → Script (pyenv, nvm, rbenv)
IDEs → Flatpak or Tarball
```

**For casual users:**
```
Web browsers → APT or Flatpak
Office suites → APT or Flatpak
Media players → APT
Games → Flatpak or Steam
```

**For power users:**
```
Command-line tools → APT
Desktop applications → Flatpak
Portable tools → AppImage
Custom builds → Source
```

---

## System Maintenance Best Practices

### Daily/Weekly Habits

#### 1. Regular Updates

```bash
# Daily quick update (recommended)
sudo apt update && sudo apt upgrade -y

# Weekly full update
sudo apt update
sudo apt full-upgrade
flatpak update
```

Enable automatic updates:
```bash
# Edit Update Manager preferences
# Or enable unattended-upgrades
sudo apt install unattended-upgrades
sudo dpkg-reconfigure unattended-upgrades
```

#### 2. Monitor Disk Space

```bash
# Check disk usage
df -h

# Find large directories
du -sh ~/.cache
du -sh ~/.local/share/flatpak
du -sh /var/cache/apt/archives

# Find large files
du -ah ~ | sort -rh | head -20
```

### Weekly Maintenance

```bash
#!/bin/bash
# Save as ~/weekly-maintenance.sh

echo "=== Weekly System Maintenance ==="

# Update package lists
echo "Updating package lists..."
sudo apt update

# Upgrade packages
echo "Upgrading packages..."
sudo apt upgrade -y

# Remove unnecessary packages
echo "Removing unnecessary packages..."
sudo apt autoremove --purge -y

# Clean package cache
echo "Cleaning package cache..."
sudo apt autoclean

# Update Flatpaks
echo "Updating Flatpaks..."
flatpak update -y

# Remove unused Flatpak runtimes
echo "Removing unused Flatpaks..."
flatpak uninstall --unused -y

# Clean thumbnails
echo "Cleaning thumbnails..."
rm -rf ~/.cache/thumbnails/*

# Show disk usage
echo "Disk usage:"
df -h / /home

echo "=== Maintenance complete! ==="
```

Make it executable:
```bash
chmod +x ~/weekly-maintenance.sh
```

### Monthly Tasks

#### 1. Review Installed Software

```bash
# List all installed packages
dpkg -l > ~/installed-packages.txt

# List Flatpaks
flatpak list > ~/installed-flatpaks.txt

# List AppImages
ls -lh ~/Applications/*.AppImage > ~/installed-appimages.txt

# Review and remove unused software
```

#### 2. Clean Up Cache Directories

```bash
# Browser caches
rm -rf ~/.cache/mozilla/firefox/*/cache2/*
rm -rf ~/.cache/chromium/Default/Cache/*

# Thumbnail cache
rm -rf ~/.cache/thumbnails/*

# Application caches
du -sh ~/.cache/* | sort -rh | head -20
# Review and delete as needed
```

#### 3. Review Startup Applications

```bash
# List startup applications
ls ~/.config/autostart/

# Disable unnecessary ones
# Use Settings → Session and Startup
```

### Quarterly Tasks

#### 1. Clean Old Kernels

```bash
# List installed kernels
dpkg -l | grep linux-image

# Keep current + one previous
sudo apt autoremove --purge

# Verify boot still works after reboot
```

#### 2. Review User Directories

```bash
# Find old/large files
find ~ -type f -size +100M
find ~ -type f -mtime +365  # Not modified in 1 year

# Review directories
du -sh ~/Downloads
du -sh ~/Documents
du -sh ~/.local/share
```

#### 3. Backup System

```bash
# Create Timeshift snapshot
sudo timeshift --create --comments "Quarterly backup"

# Backup home directory
tar -czf ~/backup-$(date +%Y%m%d).tar.gz \
  ~/Documents ~/Pictures ~/Videos ~/.config
```

### System Health Checks

#### Check for Broken Packages

```bash
# Find broken dependencies
sudo apt check

# Fix broken packages
sudo apt --fix-broken install

# Reconfigure packages
sudo dpkg --configure -a
```

#### Check System Logs

```bash
# Recent errors
sudo journalctl -p err -b

# Last boot messages
sudo journalctl -b -1

# Specific service
sudo journalctl -u service-name
```

#### Check Disk Health

```bash
# Check filesystem
sudo touch /forcefsck  # Check on next boot

# Check SMART status (for HDDs/SSDs)
sudo apt install smartmontools
sudo smartctl -a /dev/sda
```

### Documentation Best Practices

#### Keep an Installation Log

```bash
# Create log file
nano ~/installation-log.md
```

```markdown
# System Installation Log

## 2025-10-26
- Installed: onlyoffice-desktopeditors (flatpak)
- Reason: Office suite for work
- Notes: Using Flatpak for latest version

## 2025-10-25
- Installed: kanri.AppImage
- Location: ~/Applications/kanri.AppImage
- Reason: Kanban board for project management
```

#### Document Configuration Changes

```bash
# Before changing configs
cp /etc/important.conf /etc/important.conf.backup

# Add comment to modified files
sudo nano /etc/important.conf
# Add: # Modified 2025-10-26 - Changed setting X to Y
```

---

## Troubleshooting Common Issues

### Problem: "Package not found"

```bash
# Update package lists
sudo apt update

# Search with correct name
apt search package

# Check if it's in a PPA
# Google: "package-name ubuntu ppa"

# Try Flatpak
flatpak search package-name
```

### Problem: Dependency Errors

```bash
# When installing .deb file
sudo apt install ./package.deb  # Not dpkg -i

# Fix broken dependencies
sudo apt --fix-broken install

# Force install (use carefully)
sudo dpkg -i --force-depends package.deb
sudo apt --fix-broken install
```

### Problem: "Package has unmet dependencies"

```bash
# This usually means:
# 1. You're installing a package for wrong Ubuntu version
# 2. You have conflicting PPAs

# Solution 1: Check package version
apt policy package-name

# Solution 2: Remove conflicting PPAs
ls /etc/apt/sources.list.d/

# Solution 3: Use aptitude (smarter resolver)
sudo apt install aptitude
sudo aptitude install package-name
```

### Problem: Flatpak App Won't Start

```bash
# Check for errors
flatpak run org.example.App

# Repair Flatpak
flatpak repair

# Clear app cache
rm -rf ~/.var/app/org.example.App/cache

# Reset app data (LAST RESORT)
flatpak uninstall --delete-data org.example.App
flatpak install org.example.App
```

### Problem: AppImage Won't Run

```bash
# Make executable
chmod +x app-name.AppImage

# Install FUSE
sudo apt install fuse libfuse2

# Extract and run
./app-name.AppImage --appimage-extract
./squashfs-root/AppRun

# Check for missing libraries
ldd app-name.AppImage
```

### Problem: Command Not Found After Installation

```bash
# Refresh shell
source ~/.bashrc

# Or
hash -r

# Check PATH
echo $PATH

# Find executable
which command-name

# If in /usr/local/bin, add to PATH
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### Problem: System Running Out of Space

```bash
# Find space hogs
sudo du -sh /* | sort -rh | head -20

# Common culprits:
du -sh /var/cache/apt/archives  # APT cache
du -sh ~/.cache                 # User cache
du -sh ~/.local/share/flatpak   # Flatpak
du -sh /var/log                 # System logs

# Clean up
sudo apt clean
rm -rf ~/.cache/thumbnails
flatpak uninstall --unused
sudo journalctl --vacuum-time=7d
```

### Problem: Package Manager is Locked

```bash
# Error: "Could not get lock /var/lib/dpkg/lock"

# Check what's using it
sudo lsof /var/lib/dpkg/lock
sudo lsof /var/lib/apt/lists/lock

# Kill if hung
sudo killall apt apt-get

# Remove lock (ONLY IF NOTHING IS RUNNING)
sudo rm /var/lib/dpkg/lock
sudo rm /var/lib/apt/lists/lock
sudo rm /var/cache/apt/archives/lock

# Reconfigure
sudo dpkg --configure -a
```

---

## Advanced Tips & Tricks

### Multiple Versions of Software

#### Using Alternatives System

```bash
# Install multiple versions of Python
sudo apt install python3.10 python3.11 python3.12

# Configure alternatives
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 2
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 3

# Switch between versions
sudo update-alternatives --config python3

# Check current version
python3 --version
```

#### Using Environment Modules

```bash
# Install environment modules
sudo apt install environment-modules

# Create module files
sudo mkdir -p /usr/share/modules/modulefiles/app-name

sudo nano /usr/share/modules/modulefiles/app-name/1.0
```

```tcl
#%Module1.0
proc ModulesHelp { } {
  puts stderr "App Name v1.0"
}
module-whatis "App Name v1.0"

prepend-path PATH /opt/app-name-1.0/bin
prepend-path LD_LIBRARY_PATH /opt/app-name-1.0/lib
```

```bash
# Use it
module avail
module load app-name/1.0
module list
module unload app-name/1.0
```

### Version Managers

For programming languages, use dedicated version managers:

```bash
# Python: pyenv
curl https://pyenv.run | bash

# Node.js: nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Ruby: rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv

# Java: SDKMAN!
curl -s "https://get.sdkman.io" | bash
```

### Container-Based Installations

#### Using Docker

```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Run application in container
docker run -it --rm \
  -v $HOME:/root \
  -v $(pwd):/work \
  ubuntu:22.04 bash

# Persistent container
docker run -d --name myapp \
  -v $HOME/data:/data \
  myapp:latest
```

#### Using Podman (Docker alternative)

```bash
# Install Podman
sudo apt install podman

# Use like Docker
podman run -it ubuntu:22.04 bash
```

### Creating Your Own Packages

#### Simple .deb Package

```bash
# Install packaging tools
sudo apt install dpkg-dev debhelper

# Create package structure
mkdir myapp-1.0
cd myapp-1.0
mkdir -p DEBIAN usr/bin usr/share/applications

# Create control file
nano DEBIAN/control
```

```
Package: myapp
Version: 1.0
Section: base
Priority: optional
Architecture: amd64
Maintainer: Your Name <your@email.com>
Description: My Application
 A longer description of my application
```

```bash
# Add files
cp myapp usr/bin/
chmod +x usr/bin/myapp

# Build package
cd ..
dpkg-deb --build myapp-1.0

# Install
sudo dpkg -i myapp-1.0.deb
```

### System Snapshot Before Changes

```bash
# Take Timeshift snapshot
sudo timeshift --create --comments "Before installing X"

# Or manually backup key directories
tar -czf backup-$(date +%Y%m%d-%H%M).tar.gz \
  ~/.config \
  ~/.local/share \
  /etc
```

### Recovery: Bootable USB with Timeshift

If system breaks:
1. Boot from Linux Mint USB
2. Open Timeshift
3. Select backup location
4. Restore snapshot
5. Reboot

---

## Summary & Best Practices Checklist

### Installation Decision Flowchart

```
1. Check APT repos          → APT available? → Use APT
   │
   └→ Not in APT
      │
      2. Check Flatpak      → Available? → Use Flatpak
         │
         └→ Not in Flatpak
            │
            3. Check AppImage → Available? → Use AppImage
               │
               └→ Not available
                  │
                  4. Check official site
                     │
                     ├→ Tarball? → Extract to ~/Applications
                     ├→ .deb? → sudo apt install ./file.deb
                     ├→ Script? → Review carefully, then run
                     └→ Source? → Compile if necessary
```

### Golden Rules

1. **Always prefer package managers** over manual installation
2. **Document what you install** in a log file
3. **Take Timeshift snapshots** before major changes
4. **Review scripts** before running with sudo
5. **Clean up regularly** - weekly maintenance routine
6. **Update frequently** - security patches are important
7. **Use sandboxed formats** (Flatpak) for untrusted software
8. **Keep /home separate** from / (root) partition
9. **Test before removing** - check dependencies
10. **When in doubt, ask** - Linux community is helpful

### Quick Commands Cheatsheet

```bash
# APT
sudo apt update && sudo apt upgrade
sudo apt install package
sudo apt purge package
sudo apt autoremove --purge

# Flatpak
flatpak install flathub org.app.Name
flatpak update
flatpak uninstall --delete-data org.app.Name
flatpak uninstall --unused

# AppImage
chmod +x app.AppImage
./app.AppImage

# System
df -h                          # Disk space
du -sh ~/.cache               # Cache size
sudo apt clean                # Clear APT cache
flatpak repair                # Fix Flatpak
sudo timeshift --create       # Snapshot
```

### Maintenance Schedule

**Daily:**
- Nothing required (auto-updates handle this)

**Weekly:**
- Run weekly maintenance script
- Review disk space

**Monthly:**
- Review installed software
- Clean caches
- Update AppImages

**Quarterly:**
- Full system backup
- Remove old kernels
- Review logs

---

## Additional Resources

### Official Documentation

- [APT Documentation](https://manpages.ubuntu.com/manpages/focal/man8/apt.8.html)
- [Flatpak Documentation](https://docs.flatpak.org/)
- [AppImage Documentation](https://docs.appimage.org/)

### Community Resources

- [Linux Mint Forums](https://forums.linuxmint.com/)
- [Ask Ubuntu](https://askubuntu.com/)
- [r/linuxmint](https://reddit.com/r/linuxmint)
- [r/linux4noobs](https://reddit.com/r/linux4noobs)

### Helpful Wikis

- [Arch Wiki](https://wiki.archlinux.org/) (concepts apply to all distros)
- [Debian Wiki](https://wiki.debian.org/)
- [Ubuntu Wiki](https://wiki.ubuntu.com/)

---

## Conclusion

Linux software installation can seem overwhelming at first, but it becomes intuitive with practice. The diversity of installation methods exists to serve different needs:

- **APT** for system stability and integration
- **Flatpak** for latest versions and security
- **AppImage** for portability and simplicity
- **Others** for special cases

By following the best practices in this guide, you'll maintain a clean, efficient, and stable Linux system. Remember:

> "The best installation method is the one that makes your software easy to maintain and remove."

When in doubt, choose the method highest on the priority list, document your installations, and keep regular backups.

Happy Linux computing!

---

**Document Version:** 1.0  
**Last Updated:** October 2025  
**For:** Linux Mint 22+ / Ubuntu 24.04+  
**License:** Free to use, share, and modify

---

## Appendix: Quick Reference Tables

### File System Locations

| Directory | Purpose | Who Can Write |
|-----------|---------|---------------|
| `/bin`, `/usr/bin` | Essential user commands | Root only |
| `/sbin`, `/usr/sbin` | System administration commands | Root only |
| `/lib`, `/usr/lib` | System libraries | Root only |
| `/opt` | Third-party applications | Root only |
| `/usr/local` | Locally compiled software | Root only |
| `/etc` | System configuration | Root only |
| `~/.local/bin` | User binaries | User |
| `~/.local/share` | User application data | User |
| `~/.config` | User configuration | User |
| `~/Applications` | User AppImages (custom) | User |

### Package Manager Commands

| Task | APT | Flatpak | Snap |
|------|-----|---------|------|
| Update lists | `sudo apt update` | N/A | N/A |
| Upgrade all | `sudo apt upgrade` | `flatpak update` | `sudo snap refresh` |
| Search | `apt search NAME` | `flatpak search NAME` | `snap find NAME` |
| Install | `sudo apt install NAME` | `flatpak install flathub NAME` | `sudo snap install NAME` |
| Remove | `sudo apt purge NAME` | `flatpak uninstall NAME` | `sudo snap remove NAME` |
| List installed | `dpkg -l` | `flatpak list` | `snap list` |
| Info | `apt show NAME` | `flatpak info NAME` | `snap info NAME` |
| Clean | `sudo apt autoremove` | `flatpak uninstall --unused` | N/A |

---

*End of Guide*