Migrating to ArconQ 1.2.0

ArconQ 1.2.0 introduces two foundational changes that together make this a breaking upgrade and drive the steps in this guide:

• Authentication and authorization move to Keycloak. This allows ArconQ to be connected to external identity providers via Keycloak, enabling features such as Single Sign-On (SSO) and centralized user management, e.g. via Active Directory.
• ArconQ now runs under a restricted security context. Every pod runs as a non-root user with all Linux capabilities dropped, so apps no longer have root access. This affects app shared storage and Debug Mode — see Security context for the full posture.

Breaking change

• Because identity management moves to Keycloak, the existing users, roles and external clients in ArconQ are not carried over by the update and will be lost. Apps that rely on external clients for authorization are affected as well.
• Because apps now run without root access, app shared storage and Debug Mode apps must be prepared and reconfigured around the update.

Please read this guide in full and complete the preparation steps before you update.

What is affected

Affected	What happens during the update
Users	All existing user accounts are removed and must be recreated after the update.
Roles	Custom roles are removed and must be recreated after the update.
External clients	All external clients (including the one used by the ArconQ CLI) are removed and must be recreated, with new client secrets.
Apps	Apps that authenticate against ArconQ or use external clients need their authorization reconfigured once the clients are recreated.
Debug Mode apps	Apps now run as a non-root user, so in Debug Mode SSH listens on port 2222 instead of 22. Debug Mode apps also get a new Remote password on import, so their App port mappings and SDK debug configuration must be updated — see After updating.
Workspaces	Workspaces are preserved through export and import, as described below.
App shared storage	Files and directories created there by the apps are owned by the root. After the update, apps will lose access to them.

Authentication endpoint changes

Because authentication now runs on Keycloak, the OpenID Connect (OIDC) endpoints exposed by your ArconQ instance have changed. Keycloak serves OIDC under a realm-specific base path, so any application, external client or script that referenced the old endpoints — or hardcoded them instead of relying on OIDC discovery — must be updated.

The OIDC issuer (authority) is now the realm URL, and all other endpoints live underneath it:

Endpoint	Before 1.2.0	From 1.2.0
Authority / issuer	https://<your-instance>	https://<your-instance>/identity-provider/realms/arconq
OpenID configuration (discovery)	https://<your-instance>/.well-known/openid-configuration	https://<your-instance>/identity-provider/realms/arconq/.well-known/openid-configuration
Token endpoint	https://<your-instance>/connect/token	https://<your-instance>/identity-provider/realms/arconq/protocol/openid-connect/token

For example, on an instance reachable at https://arconq.prod the discovery document is now served at https://arconq.prod/identity-provider/realms/arconq/.well-known/openid-configuration.

tip

Prefer OIDC discovery over hardcoding individual endpoints: point your OIDC client at the authority above and let it read the token, authorization and other endpoints from the discovery document. This keeps your apps working if endpoint paths change again. See External clients and the Authorization SDK reference.

note

The ArconQ CLI is configured with the instance Server URL (e.g. https://arconq.prod) and resolves these endpoints automatically, so no endpoint changes are needed there — only the recreated client secret.

Migration steps

1. Before updating

1. Make sure you have access to an admin account. You will need it to recreate users, roles and external clients after the update.

2. Export all of your workspaces. Each workspace is exported as a .zip file. See Importing and exporting workspaces, or Advanced import and export if you need to include additional data from your environment.

3. Write down your current configuration of not exportable resources so you can recreate it afterwards:

   • the users and the roles assigned to them — see Role management,
   • your custom roles,
   • your external clients and their settings (grant types, redirect URIs and assigned roles) — see External clients. Client secrets cannot be recovered and will be regenerated when the clients are recreated.

4. Fix file ownership in app shared storage.

   Applies only if you use app shared storage in your apps — expand for the details.

   Files and folders written by apps on versions prior to 1.2.0 are owned by root. Starting with 1.2.0, apps run as uid/gid 58360 and will be denied access to those paths.

   Before you update, recursively change the ownership of everything under the app shared storage to uid/gid 58360, so the apps keep access after the upgrade. Changing ownership requires root access to the volume — which apps no longer have once 1.2.0 is running — so perform it while you can still reach the storage as root. Apply the change to the volume using the access method appropriate for your environment.

2. Update ArconQ

1. Delete all existing workspaces before performing the update.

2. Move the PostgreSQL data into a pgdata subdirectory.

   Applies only to installations without an external PostgreSQL connection — expand for the details.

   ArconQ 1.2.0 expects the bundled PostgreSQL data to live in a pgdata subdirectory of its data volume rather than at the root of the volume. Relocate the existing data accordingly while the PostgreSQL pod is not running and before you deploy 1.2.0:

   • Stop PostgreSQL so nothing is writing to the volume (for example, by scaling its stateful set down to zero replicas).
   • Move the current contents of the data volume into a new pgdata subdirectory.
   • Ensure the pgdata directory is owned by uid/gid 999 and has 0700 permissions, as PostgreSQL requires.

   Apply the change to the volume using the access method appropriate for your environment. PostgreSQL loads the relocated data automatically once 1.2.0 is deployed — no manual restart is required.

3. Update ArconQ to version 1.2.0: see Install ArconQ,

3. After updating

1. Log in with your admin account.

2. Recreate your custom roles — see Role management.

3. Recreate your users and assign them the appropriate roles.

4. Recreate your external clients — see External clients. New client secrets are generated, so update everywhere the old secret was stored, including your ArconQ CLI configuration.

5. Import your desired workspaces back into the updated installation — see Importing and exporting workspaces.

6. Verify your apps, especially those that rely on external clients for authorization, and update their configuration with the recreated clients where needed. If an app references the OIDC authority or token endpoint directly, update it to the new Keycloak endpoints — see Authentication endpoint changes.

7. Reconfigure your Debug Mode apps. This step applies only to apps you run in Debug Mode; other apps are unaffected. For each Debug Mode app:

   • Point the App port mapping at the new SSH port. Apps now run as a non-root user and can no longer bind to the privileged port 22, so in Debug Mode SSH listens on 2222. In the app's App port mapping, the App Port (the internal port the mapping targets) must be 2222 instead of 22. Leave the External Port unchanged.
     • If you used a standard workspace export, App port mappings are not included and must be recreated from scratch with App Port 2222.
     • If you used advanced export with app port mappings selected, the mappings are restored with the old App Port 22 and must be recreated with port 2222.
   • Copy the new Remote password into your app. The Remote password is regenerated when the app is imported. Copy the new value from the app details in the ArconQ UI into the config.Password property of your ConfigureDebugMode block. Note that config.ServerExposedPort keeps matching the External Port of the mapping — it does not change to 2222.