Skip to content

Install

Mel edited this page Nov 10, 2026 · 1 revision

Two install methods: AppImage (works today) and Flatpak (draft). All installs are user-local; nothing here needs root.

Prerequisites

The app shells out to node for every stack operation, so Node.js 22+ must be on PATH — no install method bundles it. If it is missing, first launch tells you exactly that. Get it from nodejs.org or a version manager; distro packages often lag.

Running the AppImage also needs FUSE 2 and the WebKitGTK 4.1 runtime (the AppImage does not bundle the webview):

Distro FUSE 2 WebKitGTK 4.1 runtime
Debian/Ubuntu sudo apt install libfuse2 sudo apt install libwebkit2gtk-4.1-0
Fedora sudo dnf install fuse-libs sudo dnf install webkit2gtk4.1
Arch sudo pacman -S fuse2 sudo pacman -S webkit2gtk-4.1

Without FUSE 2, launching fails with a mount error; without the webview libs it fails with a missing libwebkit2gtk-4.1.so error.

AppImage

Build it (bundle lands at src-tauri/target/release/bundle/appimage/Stack_<version>_amd64.AppImage):

npm ci
npx tauri build --bundles appimage

Or download the AppImage from the release page. Then install from a stack-app checkout:

scripts/install-appimage.sh <Stack_x.y.z_amd64.AppImage> --icons src-tauri/icons

Without --icons, the installer extracts the single icon embedded in the AppImage instead (slower, 512px only). What it does:

  • copies the AppImage to ~/.local/bin/stack-app.AppImage
  • writes ~/.local/share/applications/stack-app.desktop plus hicolor icons (id stack-app)
  • runs scripts/provision-stack.sh (skip with --no-provision, or point at an existing checkout with --stack <dir>)
  • symlinks the checkout's bin/stack to ~/.local/bin/stack, so the stack terminal command is on PATH (skipped with a warning when something else already owns that name; removed on uninstall only if it still points at a stack checkout)
  • refreshes the desktop and icon caches

Options: --prefix <dir> (default ~/.local), --reinstall.

No checkout? The AppImage also runs standalone — chmod +x it and launch directly — but then there is no menu entry and no auto-provisioning; the app's first-run picker covers the stack path.

Upgrade: re-run the installer with the new AppImage plus --reinstall (or accept the in-app update when offered — that upgrades in place). Your stack path and settings survive.

Uninstall:

scripts/uninstall-stack-app.sh            # keeps app config
scripts/uninstall-stack-app.sh --config   # also forgets stack path, recents

Never touches the stack checkout or your projects.

Flatpak

Draft only. The manifest, desktop file, and CI sketch exist, but the generated npm/cargo vendor sources are not committed and no build has been validated — see https://github.com/escacs/stack-app/blob/main/flatpak/README.md for status and how to finish it. Provisioning inside the sandbox story: run scripts/provision-stack.sh on the host first; the sandbox cannot authenticate to GitHub for you.

System packages (.deb/.rpm)

Tauri also builds deb and rpm targets. When attached to a release they install system-wide (sudo apt/dnf install ./stack_x.y.z_arch.ext) with the desktop entry included; afterwards provision the stack checkout with scripts/provision-stack.sh from a checkout (or pick the folder in the app on first run).

Stack auto-provisioning

scripts/provision-stack.sh runs at the end of every installer. In order:

  1. Already have one? If ~/escacs/stack, $ESCACS_STACK, or the already-pinned app setting is a usable checkout (git HEAD plus tools/stack/cli.mjs), it is kept and pinned in the app settings.
  2. gh clone — when gh is installed and authenticated, clones escacs/stack to ~/escacs/stack and pins it.
  3. ssh clone — batch-mode git clone (fails fast, never prompts).
  4. Folder picker — otherwise first launch shows the setup screen: authenticate (gh auth login) and re-run the script, or clone manually and pick the folder.

The pin is written to ~/.config/codes.escacs.stack/config.json as stackPath (the settings override wins in the app's resolve order), which is why GUI launches find it without shell env vars. $ESCACS_STACK is still honoured when set. The script never sees credentials — auth stays inside gh/ssh. Re-run it any time; it never overwrites an existing checkout.

The stack repo is private, so provisioning uses your existing GitHub auth (gh or ssh) and falls back to the app's first-run folder picker when there is none.

See also: First Run, Troubleshooting, Portability.

Clone this wiki locally