kst4contest/github_docs/en-Installation.md

Installation

🇬🇧 You are reading the English version | 🇩🇪 Deutsche Version

KST4Contest is distributed as a ready-to-run application package for Windows, Linux and macOS. The official release packages do not require a separate Java installation: the required Java runtime is already included.

In practical terms, you need a supported operating system, an internet connection and an ON4KST account. That sounds manageable—and usually it is.

Requirements

ON4KST account

KST4Contest is an independent client for the ON4KST chat, but it does not replace the corresponding user account.

If you do not have an account yet, you can create one on the official ON4KST website:

• ON4KST login and registration

ON4KST specifies English as the common language for the chat. This also applies when both stations happen to share another language. During contests, the usual amateur radio abbreviations such as pse, agn, qrg, dir, rrr, tnx and 73 are widely used.

Using the chat and sending personal messages are covered in the user interface chapter. For the installation, the only thing that matters at this point is that the account works.

Screen size

A usable screen area of approximately 1200 × 720 pixels or more is recommended.

KST4Contest automatically adapts the main window to the available area of the primary screen. The application can therefore also be started on smaller displays. Less space is still less space, however: not all tables, filters and additional information can then be displayed at a useful size at the same time.

Java

The ready-made packages from the GitHub Releases do not require a separate Java installation. The required runtime is distributed with KST4Contest.

A Java development environment is only required if you want to build KST4Contest from source. For the AUR packages kst4contest and kst4contest-git, Java 21 and Maven are handled as build dependencies by the package manager.

---

Stable, Beta or Nightly?

KST4Contest is distributed through three development channels:

Channel	Intended use	Classification
Stable	Normal contest operation	Published version intended for regular use
Beta	Focused testing before a Stable release	Pre-release version with a largely defined feature set
Nightly	Early testing of new features	Current development state from the main branch

The Stable version is recommended for normal operation.

Beta and Nightly builds may contain features that are not yet available in the Stable release. They may also contain unfinished workflows, changed settings or new defects. That is not an unusual failure of the release process; it is the purpose of a development channel.

If a function in this manual is explicitly marked as Nightly, it is not necessarily part of the current Stable release yet.

---

Download

The current Stable version is available here:

• Latest KST4Contest release
• All published releases

The release page contains the application packages as well as the English and German PDF manuals.

Which package do I need?

Operating system	Package	Typical filename
Windows x64	MSI installer	KST4Contest-v<version>-windows-x64.msi
Windows x64	ZIP package (portable)	praktiKST-v<version>-windows-x64.zip
Linux x86_64	AppImage	KST4Contest-v<version>-linux-x86_64.AppImage
Debian/Ubuntu amd64	DEB package	KST4Contest-v<version>-debian-amd64.deb
Fedora/RPM x86_64	RPM package	KST4Contest-v<version>-fedora-x86_64.rpm
Arch Linux x86_64	Arch package	KST4Contest-v<version>-archlinux-x86_64.pkg.tar.zst
Linux with Flatpak	Flatpak reference	de.x08.KST4Contest.flatpakref
macOS Apple Silicon	DMG for ARM64	KST4Contest-v<version>-macos-arm64.dmg
macOS Intel	DMG for x86_64	KST4Contest-v<version>-macos-x86_64.dmg

Only download application packages from the official GitHub Releases, the KST4Contest Flatpak repository or the linked AUR packages. Files from other sources may have been built differently, may be outdated or may have been modified.

---

Installing on Windows

KST4Contest is distributed for Windows in two forms: as an MSI installer and as a portable ZIP package. Both contain the same application with the same bundled runtime; they differ only in how the application gets onto the computer. The MSI installer is built for stable releases only: a beta installer would carry the same version number as the following stable release, and Windows Installer refuses to install an equal version over an installed one. Beta and nightly builds for Windows are therefore provided as the ZIP package only.

Form	Useful when …
MSI installer	KST4Contest should be installed and updated like an ordinary Windows application, with a Start menu entry
ZIP package	KST4Contest should run from any folder without installation, for example from a USB stick

MSI installer

1. Download KST4Contest-v<version>-windows-x64.msi from the latest release.
2. Start the downloaded file.
3. Keep the suggested installation folder or choose a different one, then finish the installer.
4. Start KST4Contest from the Start menu entry in the KST4Contest group or from the desktop shortcut.

The installer sets up KST4Contest for the current Windows user account only. Administrator rights are not required, and User Account Control does not ask for confirmation. A newer version is simply installed over the existing one: the installer replaces the previous installation, so there is no need to uninstall first. KST4Contest is removed like any other application through the Windows settings under Apps → Installed apps.

The installer is not signed with a code-signing certificate. If Windows shows a warning when it starts, the notes under Windows reports an unknown application apply.

ZIP package

1. Download praktiKST-v<version>-windows-x64.zip from the latest release.
2. Extract the ZIP file completely into a dedicated folder.
3. Open the extracted folder.
4. Start praktiKST.exe.

Do not start the application directly from the compressed ZIP file. KST4Contest consists of several files and a bundled runtime. Windows can only use this structure reliably after the archive has been extracted completely.

Settings and data

With both forms, the application settings and the worked-stations database are not stored in the program directory. They are stored in your user profile:

%USERPROFILE%\.praktiKST\

This allows a new application version to be installed or extracted into a different directory without losing the existing settings. An installed copy and a portable copy on the same computer use the same settings and the same database.

---

Installing on Linux

Several Linux package formats are available. The appropriate choice depends less on KST4Contest itself than on your distribution and the way you prefer to manage updates.

Installation method	Useful when …
Flatpak	updates should be managed centrally and Flatpak is already in use
AppImage	KST4Contest should run as a portable file without package installation
DEB/RPM	the distribution’s native package manager should be used
Arch package/AUR	Arch Linux, Manjaro or EndeavourOS is being used

Flatpak

For most Linux users, Flatpak is the simplest way to keep KST4Contest installed and manageable through the system’s update tools. The KST4Contest repository is GPG-signed and contains the Stable, Beta and Nightly channels.

Installing Stable from the release file

Download de.x08.KST4Contest.flatpakref from the latest release and open it with the software manager provided by your desktop environment.

Alternatively, install it from a terminal:

flatpak install ./de.x08.KST4Contest.flatpakref

Adding the KST4Contest repository

The repository only needs to be added once:

flatpak remote-add --if-not-exists kst4contest \
https://hamradioonline.github.io/kst4contest/kst4contest.flatpakrepo

You can then install the Stable version:

flatpak install kst4contest de.x08.KST4Contest//stable

Installing Beta

flatpak install kst4contest de.x08.KST4Contest//beta

Installing Nightly

flatpak install kst4contest de.x08.KST4Contest//nightly

All three KST4Contest channels use the same application ID. Installing multiple KST4Contest channels in parallel is therefore not supported.

For example, to switch from Stable to Nightly:

flatpak uninstall de.x08.KST4Contest//stable
flatpak install kst4contest de.x08.KST4Contest//nightly

This does not automatically remove the personal settings stored in ~/.praktiKST.

Installed Flatpak applications can be updated with:

flatpak update de.x08.KST4Contest

Depending on the desktop environment, the graphical software manager may also display or automatically install available Flatpak updates. The flatpak update command itself performs an update; it does not promise to turn up and run by itself one day.

AppImage

The AppImage does not require a conventional installation.

1. Download KST4Contest-v<version>-linux-x86_64.AppImage.
2. Open a terminal in the download directory.
3. Make the file executable:

chmod +x KST4Contest-v<version>-linux-x86_64.AppImage

4. Start KST4Contest:

./KST4Contest-v<version>-linux-x86_64.AppImage

The AppImage can then be moved to another location, such as ~/Applications.

Debian and Ubuntu

Install the DEB package with:

sudo apt install ./KST4Contest-v<version>-debian-amd64.deb

Alternatively, open the file with a graphical package manager.

Beta packages carry a pre-release number behind the version (1.50.0-0.beta.001) that sorts below the stable package (1.50.0-1), so the stable package installs as an upgrade over a beta.

Fedora and compatible RPM systems

Install the RPM package with:

sudo dnf install ./KST4Contest-v<version>-fedora-x86_64.rpm

Beta packages carry a pre-release number behind the version (1.50.0-0.beta.001) that sorts below the stable package (1.50.0-1), so the stable package installs as an upgrade over a beta.

Arch Linux: installing the release package

The Arch package downloaded from the GitHub Release can be installed directly:

sudo pacman -U KST4Contest-v<version>-archlinux-x86_64.pkg.tar.zst

Arch Linux: installing from the AUR

Three variants are available in the AUR:

Package	Content
kst4contest-bin	Pre-built package from the current Stable release
kst4contest	Stable release built locally from source
kst4contest-git	Current development state from the main branch

For most users, kst4contest-bin is the straightforward option:

yay -S kst4contest-bin

To build the Stable release from source:

yay -S kst4contest

To build the current development state:

yay -S kst4contest-git

All three packages provide the same application and are therefore defined as conflicting with one another. Install only one variant at a time.

AUR updates are included when the selected AUR helper checks for package updates, for example:

yay -Syu

They do not happen automatically merely because the package came from the AUR.

---

Installing on macOS

Best-effort support: The macOS packages are built together with the other releases, but they are not tested to the same extent as the Windows and Linux versions. Feedback is welcome; fully tested support for every macOS version and hardware variant cannot currently be guaranteed.

Apple Silicon Macs require the package marked arm64. Intel Macs require the package marked x86_64.

1. Download the appropriate DMG file.
2. Open the DMG file.
3. Drag KST4Contest.app into the Applications folder.
4. Start KST4Contest from the Applications folder or Launchpad.

From version 1.42 onwards the macOS packages are signed with an Apple Developer ID and notarized by Apple. The first launch therefore works by double-clicking, without going through the context menu and without a security prompt. The notarization ticket is stapled into the DMG file itself, so the check also succeeds without an internet connection.

To confirm that a downloaded package really is signed, check it in a terminal:

spctl --assess --type open --context context:primary-signature -v KST4Contest-v<version>-macos-arm64.dmg

The expected result is accepted together with source=Notarized Developer ID.

Versions up to and including 1.41.1

Older packages are not notarized, so macOS blocks the first launch.

If the application came from the official GitHub Release:

1. Open the Applications folder in Finder.
2. Right-click or Control-click KST4Contest.app.
3. Select Open.
4. Confirm the launch in the dialog that appears.

Alternatively, macOS may provide an Open Anyway button under System Settings → Privacy & Security.

---

Where are the settings stored?

KST4Contest stores its settings and other local working files in the user’s home directory. The application directory and the data directory are separate.

Operating system	Data directory	Settings file
Windows	%USERPROFILE%\.praktiKST\	%USERPROFILE%\.praktiKST\preferences.xml
Linux	~/.praktiKST/	~/.praktiKST/preferences.xml
macOS	~/.praktiKST/	~/.praktiKST/preferences.xml

Note the spelling .praktiKST with an uppercase KST. Linux and macOS distinguish between uppercase and lowercase letters. .praktikst would simply be a different directory.

An application update does not remove this directory. Even so, creating a backup before a major version change or extensive configuration work is sensible.

---

Updates

When KST4Contest starts, it checks whether a newer Stable release is available. If it finds one, it displays an information window containing:

• the installed version,
• the latest Stable version,
• a short overview of the main changes,
• the changelog,
• known issues,
• a link to the corresponding GitHub Release page.

The update checker does not install anything. It reports the new version and opens the platform-neutral release page. From there, you must select the appropriate package for Windows, Linux or macOS.

Updating Windows

MSI installer

1. Close KST4Contest.
2. Download the new MSI file and start it.
3. The installer replaces the existing installation; the Start menu entry and the desktop shortcut are kept.
4. Start the new version and check that the existing settings have been loaded.

ZIP package

1. Close KST4Contest.
2. Download the new Windows ZIP package.
3. Extract it into a new or empty directory.
4. Start the new version.
5. Check that the existing settings have been loaded.
6. Remove the old application directory only after that.

In both cases the settings are preserved because they are stored under %USERPROFILE%\.praktiKST, not in the application directory.

Updating an AppImage

1. Download the new AppImage.
2. Make it executable.
3. Start the new file.
4. Remove the previous AppImage only after the new version works.

Updating Debian and Ubuntu

sudo apt install ./KST4Contest-v<version>-debian-amd64.deb

Updating Fedora

sudo dnf upgrade ./KST4Contest-v<version>-fedora-x86_64.rpm

Updating the Arch package

sudo pacman -U KST4Contest-v<version>-archlinux-x86_64.pkg.tar.zst

Updating an AUR package

Update the installed package through the selected AUR helper, for example:

yay -Syu

Updating Flatpak

flatpak update de.x08.KST4Contest

Updating macOS

1. Download the new DMG file for the appropriate architecture.
2. Close KST4Contest.
3. Open the DMG file.
4. Replace KST4Contest.app in the Applications folder.
5. Start the new version and check the existing settings.

The configuration under ~/.praktiKST is not affected.

---

Problems during the first launch

Windows reports an unknown application

KST4Contest is not currently signed with a commercial Windows code-signing certificate. Windows or an additional security product may therefore warn about an unknown or rarely downloaded application.

Check the following first:

• Did the file come from the official KST4Contest release?
• Does the filename match the published release?
• Was the file downloaded completely?
• Does the security product report a specific detection name or only a general reputation warning?

A warning alone is neither reliable proof of malware nor automatically a false positive. If the origin of the file is unclear, do not run it or restore it from quarantine.

Some users have reported quarantine messages from Norton 360 in particular. If the warning can be reproduced, please create a GitHub issue and include:

• the KST4Contest version,
• the complete filename,
• the security product and its version,
• the reported detection name,
• a screenshot of the warning, if possible.

The AppImage does not start

Check the executable permission first:

chmod +x KST4Contest-v<version>-linux-x86_64.AppImage

Then start the file from a terminal. Error messages shown there are usually more useful than a double-click that simply produces no visible result.

macOS blocks the application

From version 1.42 onwards this should no longer happen, because the packages are signed and notarized. If it does occur, the DMG file was most likely downloaded incompletely or modified afterwards; download it again from the official GitHub Release.

On older versions the block is expected. Use the Open function described under Installing on macOS.

The problem remains

First check whether the problem has already been reported under GitHub Issues. If it has not, create a new issue containing:

• the operating system and version,
• the KST4Contest version,
• the installation method,
• the exact error message,
• the steps required to reproduce the problem.

“It does not work” usually describes the situation accurately, but it is of limited value during diagnosis.