Generic, reversible Nextcloud Desktop AppImage workaround with A/B testing, systemd user startup, APT blocking, updates, and native-package rollback

README.md

Nextcloud Desktop on Linux: test and run the official AppImage cleanly

This is a reversible way to:

1. compare a failing native Nextcloud Desktop package with the official AppImage using the same existing configuration;
2. use the AppImage as the normal desktop client without creating a second configuration universe;
3. start it through a systemd user service;
4. prevent an unwanted native package from returning; and
5. switch back after a fixed native package has been verified.

The core procedure is distribution-independent. The package-removal and APT-pinning sections apply only to Debian/Ubuntu-family systems.

Important safety rules

• Back up the client configuration and sync journals first.
• Never run the native client and AppImage client at the same time.
• Do not create <AppImage>.home or <AppImage>.config portable directories.
• Do not pass --confdir when the goal is to reuse the native client's configuration.
• Do not delete ~/.config/Nextcloud, credentials, or ._sync* journal databases to work around a crash.
• Treat configuration files and debug logs as private. They can contain usernames, server URLs, local paths, filenames, and other identifying information.
• Download the AppImage only from an official Nextcloud release location and verify its published checksum.

Without portable directories or an explicit alternate configuration directory, the AppImage uses the normal Nextcloud locations, including:

~/.config/Nextcloud/
~/.local/share/Nextcloud/

Removing an AppImage executable does not remove those normal configuration directories or the locally synchronized data.

1. Back up the existing state

Create a private backup directory:

BACKUP="$HOME/nextcloud-client-backup-$(date +%Y%m%d-%H%M%S)"
install -d -m 0700 "$BACKUP/config" "$BACKUP/local-share"

if test -d "$HOME/.config/Nextcloud"; then
    cp -a "$HOME/.config/Nextcloud" "$BACKUP/config/"
fi

if test -d "$HOME/.local/share/Nextcloud"; then
    cp -a "$HOME/.local/share/Nextcloud" "$BACKUP/local-share/"
fi

Each configured sync root normally contains hidden ._sync* journal files. Record the sync-root paths from the client and back up those files separately while the client is stopped. Do not publish these databases.

Desktop credentials are commonly held in the desktop keyring rather than the configuration directory. Do not clear or replace the keyring during this procedure.

2. Prepare and verify the official AppImage

Download the desired official release, then point a shell variable at it:

APPIMAGE="$HOME/Downloads/Nextcloud-<VERSION>-x86_64.AppImage"
APPIMAGE_NAME=${APPIMAGE##*/}
chmod 0755 "$APPIMAGE"
sha256sum "$APPIMAGE"

Compare that digest with the checksum published by Nextcloud. Do not continue if it differs.

Confirm that portable-mode companions do not exist:

test ! -e "${APPIMAGE}.home"
test ! -e "${APPIMAGE}.config"

3. Stop the native client

The native package may have installed a user service. Stop it if present:

systemctl --user stop com.nextcloud.desktopclient.nextcloud.service 2>/dev/null || true
pgrep -af nextcloud

If pgrep still shows a native Nextcloud process, close it normally before continuing. Re-run pgrep and make sure no client remains.

Also inspect ~/.config/autostart/ for a Nextcloud desktop entry. Archive or disable it before making systemd the sole startup mechanism.

4. Run a controlled A/B test

Start the AppImage directly in a terminal with debug logging:

"$APPIMAGE" --logdebug --logfile -

Use the existing account and sync folders. Observe the same operation that caused the native package to fail, and continue through at least one completed synchronization of every configured folder.

A useful A/B report records:

• native package version and origin;
• AppImage version and checksum;
• operating system and desktop session type;
• Qt and OpenSSL versions reported by each build;
• whether both used the same normal configuration;
• the exact operation immediately before failure;
• signal, exception, and restart-loop evidence; and
• whether the AppImage completed repeated discovery/sync cycles.

Redact account names, server URLs, local paths, filenames, tokens, cookies, and credentials before publishing evidence.

If both builds fail identically, investigate upstream client behavior, account state, server responses, or sync data. If the same-version official AppImage succeeds while the native package fails, the native build, compatibility patches, or system-library combination becomes the leading suspect.

5. Install the AppImage in a stable user-local location

After the controlled test succeeds, stop the test instance and install it under a versioned filename:

install -d -m 0755 "$HOME/.local/opt/nextcloud"
install -m 0755 "$APPIMAGE" "$HOME/.local/opt/nextcloud/$APPIMAGE_NAME"
ln -sfn "$APPIMAGE_NAME" "$HOME/.local/opt/nextcloud/current"
readlink -f "$HOME/.local/opt/nextcloud/current"

The resulting layout is:

~/.local/opt/nextcloud/
├── Nextcloud-<VERSION>-x86_64.AppImage
└── current -> Nextcloud-<VERSION>-x86_64.AppImage

6. Install and enable the systemd user service

Install the accompanying nextcloud-appimage.service file:

install -Dm0644 nextcloud-appimage.service \
    "$HOME/.config/systemd/user/nextcloud-appimage.service"

systemctl --user daemon-reload
systemctl --user enable --now nextcloud-appimage.service
systemctl --user status nextcloud-appimage.service

Inspect logs with:

journalctl --user -u nextcloud-appimage.service --since today

This unit is attached to graphical-session.target. Check that the desktop activates that target:

systemctl --user is-active graphical-session.target

If the target is not active on a particular desktop, adapt the installation target to that desktop rather than adding a second simultaneous autostart mechanism.

Do not add RestrictRealtime=true without testing it. Some systemd versions enforce it in a way that prevents the AppImage FUSE runtime from mounting, causing exit status 127.

7. Add an application-menu entry

Install the accompanying desktop file:

install -Dm0644 nextcloud-appimage.desktop \
    "$HOME/.local/share/applications/nextcloud-appimage.desktop"

update-desktop-database "$HOME/.local/share/applications" 2>/dev/null || true

The template uses the icon name nextcloud-appimage. You may install a suitable Nextcloud icon as:

~/.local/share/icons/hicolor/512x512/apps/nextcloud-appimage.png

If no icon is installed, change the desktop file's Icon= value to an icon available in the current desktop theme. The launcher still works without a custom icon.

Do not add a separate ~/.config/autostart/ entry when the systemd user service is enabled.

8. Optionally remove and block the native Debian packages

First inspect the installed package names and simulate the removal. Package names can change between releases:

dpkg-query -W 'nextcloud*' 'libnextcloudsync*' 2>/dev/null

sudo apt-get -s remove \
    nextcloud-desktop \
    nextcloud-desktop-common \
    nextcloud-desktop-l10n \
    libnextcloudsync0

Read the simulation carefully. File-manager integration packages may also depend on the client. If the proposed transaction is acceptable, repeat without -s. Do not use purge, and do not run autoremove, because the objective is to preserve configuration and make rollback easy.

Disable the repository or PPA that supplied the failing package using the distribution's normal software-source tools. Do not disable an unrelated source.

For an additional temporary block, install the accompanying APT preference:

sudo install -m 0644 nextcloud-desktop-block.pref \
    /etc/apt/preferences.d/nextcloud-desktop-block.pref

sudo apt-get update
apt-cache policy \
    nextcloud-desktop \
    nextcloud-desktop-common \
    nextcloud-desktop-l10n \
    libnextcloudsync0

With the preference active, those packages should have no installable candidate. Adjust the package list if the distribution uses different names.

9. Update the AppImage

AppImage updates are normally manual:

1. Download the new official AppImage.
2. Verify its checksum.
3. Back up the current client state.
4. Install it beside the previous version.
5. Stop the service.
6. Point current at the new filename.
7. Start the service and verify every sync folder.
8. Retain the previous AppImage until the new one has completed several successful cycles.

Example:

NEW_IMAGE="$HOME/Downloads/Nextcloud-<NEW-VERSION>-x86_64.AppImage"
NEW_NAME=${NEW_IMAGE##*/}

sha256sum "$NEW_IMAGE"
install -m 0755 "$NEW_IMAGE" "$HOME/.local/opt/nextcloud/$NEW_NAME"

systemctl --user stop nextcloud-appimage.service
ln -sfn "$NEW_NAME" "$HOME/.local/opt/nextcloud/current"
systemctl --user start nextcloud-appimage.service
systemctl --user status nextcloud-appimage.service

To roll back, stop the service, repoint current to the previous verified filename, and start the service again.

10. Return to a fixed native package

Do not switch merely because a newer package exists. First identify the relevant bug report or fix and test the candidate package against the preserved configuration.

A controlled return looks like this:

1. Keep the working AppImage available for rollback.
2. Stop the AppImage service.
3. Remove the APT preference and re-enable the appropriate package source.
4. Update package metadata and simulate the native installation.
5. Install the complete version-matched native package set.
6. Ensure no AppImage process is running.
7. Run the native client manually with debug output through discovery and synchronization.
8. Restore native autostart only after the candidate succeeds repeatedly.
9. If it fails, stop/remove the candidate, restore the block, and restart the verified AppImage.

After the native client is accepted:

systemctl --user disable --now nextcloud-appimage.service

Archive rather than immediately delete the previous AppImage and backup. Remove the AppImage menu entry only after the native setup is confirmed stable.

Why this avoids configuration sprawl

The AppImage executable is stored under ~/.local/opt, but it deliberately continues using the normal Nextcloud configuration and data locations. There is only one client configuration, not a native configuration plus a portable/container configuration. Replacing or deleting the AppImage executable therefore does not implicitly delete the normal user configuration.

nextcloud-appimage.desktop

[Desktop Entry]
Type=Application
Name=Nextcloud
GenericName=File Synchronizer
Comment=Nextcloud desktop synchronization client
Exec=systemctl --user start nextcloud-appimage.service
Icon=nextcloud-appimage
Terminal=false
Categories=Network;FileTransfer;
StartupNotify=false

nextcloud-appimage.service

[Unit]
Description=Nextcloud Desktop AppImage
Wants=network-online.target
After=graphical-session.target network-online.target
PartOf=graphical-session.target
StartLimitIntervalSec=5min
StartLimitBurst=3

[Service]
Type=exec
ExitType=cgroup
ExecStart=%h/.local/opt/nextcloud/current --background
Restart=on-failure
RestartSec=10s
Slice=app.slice

[Install]
WantedBy=graphical-session.target

nextcloud-desktop-block.pref

# Temporary block while a verified AppImage is active
Package: nextcloud-desktop nextcloud-desktop-common nextcloud-desktop-l10n libnextcloudsync0
Pin: version *
Pin-Priority: -1

Thank you, this is very helpful.