Upgrade documentation

Author: filippomc

docs/upgrades/2.x_3.x.md

@@ -0,0 +1,73 @@
+
+## Upgrade project from 2.x to 3.x
+
+## Update Python virtual environment
+
+With conda:
+
+```sh
+conda create --name ENVNAME python=3.12
+conda activate ENVNAME
+source install.sh
+```
+
+## Migrate cloudharness-base images to debian
+
+Before 3.x, there were 2 different base images that could be used on applications:
+
+- `cloudharness-base` -- based on Alpine -- `FROM $CLOUDHARNESS_BASE` in Dockerfiles
+- `cloudharness-base-debian` -- based on Debian -- `FROM $CLOUDHARNESS_BASE_DEBIAN` in Dockerfiles
+
+Now `cloudharness-base` is based on Debian and `cloudharness-base-debian` cannot be used anymore as a dependency
+
+The new command `harness-migrate` will help with porting your cloudharness-base dependent images to debian.
+
+After that, it's likely that some apk based dependencies have still to be tweaked in your Dockerfiles.
+
+
+## Update Keycloak
+
+Updating Keycloak is easily done by restoring a Postgres backup after the upgrade is done,
+and letting Keycloak apply the migrations taking care of not mixing old and new replicas.
+
+### Prepare for update
+
+The new update is available on Cloud Harness 3.x+, or the develop branch.
+
+The following files are usually overridden and might need merge/replacement:
+
+applications/accounts/Dockerfile
+
+applications/accounts/deploy/resources/realm.json
+
+deployment-configuration/helm/templates/auto-gatekeepers.yaml
+
+In addition to this, there might be references to the code to old paths, as the new version removed the /auth prefix.
+
+If keycloak-js is used, better remove it as the updated version has known issues and doesn’t work on local deployments. The replacement to keycloak-js is to use a Gatekeeper and get user information from the kc-access cookie, as done for example here.
+
+### Upgrade procedure 
+#### Before upgrading
+```sh
+BACKUP_FILE=full_backup_keycloak_postgres.psql
+NAMESPACE="${1:-neuroglass-research}"
+
+kubectl exec -n $NAMESPACE deployment/keycloak-postgres -- pg_dump -d auth_db -U postgres -F c > kc-$BACKUP_FILE
+
+kubectl scale deployment accounts --replicas=0 -n $NAMESPACE
+```
+
+#### After upgrading (new version deployed)
+```sh
+kubectl scale deployment accounts --replicas=0 -n $NAMESPACE
+kubectl exec -i -n $NAMESPACE deployment/keycloak-postgres -- psql -U user -d auth_db -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
+kubectl exec -i -n $NAMESPACE deployment/keycloak-postgres -- pg_restore --if-exists --no-owner --clean -d auth_db -U user < kc-$BACKUP_FILE
+kubectl scale deployment accounts --replicas=1 -n $NAMESPACE
+```
+
+### Manual steps
+
+There are a few known issues that have to be fixed manually after the upgrade:
+
+1. Users cannot access their account page (e.g. https://accounts.research.neuroglass.dev.metacell.us/realms/mnp/account/) unless this: https://github.com/keycloak/keycloak/discussions/12894#discussioncomment-3145960 →  add the client scopes as optional to the account-console client.
+2. sub is not present in the token → add the mapper for sub to the profile client scope