docs: Add troubleshooting for slow Capella and unresponsive Xpra

docs/docs/admin/troubleshooting.md

@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Troubleshooting
+# Administrator Troubleshooting
 
 ## Can't resolve registry
 

docs/docs/development/troubleshooting.md

@@ -3,7 +3,7 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# Troubleshooting
+# Development Troubleshooting
 
 ## The `k3d` Registry is Unreachable
 

docs/docs/user/sessions/troubleshooting.md → docs/docs/user/sessions/troubleshooting/index.md

@@ -3,7 +3,12 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-??? question "My session window doesn't scale properly"
+# Session Troubleshooting
+
+<!-- prettier-ignore -->
+??? question "My session window doesn't scale properly <a href="#window-scaling">:material-link:</a>"
+
+    <span id="window-scaling" />
 
     If you use a direct session connection via Guacamole, the window doesn't scale
     automatically after browser resizing. You can manually trigger a resize by
@@ -12,7 +17,10 @@
     Alternatively, you can use our internal session viewer, which comes with
     automatic scaling out of the box.
 
-??? question "The session requests takes a long time"
+<!-- prettier-ignore -->
+??? question "The session requests takes a long time <a href="#session-request-takes-long">:material-link:</a>"
+
+    <span id="session-request-takes-long" />
 
     If a session takes a few minutes to start, it means that you've reached a
     new node that doesn't have the requested tool installed (for load balancing reasons,
@@ -21,25 +29,17 @@
     or updates from the cluster operator. In both cases, we pull a new Docker image
     (which can be understood as a reinstallation of the tool) on demand.
 
-??? question "I've minimized my window in Xpra and can't get it back"
-
-    Just refresh the page in the browser. The window should appear again.
+<!-- prettier-ignore -->
+??? question "I've minimized my window in Xpra and can't get it back <a href="#minimized-xpra-window">:material-link:</a>"
 
-??? question "The clipboard doesn't work anymore."
+    <span id="minimized-xpra-window" />
 
-    This is a known bug with our used `RDP`-server `xrdp`. `xrdp` maintains so
-    called `channels`, which are managed by the process `chansrv`. One channel
-    is `cliprdr`, which enables the clipboard feature. However, `chansrv`
-    doesn't terminate properly on session disconnects and `chansrv` doesn't
-    accept new connections. This leads to the fact that the clipboard doesn't
-    work anymore after a reconnect. The bug is tracked in the
-    [`xrdp` Github repository](https://github.com/neutrinolabs/xrdp/issues/1188)
-    and in [our Github repository](https://github.com/DSD-DBS/capella-dockerimages/issues/67).
+    Just refresh the page in the browser. The window should appear again.
 
-    The only solution for now: You have to terminate the existing session and
-    create a new session to get a working clipboard again.
+<!-- prettier-ignore -->
+??? question "My read-only sessions shows 'Modelloading failed' <a href="#modelloading-failed">:material-link:</a>"
 
-??? question "My read-only sessions shows 'Modelloading failed'"
+    <span id="modelloading-failed" />
 
     This happens if the loading of one of the models fails.
     Please reach out your project lead. If you are project lead, please check
@@ -50,19 +50,41 @@
     If you have no success, please reach out your administrator. Administrators
     can see the logs of read-only sessions.
 
-??? question "The TeamForCapella password doesn't work"
+<!-- prettier-ignore -->
+??? question "The TeamForCapella password doesn't work <a href="#t4c-password-doesnt-work">:material-link:</a>"
+
+    <span id="t4c-password-doesnt-work" />
 
     Since we have released version 2, users have to use sessions passwords. More
-    information can be found [here](../tools/capella/teamforcapella/connect/index.md).
+    information can be found [here](../../tools/capella/teamforcapella/connect/index.md).
     If you have been added to a project recently while having a running session,
     please recreate your session to get a valid session password for the models
     of the required project.
 
 <!-- prettier-ignore -->
-??? question "I can't use the `Control` key for the secondary/right-click on macOS"
+??? question "I can't use the `Control` key for the secondary/right-click on macOS <a href="#macos-control-key">:material-link:</a>"
+
+    <span id="macos-control-key"/>
 
     Please use an external mouse or use the trackpad gesture (click with two
     fingers on the trackpad).
 
     The sessions run on Linux and the `Control` key can't be mapped properly
     via the remote desktop protocol.
+
+    Alternatively, you can use the Xpra connection method instead of Guacamole.
+
+<!-- prettier-ignore -->
+??? question "My Xpra window doesn't react anymore <a href="#xpra-reaction">:material-link:</a>"
+
+    <span id="xpra-reaction"/>
+
+    If the Xpra window doesn't react anymore, a modal dialog in the background might block the main window.
+
+    To identify a potential hidden dialog, double-click on the title-bar of the application in Xpra. Alternatively, you can minimize it:
+    ![Minimize Xpra window](./minimize-xpra.png)
+
+    Then, drag the window around to see if there is any other modal dialog window. If you find one, close it.
+
+    Another option is to refresh the browser tab. It will bring the hidden modal dialog into the foreground.
+    This step might take a bit longer.

docs/docs/user/sessions/troubleshooting/minimize-xpra.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/docs/user/tools/capella/troubleshooting/close-projects.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/docs/user/tools/capella/troubleshooting/confirm-close-projects.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/docs/user/tools/capella/troubleshooting/index.md

@@ -5,7 +5,10 @@
 
 # Capella Troubleshooting
 
-!!! question "My Capella crashed. What should I do?"
+<!-- prettier-ignore -->
+??? question "My Capella crashed. What should I do? <a href="#capella-crash">:material-link:</a>"
+
+    <span id="capella-crash" />
 
     Capella can crash for many different reasons. Many issues are issues with
     Eclipse Capella itself, so we try to escalate issues there. Bugs can be
@@ -21,7 +24,10 @@
     1. You should now see the list of events and you can try to find an entry with
        a matching timestamp.
 
-!!! question "The description editor doesn't load anymore"
+<!-- prettier-ignore -->
+??? question "The description editor doesn't load anymore <a href="#description-editor">:material-link:</a>"
+
+    <span id="description-editor" />
 
     In some cases the description doesn't load anymore, is just a blank page, or looks like this:
 
@@ -51,5 +57,37 @@
 
     - End your session and request a new session in the Capella Collaboration Manager.
 
-
     If none of these workarounds help, the only solution is to reset your workspace. Please contact your administrator for assistance.
+
+<!-- prettier-ignore -->
+??? question "My Capella is slow. What can I do? <a href="#slow-capella">:material-link:</a>"
+
+    <span id="slow-capella" />
+
+    A slow Capella instance can have multiple reasons. Here are some common issues:
+
+    1.  __Disable the automatic refresh in the Semantic Browser__
+
+        The automatic refresh of the Semantic Browser slows down Capella when connected to a TeamForCapella repository.
+
+        By default, the Semantic Browser auto-refresh is enabled. You can disable it in each session using the button marked in the screenshot (red/right box).
+        After you've disabled the auto-refresh, you can manually refresh the Semantic Browser by clicking the refresh button (blue/left box):
+        ![Semantic Browser](./semantic-browser-autorefresh.png)
+
+        When you want to save the option for all future sessions, disable it in the UI first and then close Capella to save the workbench state: <br>
+        ![Exit Capella](./exit-capella.png){:style="width:300px"}
+
+    1.  __Close all unrelated projects and tabs__
+
+        Navigate to the project explorer in Capella and right-click the project you want to work on.
+        Select "Close projects":
+
+        ![Close projects](./close-projects.png){:style="width:300px"}
+
+        Then, confirm the dialog:
+
+        ![Confirm to close the projects](./confirm-close-projects.png)
+
+        This will close all projects except the selected one.
+
+    If none of those steps help, please reach out to your system administrator.

docs/docs/user/tools/capella/troubleshooting/restart-capella.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/docs/user/tools/capella/troubleshooting/semantic-browser-autorefresh.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/mkdocs.yml

@@ -50,7 +50,7 @@ nav:
           - Terminate Session: user/sessions/terminate.md
           - Taking Screenshots: user/sessions/screenshots/index.md
           - Files Browser: user/sessions/files/index.md
-          - Troubleshooting: user/sessions/troubleshooting.md
+          - Troubleshooting: user/sessions/troubleshooting/index.md
       - Capella:
           - Introduction: user/tools/capella/introduction.md
           - Update a Capella Model to a Newer Version: user/tools/capella/migration/index.md