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.
Before any update
Section titled “Before any update”Get notified about a new release
Section titled “Get notified about a new release”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.
Prepare the installation
Section titled “Prepare the installation”- Make an encrypted
.hvbexport of your vaults from Profile & Security > Data management, and keep it off the computer. - Note the installed version (header of the changelog) and read the sections of the versions in between, especially “Breaking changes”.
- 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.
Updating a computer
Section titled “Updating a computer”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?).
AppImage: data created with version 2.0.0
Section titled “AppImage: data created with version 2.0.0”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.
Linux system install
Section titled “Linux system install”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.
Install
Section titled “Install”Prerequisite: a heelonvault-core checkout at the desired tag and the binary built in release
mode, as your user (see the development documentation):
cargo build --release -p heelonvault-app
# Preview, without changing anythingsudo env HEELONVAULT_DRY_RUN=1 ./scripts/install.sh
# Installsudo ./scripts/install.shThe 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.
Update
Section titled “Update”Close HeelonVault, then from the checkout at the new tag:
cargo build --release -p heelonvault-appsudo ./scripts/install.shThe same command installs or updates. For an update, the script:
- shows the installed version and the one replacing it, and offers the current profile (Personal or Enterprise) as the default;
- refuses to go on while HeelonVault is open;
- installs the system dependencies, then backs up the detected databases to
/var/backups/heelonvault(heelonvault_user_<user>_backup_YYYYMMDD_HHMMSS.dborheelonvault_enterprise_backup_YYYYMMDD_HHMMSS.db) with a consistent copy (sqlite3 .backup) whose integrity is checked; an invalid backup stops everything; - prepares the new version next to the old one (
/opt/heelonvault.new), then swaps them in a single operation; - 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:
test -x /opt/heelonvault/heelonvault && test -x /opt/heelonvault/run.sh && echo OKstat -c "%a %n" ~/.local/share/heelonvault/heelonvault-rust.db # expected: 600Roll back
Section titled “Roll back”# 1. Reinstall the previous version (checkout at the previous tag, matching binary)sudo ./scripts/install.sh
# 2. Restore the backup made before the updatels -lth /var/backups/heelonvault/cp /var/backups/heelonvault/<backup>.db ~/.local/share/heelonvault/heelonvault-rust.dbUninstall
Section titled “Uninstall”sudo ./scripts/remove.shData 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):
# 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.csvThe CSV file holds your passwords in clear text: delete it securely as soon as the import is done.
