Buttons doesn't update itself. It shows a notice when a new version is available, but you download and install the new version yourself.
Each version keeps its configuration in its own database. The first time a new version starts, it has no configuration yet, so it asks you which one to use: a copy of an earlier version's configuration, or an empty one. Importing makes a copy, so the version you upgrade from keeps its own configuration untouched.
Run the new installer over the existing installation.
Warning
Quit Buttons yourself before you run the installer. If it's still running, it gets force-terminated rather than shut down cleanly.
As a safety net, the installer also stops any leftover database or key-value store process still running from a previous install, after you confirm the install and before it copies files. It only stops processes running from the previous or destination install folder, never a separate system-wide PostgreSQL or Garnet.
Run the new .pkg installer. If Buttons is still running, the installer asks you to quit it first. Quit it from the app rather than letting the installer close it.
Start the new version. The watchdog window opens on Configuration Options.
Select a configuration from the list. The newest is at the top, and each entry shows the version it belongs to and the date it was created. In most cases, pick the top entry: the version you were running until now.
Select Import selected configuration.
Importing makes a copy for the new version. The configuration you import from stays as it was, so the earlier version still has its own configuration if you go back to it.
To start from scratch instead, select Start with a new configuration without selecting anything in the list.
Some entries may be greyed out with a red warning icon. Those can't be imported into this version. Hover over the icon to see why:
The configuration is from a newer version of Buttons.
The configuration is from a version before 1.4.
The configuration is from a 1.5 beta version.
The configuration is from a custom build of Buttons.
After you choose, the watchdog shows Migrating configuration with a progress bar while it copies and updates the configuration.
When the migration finishes, the watchdog moves to Starting and brings the services up. Services that depend on others show what they're waiting for, such as "waiting for app-discovery" or "awaiting port 4440 to be open". This is normal and clears on its own.
When every service is ticked, the watchdog shows Running and Launch Editor UI becomes available.
There's no rollback button, but reinstalling an older version isn't blocked. Because each version keeps its own configuration, the older version starts with the configuration it had before you upgraded, as long as it's still on the machine. Anything you changed after upgrading stays with the new version.
Treat this as a side effect of how versions are stored, not a supported rollback. To return to a known-good state on purpose, restore a backup instead.
This version can't find an earlier configuration on this machine. Select Start with a new configuration, then import an exported archive if you have one. See Export or import Buttons configuration.
The configuration you want is greyed out.
Hover over the red icon for the reason. A configuration from a newer version, a version before 1.4, a 1.5 beta or a custom build can't be imported.
Error migrating configuration appears under the list.
Note the message, then collect support information and contact Bitfocus support. The configuration you imported from is unchanged.
You started with a new configuration by mistake.
Configuration Options only appears on a version's first start. Start the earlier version, export its configuration, and import that archive into the new version. See Export or import Buttons configuration.
A service stays on a yellow icon during Starting.
Wait a minute: services wait for the ones they depend on. If one never starts, see Collect support information.
On Linux, watchdog-cli exits right after the first start of a new version.
This is expected. Re-run it with --migrate <number> or --migrate 0, as described above.
On Linux, the new version conflicts with a system-wide PostgreSQL or Valkey.
Buttons runs its own PostgreSQL and Valkey: disable any system-wide services of the same kind, as during the first install.
Buttons was still running when you upgraded on Windows.
Next time, quit it yourself first: the installer force-terminates it rather than shutting it down cleanly.
