KStars for Linux

What is Flatpak?

Flatpak is a modern packaging and distribution system for Linux applications. It allows developers to bundle an app with all its dependencies into a single, portable package that runs consistently across different Linux distributions. In other words, the same Flatpak version of KStars will run on Ubuntu, Fedora, Arch, openSUSE, and many other systems — without modification.

How is Flatpak Different from Normal Packages?

Traditional Linux packages (like .deb or .rpm) rely on the host system’s libraries and configurations. This often leads to compatibility issues between distributions or when a required library is missing or outdated. Flatpak solves this by:

• Bundling dependencies with the app (ensuring version consistency).
• Running in a sandbox for better security and isolation.
• Receiving updates independently of the operating system.
• Working across all major Linux distributions.

However, it also means Flatpak apps are slightly larger in size and may have limited access to some system files unless permissions are granted.

Flatpak Variants of KStars

There are currently two main builds:

Stable Release (Flathub)

Package: org.kde.kstars//stable Maintained and published by KDE on Flathub. Released every two months. Ideal for most users who want reliability and regular updates.

Master (Development) Build (KDE Nightly)

Package: org.kde.kstars//master Built directly from KStars’ master branch. Released on a nightly basis. Includes the latest features and fixes, but may be unstable or experimental.

Both can be installed side-by-side without conflict. You can test new features in the master build while keeping the stable version for everyday use.

Installation

To install KStars using Flatpak:

wget https://raw.githubusercontent.com/ikarustechnologies/indi-firmware/main/kstars.sh
bash kstars.sh

By default, it will install the stable version. To install the latest nightly version, run:

bash kstars.sh nightly

The script will guide you through the installation process. You may be prompted for your password for sudo commands.

Update

The script above also updates the app in case you already have it. To manually update, use the command below:

flatpak update org.kde.kstars

Flatpak Permissions

The KStars Flatpak includes a broad set of permissions to ensure full hardware and system integration while maintaining security:

• Access to Documents, Pictures, and Videos for saving and loading files.
• Access to ~/.indi for telescope and equipment profiles.
• Access to network, audio, and both X11/Wayland display systems.
• All devices are exposed for astronomical camera and mount communication.
• The environment variable GSCDAT points to the Guide Star Catalog data.

Migrating Existing KStars Settings

If you used a system-installed version of KStars before (via apt, dnf, etc.), you can copy your settings into the Flatpak environment:

cp -r ~/.config/kstarsrc ~/.var/app/org.kde.kstars/config/
cp -r ~/.local/share/kstars ~/.var/app/org.kde.kstars/data/

After copying, launch KStars (Flatpak version). Your existing settings, observatory locations, and INDI profiles will be preserved.

Configuring Ekos Directory Paths

Open KStars → Ekos → Capture -> Directory Paths.

⚠️ Critical: You Must Explicitly Select Pictures Directory

Due to Flatpak's XDG Document Portal, you must explicitly select your directories through the file chooser dialog at least once. This applies to Pictures Directory and also any other document directories for Sequences and Scheduler files.

Why this is important:

• Flatpak apps must use the Document Portal to access files outside their sandbox
• Hardcoded or default paths don't grant automatic access—even if they display a path like /home/stellarmate/Pictures
• If you skip explicit selection, files will be written to temporary directories like /run/user/1000/doc/... that are hard to find and access later

What to do:

1. For each directory setting, click the folder icon and explicitly select your desired location
2. You only need to do this once—after initial selection, the paths will persist
3. Choose permanent, easily accessible locations in your home directory (e.g., ~/Pictures, ~/Documents/Ekos)
4. Verify the paths are correct before starting your sessions

This is a Flatpak security feature, not a bug. Taking a moment to set these paths correctly will save you from losing files in obscure temporary locations.

Limitations of Flatpak

• File access restrictions: Apps run in a sandbox and don’t have full access to your filesystem. By default, only ~/Documents, ~/Videos, ~/Pictures, and ~/.indi directories are accessible.
• Hardware access: Some drivers or USB devices may require additional configurations (If Kstars is installed using our script, these configurations are done automatically).
• Performance: Minor startup overhead due to sandboxing.
• Disk usage: Flatpak runtimes (shared environments) add extra storage, though they’re reused across apps.