Skip to content

Updating and Deployment

This guide explains how to move to a new HeelonVault version and, for administrators, how to perform a Linux system-wide install. For a first install on a computer, see QUICKSTART.md.

Enable Profile & Security > Application updates > Check automatically to check the latest stable GitHub release at startup, at most once every 24 hours. No automatic request is made without consent. Check now performs a one-off check even with that option disabled.

The Explore release banner opens official notes and downloads in your browser; Later hides it for the application session. An unavailable connection is never presented as an absence of updates. GitHub receives the IP address but no vault, account or license data. The application neither installs nor verifies packages: the following steps remain necessary.

  1. Make an encrypted .hvb export of your vaults from Profile & Security > Data management, and keep it off the computer.
  2. Note the installed version (header of the changelog) and read the sections of the versions in between, especially “Breaking changes”.
  3. Close HeelonVault.

Database schema changes are applied automatically on the first launch of the new version. They cannot be undone: going back to an older version requires restoring a backup made before the update.

Security dependency updates do not, by themselves, require recreating vaults, changing your master password or replacing your recovery phrase. Check the changelog for any release-specific steps. Install the corrected package on each computer and also restart any standalone PSC callback bridge after updating it: replacing files does not update an already running process.

Download and verify the new package as for a first install (sections 1 and 2 of the quickstart), then:

System Procedure
Windows Run the new .msi. It replaces the installed version; no need to uninstall first. An .msi older than the installed version is refused.
macOS Drag the new application into Applications and choose Replace. Redo the Gatekeeper first-launch step.
Linux (AppImage) Replace the old .AppImage file with the new one, then make it executable (chmod +x).

Replacing the application does not touch your data: it lives in a separate folder (see Where is my data?).

The 2.0.0 AppImage stored its database in a data/ folder relative to the folder it was launched from (often the home folder: ~/data/heelonvault-rust-dev.db). Later versions use ~/.local/share/heelonvault/heelonvault-rust.db. On first launch, if that new file does not exist yet, the AppImage automatically copies the old database found in the launch folder or in the home folder. The old file is left in place: delete it yourself once you have checked your secrets.

For administrators who want an install in /opt/heelonvault with application-menu integration, or a shared database on a server. For a single computer, the AppImage is enough.

The install scripts detect the distribution (Debian/Ubuntu family or Fedora/RHEL/Rocky/AlmaLinux), install the system dependencies and offer two profiles:

Profile Database Logs
Personal (default) ~/.local/share/heelonvault/heelonvault-rust.db ~/.local/state/heelonvault/logs/
Enterprise /var/lib/heelonvault/heelonvault-rust.db /var/log/heelonvault/

The Personal profile shares the AppImage’s database: both can coexist.

Prerequisite: a heelonvault-core checkout at the desired tag and the binary built in release mode, as your user (see the development documentation):

Fenêtre de terminal
cargo build --release -p heelonvault-app
# Preview, without changing anything
sudo env HEELONVAULT_DRY_RUN=1 ./scripts/install.sh
# Install
sudo ./scripts/install.sh

The script picks the most recent binary between target/release/heelonvault and the repository root. If CARGO_TARGET_DIR is set (sudo does not pass it on), point to it: sudo env HEELONVAULT_BINARY="$CARGO_TARGET_DIR/release/heelonvault" ./scripts/install.sh. It refuses a stale binary: version different from the sources, or a source file changed after the build, as after a git pull (HEELONVAULT_ALLOW_STALE_BINARY=1 to override).

It then checks the binary’s integrity when a heelonvault.sha256 file sits next to it, copies the application and its migrations to /opt/heelonvault, and generates the run.sh launcher and the com.heelonvault.rust.desktop menu entry. install-ubuntu.sh and install-rhel.sh force a distribution family.

With the Enterprise profile, the script only sets up the shared paths: network publishing (RDS, VDI, RemoteApp, bastion…) is up to you. Keep the database on low-latency storage, ideally local to the server running the application.

Close HeelonVault, then from the checkout at the new tag:

Fenêtre de terminal
cargo build --release -p heelonvault-app
sudo ./scripts/install.sh

The same command installs or updates. For an update, the script:

  1. shows the installed version and the one replacing it, and offers the current profile (Personal or Enterprise) as the default;
  2. refuses to go on while HeelonVault is open;
  3. installs the system dependencies, then backs up the detected databases to /var/backups/heelonvault (heelonvault_user_<user>_backup_YYYYMMDD_HHMMSS.db or heelonvault_enterprise_backup_YYYYMMDD_HHMMSS.db) with a consistent copy (sqlite3 .backup) whose integrity is checked; an invalid backup stops everything;
  4. prepares the new version next to the old one (/opt/heelonvault.new), then swaps them in a single operation;
  5. on any error after the swap (icons, launcher, validation), automatically restores the previous version.

Up to step 4, a failure leaves the existing installation untouched. The script never modifies the databases: only the application migrates them, on its first launch.

Post-update check:

Fenêtre de terminal
test -x /opt/heelonvault/heelonvault && test -x /opt/heelonvault/run.sh && echo OK
stat -c "%a %n" ~/.local/share/heelonvault/heelonvault-rust.db # expected: 600
Fenêtre de terminal
# 1. Reinstall the previous version (checkout at the previous tag, matching binary)
sudo ./scripts/install.sh
# 2. Restore the backup made before the update
ls -lth /var/backups/heelonvault/
cp /var/backups/heelonvault/<backup>.db ~/.local/share/heelonvault/heelonvault-rust.db
Fenêtre de terminal
sudo ./scripts/remove.sh

Data and backups are only deleted if you explicitly confirm it.

Migrating from the old Python version (0.4)

Section titled “Migrating from the old Python version (0.4)”

HeelonVault never reads or modifies the old Python application’s data. To bring it over, export it to CSV, then import that file from Profile & Security > Data management > Import data (CSV):

Fenêtre de terminal
# Data in the default folder (~/.local/share/passwordmanager), given profile
./scripts/export-legacy-v0.4-to-csv.py --profile <profile> --output legacy_export.csv
# Or explicit paths (shared deployment, for example under /var/lib/heelonvault-shared)
./scripts/export-legacy-v0.4-to-csv.py \
--db-path <path>/passwords_<profile>.db \
--salt-path <path>/salt_<profile>.bin \
--output legacy_export.csv

The CSV file holds your passwords in clear text: delete it securely as soon as the import is done.