migration and updates

upgrading kftray versions typically goes smoothly due to backward-compatible configuration storage, but understanding the process helps avoid problems with running port forwards and shared state between interfaces.

when migration considerations matter

migration becomes important when someone has running port forwards during upgrade time, works with both interfaces simultaneously, or needs to preserve configuration across system changes. simple installations with no active forwards usually upgrade without special procedures.

teams with established configurations benefit from documented upgrade procedures, especially when multiple developers coordinate shared configurations or github sync setups.

understanding the upgrade impact

the key consideration during upgrades is the relationship between interface processes and shared configuration. both interfaces read from the same SQLite database in ~/.kftray/, but each manages its own port forward processes independently.

this means someone can upgrade the desktop interface while keeping terminal interface port forwards running, or vice versa. the database remains compatible across versions, preserving configurations and state information.

however, port forwards started by the interface being upgraded need to be stopped first, since the upgrade process terminates the application and its associated forwarding processes.

desktop interface upgrade process

upgrading the desktop interface follows standard application update patterns for each platform. on macOS with homebrew:

brew upgrade --cask kftray

on linux systems using homebrew:

brew upgrade kftray-linux

the upgrade process handles application replacement automatically. if port forwards are running through the desktop interface, they'll stop during the upgrade and need manual restart afterward.

backup the configuration database before major version upgrades:

cp ~/.kftray/kftray.db ~/kftray-backup-$(date +%Y%m%d).db

this provides recovery options if something goes wrong during the upgrade process.

terminal interface upgrade process

the terminal interface uses installer scripts that download and replace the binary:

bash <(curl -s https://raw.githubusercontent.com/hcavarsan/kftray/main/hacks/kftui_installer.sh)

this approach works for initial installation and upgrades. the installer detects existing installations and replaces the binary while preserving configuration data.

stop any running kftui instances before upgrading to ensure clean process replacement. active port forwards managed by kftui will stop during the upgrade.

migration workflow for active environments

coordinated upgrade approach

teams with active development environments often coordinate upgrades to minimize disruption. a typical approach involves:

document currently running forwards and their managing interfaces. stop forwards that will be affected by the upgrade, or plan for brief downtime. upgrade during low-activity periods when port forward interruption has minimal impact.

restart forwards after verifying the upgrade succeeded and applications start correctly.

rolling upgrade strategy

someone using both interfaces can upgrade one while keeping the other operational. upgrade the less critical interface first, verify it works correctly, then upgrade the second interface.

this approach maintains some port forwarding capability throughout the upgrade process, useful when complete downtime isn't acceptable.

version compatibility and feature availability

different versions support different feature sets, which affects upgrade planning. major features like http logging and github sync were added in specific versions, so upgrades may enable new functionality.

current feature requirements:

• HTTP logging requires desktop interface v0.11.7+
• GitHub sync requires desktop interface v0.10.0+
• UDP forwarding works across all recent versions
• Configuration sharing works across all versions

check release notes for version-specific changes and new feature availability. teams may want to coordinate upgrades to take advantage of new collaboration features.

configuration migration and backup strategies

database portability

the SQLite configuration database transfers easily between systems and versions. copy ~/.kftray/kftray.db to preserve configurations when moving to new machines or creating backup installations.

configuration export through the desktop interface provides cross-platform sharing options. JSON exports work independently of database versions and provide readable backup formats.

github sync migration

teams using github sync need to ensure repository access continues working after upgrades. personal access tokens and repository URLs remain valid across versions, but new features may require updated permissions.

verify github sync functionality after upgrades, especially when new collaboration features become available.

troubleshooting upgrade issues

version compatibility problems

when upgrades cause problems, check version compatibility between interfaces. mixing very old and very new versions may cause database compatibility issues or feature conflicts.

verify both interfaces show the same version expectations and feature availability. update both interfaces to similar version ranges when compatibility problems occur.

process cleanup after failed upgrades

incomplete upgrades sometimes leave stuck processes or corrupted state. identify and clean up problematic processes:

ps aux | grep kftray
ps aux | grep kftui

kill stuck processes if necessary, then restart cleanly. the configuration database usually survives process problems without corruption.

configuration recovery procedures

when configuration gets corrupted or lost during upgrades, restore from backups:

1. stop all interfaces
2. restore database backup: cp ~/kftray-backup.db ~/.kftray/kftray.db
3. restart interfaces and verify configuration

alternatively, reimport configurations from JSON exports or github repositories if database recovery isn't possible.

post-upgrade verification and testing

functionality verification

after upgrades, verify core functionality works correctly. test port forward creation, starting/stopping forwards, and interface coordination. check that both interfaces show consistent configuration and state information.

verify new features work as expected, especially if the upgrade enabled previously unavailable functionality like http logging or github sync.

performance and stability testing

run typical development workflows to ensure upgrade didn't introduce performance regressions or stability issues. monitor resource usage and connection reliability during normal usage.

test interface switching and process management to ensure the shared state model continues working correctly after the upgrade.

planning upgrades for teams

coordination and communication

teams benefit from coordinated upgrade schedules that minimize disruption to shared development environments. communicate upgrade timing and coordinate github sync repository changes if needed.

document any configuration changes or new features that become available, and update team procedures accordingly.

rollback planning

plan rollback procedures in case upgrades cause problems. maintain backup installations or previous versions until upgrades prove stable. document downgrade procedures for critical environments.

consider testing upgrades in non-critical environments before upgrading primary development systems.

this upgrade approach balances safety with the benefits of staying current with improvements and bug fixes in newer versions.