# 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.

```sh
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 --features full-embed` 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. When combining with an embedded server, the GUI artifact
must have been built with its `full-embed` feature so it can safely place local
dump files into the bundled server's dump directory:

```sh
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:

```sh
# 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:

```text
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:

```sh
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:

```sh
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.