Upgrading¶

Updating a deployment¶

Pick the release that matches your registry's major and minor version (see Compatibility). When you upgrade the registry to a new minor version, upgrade the app with it. 1.0.0-rc2 is an exception: it doesn't work with cloud-registry 1.0.0rc1 (see below).
Read its release notes on GitHub, and the changes below, for settings to add or change.
Verify the image, update the settings if needed, and replace the container with one of the new image.

The app keeps no data of its own: everything is stored in the registry, so the app can be replaced at any time, except when you upgrade to or from 1.0.0-rc2 (see below). Users who are logged in keep their session (it is kept in cookies), unless the release notes say otherwise: the upgrade to 1.0.0-rc2 logs them out, and they log in once more. Logins that are in progress during the update may fail; users then log in again.

1.0.0-rc2¶

Upgrade the registry together with the app: this version needs cloud-registry 1.0.0rc2, and has no fallback for older ones. The registry moved the paths of users' roles to /services/{serviceId}/permissions/users/{userId}, and the app calls only these. Don't run this version with cloud-registry 1.0.0rc1: the registry answers 200 OK, but grants the role to a user users/bob instead of bob (0.6.0 takes these paths the same way, and earlier versions don't find them). Earlier versions of the app can't change roles of users with the new registry, which no longer finds the old paths; if user IDs start with users/, they even change the roles of another user, so stop them first.

In short, to upgrade from 1.0.0-rc1:

Before the upgrade, check the login settings (see Login below): the issuer of every provider in LOGIN_PROVIDERS and LOGIN_REDIRECT_URI are https URLs (http only for localhost, *.localhost and loopback addresses), and the app's login page (/auth/login at the origin of LOGIN_REDIRECT_URI) is registered as a post-logout redirect URI with each provider that has an end_session_endpoint.
Stop the app, or scale it to 0 replicas, and upgrade the registry to cloud-registry 1.0.0rc2 with a fresh database, as the registry's upgrade guide describes.
Start the app with the image elixircloud/cloud-registry-ui:1.0.0-rc2 (see Verifying images); users who were logged in log in once more. No setting must change. Two are new (see Access dialog): NEXT_PUBLIC_ACCESS_PAGE_SIZE (now 5 entries per page instead of 8) and NEXT_PUBLIC_INVITATION_LABEL_REQUIRED (invitations now need a label; set it to false to keep labels optional).

The rest of this section explains why and what changes.

So no order of apps and registry pods is safe during a rolling update. Follow the registry's upgrade guide: scale the registry to 0 replicas for the upgrade, unless nobody changes roles during it. After a rolling update, look for wrongly granted roles as the guide describes.

If the app ran with an older registry, it can't repair the result: it reports an error for such a grant, but the wrong role stays stored, and a downgrade leaves the real user's role as it was. With that registry, Remove fails, as the app can't read the IDs of those who hold roles, so check all role changes made in that time. Upgrade the registry, then remove the wrong roles as the guide describes. To go back from this version, move the registry and the app back together, as the guide describes under Going back.

The app refuses user IDs and groups that start with /, as their paths would be those of another user or group. Roles of such IDs, which should be rare, can no longer be changed in the app, which says so when you try.

The Manage access dialog now has the tabs Current Access and Invitations, and shows 5 entries per page instead of 8. To change that, set NEXT_PUBLIC_ACCESS_PAGE_SIZE (see Access dialog); there is nothing else to change. It no longer lists accepted invitations, as the person is listed with their role.

Invitations now have labels, which say who they are for, and the form requires one by default. To keep it optional, set NEXT_PUBLIC_INVITATION_LABEL_REQUIRED=false (see Access dialog). Expired invitations stay listed, marked as expired, with New link, removal and Remove expired. Both need cloud-registry 1.0.0rc2. If the app meets 1.0.0rc1 during an upgrade, it creates links without the label and says so, and doesn't list expired invitations, as that registry doesn't; this is no reason to run that pairing, which gives roles to the wrong user, as described above.

Names of the registry's API: cloud-registry 1.0.0rc2 moves the fields and query parameters it adds to camelCase (e.g. userId, registrationRules, createdAt), without aliases, and needs a fresh database, and the app only follows the new names (see Compatibility and the registry's upgrade guide). There is nothing to change in the app's settings.

Removing a user's role now also deletes the invitations to the service that they created and nobody accepted, as the registry does this. The Invitations tab follows at once (see Managing access).

Import and sync of service info: the registration form can import a service's public service info, and keep the new entry in sync with it (see Importing from service info). This takes no settings in the app; the registry's settings say whether it syncs and how often. With a registry older than 1.0.0rc2, the form has neither, and there are no labels.

Synced services have the labels Synced and Out of sync and, for those with a role, controls on their page (see Syncing services). An out-of-sync label without a reason means that the registry's syncs aren't running: check the registry.

Notifications: logged-in users have a bell in the top bar, with what needs their attention (see Notifications). This takes no settings; a registry without notifications, or one that refuses them (403), shows no bell.

No bell or sync labels, or a refused import, with cloud-registry 1.0.0rc2: if the registry runs with its own access policy (e.g. in a config overlay), the policy probably lacks the rules that 1.0.0rc2 added for these endpoints (/notifications, the syncs of services, /services/import). The registry then refuses them: the app shows no bell (and logs a warning in the browser's console) and no sync labels, and the import fails with an error. Update the policy as the registry's upgrade guide describes.

Login: the login is hardened (see Login). Check these points before the upgrade:

https for login providers: the issuer in LOGIN_PROVIDERS must be an https URL (http only for localhost, *.localhost and loopback addresses); the app refuses to start with others. Logins fail with providers whose discovery document lists http endpoints.
Token requests: the app now sends the client ID and secret in the body (client_secret_post) only to providers that list this method in token_endpoint_auth_methods_supported, and uses HTTP Basic authentication (client_secret_basic) otherwise. Providers that list no methods and refuse Basic authentication don't follow OpenID Connect, which takes Basic authentication as the default: logins with them fail with invalid_client in the app's log.
Logout at the provider: for providers with an end_session_endpoint, logging out now ends the session at the provider too. Register the app's login page (/auth/login at the origin of LOGIN_REDIRECT_URI) as a post-logout redirect URI with each such provider before the upgrade (see Sessions and logout); otherwise, the provider may show an error after logging out.
Cookie names: the session's cookies now have the prefix __Host- (e.g. __Host-access_token), which only the app's own origin can set, and the app reads only these names. Users who are logged in when you upgrade are logged out and log in once more (sessions of 1.0.0-rc1 last at most 12 hours anyway), and so are those of earlier versions. The next login deletes the cookies of the old names (access_token, id_token, login_provider); otherwise, they expire unread. A login in progress during the upgrade fails, and the user logs in again. During a rolling update, instances of the earlier version don't read the new names: users who log in on a new instance seem logged out on an old one until the update is complete. Serve the app on a domain of its own (see Sessions and logout).
https for the redirect URI: LOGIN_REDIRECT_URI must be an https URL too (http only for localhost, *.localhost and loopback addresses), as the provider sends the authorization code there; the app refuses to start with others.

Listing the registry itself: in admin mode, the service info page can list the registry among its own services (see Listing the registry itself). With a registry older than 1.0.0rc2 (e.g. an earlier development version), the page says that it can't tell whether the registry is listed; the rest of the app works.

1.0.0-rc1¶

Upgrade the registry to cloud-registry 1.0.0rc1 together with the app (see Compatibility). It brings two features that the app uses once the registry has them, without any setting to change in the app:

Invitations: owners invite users to services by link (see Inviting by link and Accepting an invitation). Their expiry and limits, and what the registry shows of those who accepted, are the registry's settings.
Limit of services per user: the registry's setting custom.access_control.max_services_per_user (50 by default; 0 allows only admins to register services) is published in its service info, and the app reports it when a registration is refused (see Limit on registered services). Check that the default suits your users before the upgrade.

With registries older than 1.0.0rc1, the app keeps working: it reports that the registry has no invitations, and there is no limit.

Changes since unreleased versions¶

These changes apply to deployments of earlier, unreleased versions, e.g. built from the repository.

Settings at start instead of build arguments¶

Before, the NEXT_PUBLIC_* settings were build arguments of the Docker image. Now, all settings are read when the app starts, and one image serves any deployment. Existing deployments must pass them with docker run now (see Docker): docker build --build-arg NEXT_PUBLIC_* only prints a warning, and new images no longer hold them in their history. The names of the settings are unchanged, so .env files and Vercel projects keep working.

Registration rules instead of settings¶

Before, the environments and URL schemes that the registry allows for services had to be set in the app as well (NEXT_PUBLIC_SERVICE_ENVIRONMENTS and NEXT_PUBLIC_SERVICE_URL_SCHEMES), in line with the registry's config. Now, the app reads them from the registry's service info (see Registry), so they can't differ from what the registry enforces (cloud-registry 1.0.0rc2 and later publish them under the name the app reads; with older registries, the edit form takes any environment and any http or https URL, and the registry checks them). Remove the two settings from your deployment (docker run -e, .env, Vercel project): if they are still set, the app ignores them and logs a warning when it starts ("Ignoring setting …").

Login providers instead of `LS_LOGIN_URL` and `OIDC_*`¶

Earlier versions supported only LS Login. Replace these variables:

Before	Now
`LS_LOGIN_URL`	`issuer` of the provider: `LS_LOGIN_URL` followed by `/oidc/`
`OIDC_CLIENT_ID`	`clientId` of the provider
`OIDC_CLIENT_SECRET`	`clientSecret` of the provider
`OIDC_REDIRECT_URI`	`LOGIN_REDIRECT_URI` (same value)

Use the LS Login example, with "scopes" as shown to keep requesting the same scopes. Users who are logged in stay logged in, as long as LS Login is the only provider: once you add a second one, their sessions end, and they log in again (see 1.0.0-rc2). The app stops with a message if it finds the old variables without LOGIN_PROVIDERS. On Vercel, change the project's environment variables before deploying this version: the build fails if the old ones are set without LOGIN_PROVIDERS. Old variables that are still set next to LOGIN_PROVIDERS are ignored, with a warning that names each of them (not their values) when the app starts: remove them, so that no stale client secret (OIDC_CLIENT_SECRET) stays in the deployment.

Admin mode¶

With cloud-registry 0.6.0 and later, admins act as admins only in admin mode, which they switch on in the app (see Admins and admin mode). All releases of the app support it; builds from before admin mode was added don't send the admin role, so their admins can't act as admins with such a registry. Replace them with a release.