Flatpak: Universal Application Distribution System

Table of Contents

Introduction

Flatpak is a modern application distribution framework that provides a universal package format for Linux desktop applications. It enables developers to distribute applications across different Linux distributions while ensuring consistent behavior and security through sandboxing.

Key Features

| Feature | Description | |---------|-------------| | Universal Packages | Single package works across multiple Linux distributions | | Sandboxing | Applications run in isolated environments with controlled permissions | | Runtime Independence | Applications bundle their dependencies, reducing conflicts | | Forward/Backward Compatibility | Applications continue working across system updates | | Decentralized Distribution | Multiple repositories can coexist | | Developer Friendly | Simplified packaging and distribution process |

Benefits

- For Users: Easy installation, automatic updates, consistent behavior - For Developers: Simplified distribution, reduced testing overhead - For Distributions: Reduced maintenance burden for application packages

Architecture and Core Concepts

Core Components

#### Applications Self-contained software packages that include all necessary dependencies and run in sandboxed environments.

#### Runtimes Shared libraries and frameworks that multiple applications can use. Common runtimes include:

| Runtime | Purpose | Examples | |---------|---------|----------| | org.freedesktop.Platform | Base runtime with core libraries | GTK, Qt applications | | org.gnome.Platform | GNOME-specific libraries | GNOME applications | | org.kde.Platform | KDE-specific libraries | KDE applications | | org.freedesktop.Sdk | Development tools and headers | Building applications |

#### Repositories (Remotes) Sources from which Flatpak downloads applications and runtimes.

| Repository | URL | Purpose | |------------|-----|---------| | Flathub | https://flathub.org | Primary community repository | | GNOME Nightly | https://nightly.gnome.org | Development versions of GNOME apps | | KDE Applications | https://distribute.kde.org | KDE application repository |

Sandboxing Model

Flatpak uses several Linux kernel features for sandboxing:

- Namespaces: Isolate processes from system resources - Seccomp: Filter system calls - Bind mounts: Control filesystem access - D-Bus proxying: Mediate inter-process communication

Installation

System Requirements

- Linux kernel 3.10 or newer - systemd (recommended) - D-Bus - PolicyKit (for system-wide installations)

Distribution-Specific Installation

| Distribution | Installation Command | |--------------|---------------------| | Ubuntu/Debian | sudo apt install flatpak | | Fedora | sudo dnf install flatpak | | CentOS/RHEL | sudo yum install flatpak | | Arch Linux | sudo pacman -S flatpak | | openSUSE | sudo zypper install flatpak | | Gentoo | sudo emerge sys-apps/flatpak |

Post-Installation Setup

After installing Flatpak, add the Flathub repository:

`bash flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo `

For system-wide installation: `bash sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo `

Basic Commands

Command Structure

` flatpak [OPTION...] COMMAND [COMMAND-OPTIONS] [ARGS...] `

Essential Commands Overview

| Command | Purpose | Scope | |---------|---------|-------| | install | Install applications or runtimes | User/System | | uninstall | Remove applications or runtimes | User/System | | list | Show installed applications | User/System | | search | Find available applications | Repository | | run | Execute applications | User | | update | Update applications and runtimes | User/System | | info | Display application information | Repository/Local |

Global Options

| Option | Description | |--------|-------------| | --user | Operate on user installation (default) | | --system | Operate on system-wide installation | | --installation=NAME | Use specific installation | | --arch=ARCH | Specify architecture | | --verbose | Show detailed output | | --ostree-verbose | Show OSTree-level output |

Repository Management

Adding Repositories

#### Adding Flathub (Primary Repository) `bash flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo `

#### Adding Custom Repositories `bash flatpak remote-add custom-repo https://example.com/repo/custom.flatpakrepo `

#### Adding GPG Keys for Verification `bash flatpak remote-add --gpg-import=keyfile.gpg custom-repo https://example.com/repo `

Repository Management Commands

| Command | Description | Example | |---------|-------------|---------| | remote-add | Add new repository | flatpak remote-add flathub URL | | remote-delete | Remove repository | flatpak remote-delete flathub | | remote-list | List configured repositories | flatpak remote-list | | remote-modify | Modify repository settings | flatpak remote-modify --enable flathub | | remote-info | Show repository information | flatpak remote-info flathub org.gimp.GIMP |

Repository Configuration Options

`bash

Disable a repository

Enable a repository

Set repository priority

Configure repository for subset of architectures

Application Management

Installing Applications

#### Basic Installation `bash flatpak install flathub org.gimp.GIMP `

#### Installation Options

| Option | Description | Example | |--------|-------------|---------| | --user | Install for current user only | flatpak install --user flathub org.gimp.GIMP | | --system | Install system-wide | flatpak install --system flathub org.gimp.GIMP | | --no-deps | Don't install dependencies | flatpak install --no-deps org.gimp.GIMP | | --or-update | Install or update if exists | flatpak install --or-update org.gimp.GIMP |

#### Installing from File `bash flatpak install application.flatpak `

#### Installing Specific Versions `bash flatpak install flathub org.gimp.GIMP//2.10 `

Searching Applications

#### Basic Search `bash flatpak search gimp `

#### Advanced Search Options `bash

Search in specific repository

Show detailed information

Running Applications

#### Standard Execution `bash flatpak run org.gimp.GIMP `

#### Runtime Options

| Option | Description | Example | |--------|-------------|---------| | --branch=BRANCH | Use specific branch | flatpak run --branch=stable org.gimp.GIMP | | --arch=ARCH | Use specific architecture | flatpak run --arch=x86_64 org.gimp.GIMP | | --command=COMMAND | Run specific command | flatpak run --command=sh org.gimp.GIMP | | --devel | Use development version | flatpak run --devel org.gimp.GIMP |

#### Permission Overrides `bash

Grant additional filesystem access

Allow network access

Enable device access

Updating Applications

#### Update All Applications `bash flatpak update `

#### Update Specific Application `bash flatpak update org.gimp.GIMP `

#### Update Options

| Option | Description | |--------|-------------| | --no-deps | Don't update dependencies | | --no-related | Don't update related refs | | --commit=COMMIT | Update to specific commit |

Uninstalling Applications

#### Basic Uninstallation `bash flatpak uninstall org.gimp.GIMP `

#### Uninstall Options

| Option | Description | |--------|-------------| | --keep-data | Preserve application data | | --delete-data | Remove application data | | --unused | Remove unused runtimes | | --all | Remove all applications |

#### Clean Up Unused Dependencies `bash flatpak uninstall --unused `

Runtime Management

Understanding Runtimes

Runtimes provide the base environment for applications. They contain: - Core libraries (glibc, GTK, Qt) - System services - Development tools (for SDK variants)

Common Runtime Patterns

| Runtime ID | Description | Size (Approx.) | |------------|-------------|----------------| | org.freedesktop.Platform | Base runtime | 200-300 MB | | org.gnome.Platform | GNOME stack | 400-500 MB | | org.kde.Platform | KDE stack | 400-600 MB | | org.freedesktop.Sdk | Development tools | 800-1000 MB |

Runtime Management Commands

#### List Installed Runtimes `bash flatpak list --runtime `

#### Install Runtime Manually `bash flatpak install flathub org.freedesktop.Platform//21.08 `

#### Runtime Information `bash flatpak info org.freedesktop.Platform `

Runtime Versions and Branches

Runtimes follow semantic versioning: - Stable branches: 20.08, 21.08, 22.08 - Beta branches: 21.08beta, 22.08beta - Development branches: master

Permissions and Security

Flatpak Permission System

Flatpak uses a capability-based security model where applications request specific permissions.

Permission Categories

| Category | Description | Examples | |----------|-------------|----------| | Filesystem | File system access | home, host, ~/Documents | | Device | Hardware device access | dri, kvm, all | | Features | System features | devel, multiarch, bluetooth | | Sockets | Communication sockets | x11, wayland, pulseaudio | | Bus | D-Bus access | session, system |

Common Permissions

#### Filesystem Permissions `bash

Full home directory access

Specific directory access

Read-only access

Host filesystem access (dangerous)

#### Device Permissions `bash

Graphics acceleration

All devices (very dangerous)

KVM virtualization

#### Socket Permissions `bash

X11 display server

Wayland display server

Audio system

Network access

Managing Application Permissions

#### View Current Permissions `bash flatpak info --show-permissions org.gimp.GIMP `

#### Override Permissions Globally `bash flatpak override --filesystem=~/Projects org.gimp.GIMP `

#### Reset Permission Overrides `bash flatpak override --reset org.gimp.GIMP `

#### System-wide Permission Management `bash

Apply to all users

View system overrides

Configuration and Customization

Flatpak Configuration Locations

| Path | Purpose | |------|---------| | ~/.local/share/flatpak/ | User applications and data | | /var/lib/flatpak/ | System-wide applications | | ~/.config/flatpak/ | User configuration | | /etc/flatpak/ | System configuration |

Environment Variables

#### Flatpak-Specific Variables `bash

Override installation directory

Enable debug output

Disable sandboxing (development only)

#### Application Environment Variables `bash

Pass environment variables to applications

Set multiple variables

Custom Installation Directories

#### Create Custom Installation `bash flatpak --installation=custom install --user flathub org.gimp.GIMP `

#### List Custom Installations `bash flatpak installations `

Repository Configuration Files

#### User Repository Configuration Location: ~/.local/share/flatpak/repo/config

`ini [core] repo_version=1 mode=archive-z2

[remote "flathub"] url=https://flathub.org/repo/ gpg-verify=true `

Troubleshooting

Common Issues and Solutions

#### Issue: Application Won't Start

Symptoms: Application launches but immediately closes or shows error

Diagnostic Commands: `bash

Run with verbose output

Check application logs

Run with development permissions

Solutions: 1. Update the application: flatpak update org.app.Name 2. Reset permissions: flatpak override --reset org.app.Name 3. Check for missing runtimes: flatpak list --runtime

#### Issue: Permission Denied Errors

Symptoms: Application cannot access files or resources

Diagnostic Commands: `bash

Check current permissions

View permission overrides

Solutions: `bash

Grant filesystem access

Grant device access

Grant network access

#### Issue: Repository Connection Problems

Symptoms: Cannot download or update applications

Diagnostic Commands: `bash

Test repository connectivity

Check repository status

Solutions: `bash

Refresh repository metadata

Re-add repository

Debugging Commands

| Command | Purpose | |---------|---------| | flatpak --verbose | Enable verbose output | | flatpak --ostree-verbose | Show OSTree operations | | strace -f flatpak run app | Trace system calls | | FLATPAK_DEBUG=1 flatpak run app | Enable debug mode |

Log Locations

| Log Type | Location | |----------|----------| | User Session | journalctl --user | | System | journalctl -u flatpak-system-helper | | Application | ~/.local/share/flatpak/app/APP_ID/current/active/files/ |

Best Practices

For Users

#### Security Considerations 1. Review Permissions: Always check what permissions an application requests 2. Use Minimal Permissions: Grant only necessary access 3. Regular Updates: Keep applications and runtimes updated 4. Trusted Sources: Install applications from reputable repositories

#### Performance Optimization `bash

Clean up unused runtimes

Remove old application data

Optimize repository metadata

#### Storage Management `bash

Check disk usage

List largest applications

For Developers

#### Application Packaging 1. Minimal Permissions: Request only essential permissions 2. Proper Runtime Selection: Choose appropriate base runtime 3. Metadata Quality: Provide comprehensive AppStream metadata 4. Testing: Test across different distributions and environments

#### Distribution Strategy 1. Flathub Submission: Primary distribution channel 2. CI/CD Integration: Automate builds and testing 3. Version Management: Use semantic versioning for releases 4. Documentation: Provide clear installation and usage instructions

Examples

Example 1: Installing and Running GIMP

`bash

Add Flathub repository

Search for GIMP

Install GIMP

Run GIMP

Check GIMP information

Example 2: Managing Development Environment

`bash

Install development runtime

Install code editor

Grant additional filesystem access for development

Run with development tools

Example 3: System Administration

`bash

List all installed applications (system and user)

Update all applications system-wide

Clean up unused runtimes system-wide

Set global permission policy

Example 4: Custom Repository Setup

`bash

Add custom repository with GPG verification

Install application from custom repository

List applications from specific repository

Example 5: Troubleshooting Application Issues

`bash

Application won't start - gather information

Run with verbose output

Try with additional permissions

If working, make permanent

Reset if issues persist

This comprehensive guide covers the essential aspects of Flatpak, from basic installation and usage to advanced configuration and troubleshooting. The modular nature of Flatpak makes it a powerful tool for both users seeking easy application management and developers looking for universal distribution solutions.