komp_ac/packaging/appimage/README.md

Combined Linux AppImage

This packaging layer keeps server and client-gui2 independently buildable and combines their release artifacts into one x86_64 Linux AppImage. The AppImage entry point starts the selected server build, waits for its local gRPC port, runs the GUI, and terminates the server when the GUI exits.

With the full-embed server feature, the PostgreSQL installation, database, dumps, JWT secret and server log are persistent and are not stored in the read-only AppImage. By default they live under ${XDG_DATA_HOME:-$HOME/.local/share}/komp_ac. Set KOMP_AC_DATA_DIR to override that root. A full build instead uses the external PostgreSQL settings supplied through RUST_DB_* environment variables. Both modes create fresh runtime Tantivy indexes under the application-data root; existing repository indexes are never packaged.

Build both and combine

The frontend dependencies must already be present in client-gui2/node_modules. The build also requires Nix and Tauri's Linux build dependencies. It uses appimagetool from APPIMAGETOOL or PATH when available, otherwise it reuses Tauri's cached linuxdeploy-plugin-appimage.AppImage. It does not fetch or install frontend dependencies.

packaging/appimage/build.sh ./KompAC.AppImage

This performs the existing builds independently:

1. nix build '.?submodules=1#portable-server'
2. yarn tauri build --bundles appimage in client-gui2
3. assemble.sh to add the portable server and supervisor to the GUI AppImage

The standalone server and GUI build processes remain available unchanged.

Combine existing artifacts

Already-built artifacts can be combined without rebuilding either application. The first argument may be either a completed GUI AppImage or Tauri's completed .AppDir directory:

packaging/appimage/assemble.sh \
    client-gui2/src-tauri/target/release/bundle/appimage/komp_ac.AppDir \
    result/bin/server \
    embedded \
    ./KompAC.AppImage

The generated AppImage uses local embedded mode and binds gRPC only to 127.0.0.1:50051. Only one combined AppImage instance may run against a data directory at a time.

Debian production build from NixOS

build-debian.sh uses rootless Podman to build inside a Debian 12 userspace. The host source is mounted read-only and copied into the temporary container. Cargo and Yarn caches use named Podman volumes, so neither Cargo target files nor frontend dependencies are written into the repository. The source snapshot excludes build outputs, local environment files and generated runtime data such as Tantivy indexes, dumps and embedded PostgreSQL data. It also omits profiling captures, benchmark and mutation reports, old AppImages, frontend caches, logs, and local editor or agent state. Cargo configuration, SQLx offline metadata, migrations and all crate/frontend source inputs remain in the snapshot. The container validates the completed snapshot and stops before compilation if a known runtime, cache or private-data path survived the exclusions. Top-level copying is allowlisted to workspace manifests, required crates, client-gui2 and the packaging layer, so unrelated future repository directories are omitted by default.

The server feature is a required argument. Nothing implicitly chooses the database implementation:

# One-click application with PostgreSQL embedded in the server binary
packaging/appimage/build-debian.sh full-embed

# GUI and server using a separately managed PostgreSQL instance
packaging/appimage/build-debian.sh full

The default embedded outputs are:

debian-dist/KompAC-embedded-debian12-amd64.AppImage
debian-dist/bin/client-gui2
debian-dist/bin/server

full-embed runs cargo build --release --package server --features full-embed; PostgreSQL 17.10.0 is embedded by postgresql_embedded. full runs the same command with --features full and configures the AppImage launcher for external database mode. OpenSSL is linked statically in both builds. The GUI is built by Tauri inside Debian with its normal AppImage dependency collection.

An alternative output directory and filename may be supplied:

packaging/appimage/build-debian.sh \
    full-embed \
    /path/to/releases \
    KompAC-0.8.48-debian12-amd64.AppImage

An external build needs its database connection when launched:

RUST_DB_USER=komp_ac \
RUST_DB_PASSWORD=secret \
RUST_DB_HOST=127.0.0.1 \
RUST_DB_PORT=5432 \
RUST_DB_NAME=komp_ac \
./debian-dist/KompAC-external-debian12-amd64.AppImage

The build requires network access for the Debian builder image, APT packages, Rust crates, frontend packages, PostgreSQL's embedded archive and Tauri's AppImage tooling. The named cache volumes are retained for later production builds. They can be inspected with podman volume ls.

On NixOS, the host script uses /etc/containers/containers.conf when Podman's vendor configuration below /usr/share is not readable. An explicitly supplied CONTAINERS_CONF is always preserved. If /usr/share/containers/seccomp.json is also unreadable, the script visibly passes --security-opt seccomp=unconfined to the rootless build containers. Restore normal host permissions with sudo chmod 755 /usr/share to retain seccomp isolation. The same fallback disables automatic OCI hook discovery when its vendor directory is unreadable; explicitly configured hook overrides are never replaced.