UpgradingCopy Anchor Link

Most upgrades only need the new image or a rebuild. The versions below also need a change on the operator's side, taken from the Upgrading section of each release in the changelog. When skipping versions, apply every section between the old version and the new one, oldest first.

Back up server.data_path, /var/lib/headplane by default, before upgrading. It holds Northplane's database.

To get patch releases without moving to a new minor version by surprise, pin the Docker image to a minor tag, such as ghcr.io/tale/headplane:0.8.

0.9.0Copy Anchor Link

• DNS records are only read from and written to the file in Headscale's dns.extra_records_path. Records listed inline under dns.extra_records show as read-only, so move them into the file to keep editing them.
• The proc and kubernetes integrations now restart Headscale instead of reloading it, so Headscale needs a supervisor that brings it back: systemd with Restart=always, which Headscale's own unit and the NixOS module already set, or the kubelet.
• Enabling more than one integration now turns them all off, with an error in the log. Keep one.
• After signing in with single sign-on, only owners, admins and IT admins can pick which Headscale user their account links to. Everyone else links automatically or is linked from the Users page.
• Builds no longer read __INTERNAL_PREFIX. If a build used it to serve Headplane somewhere other than /admin, set server.base_path to that path instead.

0.8.1Copy Anchor Link

• Single sign-on stays off until server.base_url is set to Headplane's public URL.
• Proxy rules that rewrite the Origin header, added as a workaround for 0.8.0, can be removed.

0.8.0Copy Anchor Link

• Building from source needs Go 1.27.1 or newer.

0.7.0Copy Anchor Link

• Headplane needs Headscale 0.27.0 or newer.
• The agent needs Headscale 0.28 and headscale.api_key, and creates its own pre-auth key. Remove integration.agent.pre_authkey and integration.agent.cache_path.
• oidc.headscale_api_key is now headscale.api_key. The old option still works, but is deprecated.
• Logs are JSON, one object per line. Update anything that parses them.
• Accounts are linked to Headscale users. Single sign-on accounts link by subject or email when they sign in. Accounts that don't match need linking by hand before they can create their own auth keys or use Browser SSH.

0.6.2Copy Anchor Link

• oidc.redirect_uri is replaced by server.base_url. Headplane logs the value to use when it finds the old option.
• PKCE is opt-in. If the identity provider requires it, set oidc.use_pkce: true.
• Environment variables are always read, so remove HEADPLANE_LOAD_ENV_OVERRIDES. .env files are no longer loaded.
• Remove oidc.strict_validation. It has no effect.

0.6.1Copy Anchor Link

• Headplane keeps a database, hp_persist.db, in server.data_path. The directory has to be persistent and writable, such as a Docker volume. Existing users migrate on their own.
• The Docker image has no shell. For debugging, use the matching -shell tag, such as ghcr.io/tale/headplane:0.6.1-shell.

0.6.0Copy Anchor Link

• Headplane needs Headscale 0.26.0 or newer.

0.5.6Copy Anchor Link

• Single sign-on accounts get roles. New accounts start as members with no dashboard access, and the first person to sign in becomes the owner, so sign in right after upgrading to claim the owner account.

0.5Copy Anchor Link

• Settings moved from environment variables to a config file. Start from config.example.yaml. Settings that used to be shared with Headscale, such as public_url and oidc, are now separate.