docs(modeler): add troubleshooting entry for sandboxing issue (#4607)

Related to camunda/camunda-modeler#4695 Co-authored-by: Christina Ausley <[email protected]>
camunda · Nov 19, 2024 · 5e7ce8b · 5e7ce8b
1 parent 4d96672
commit 5e7ce8b
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 0 deletions.
diff --git a/docs/components/modeler/desktop-modeler/troubleshooting.md b/docs/components/modeler/desktop-modeler/troubleshooting.md
@@ -171,6 +171,18 @@ DEBUG=* ZEEBE_NODE_LOG_LEVEL=DEBUG GRPC_VERBOSITY=DEBUG GRPC_TRACE=all camunda-m
 </TabItem>
 </Tabs>
 
+## Desktop Modeler does not start on Ubuntu 24 / modern Linux
+
+Modern Linux operating systems introduce restrictions on user namespaces, a sandboxing (isolation) mechanism Modeler uses. You may see an error message when you start the application:
+
+```sh
+$ ./camunda-modeler
+[46193:1114/170934.837319:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that [...]/camunda-modeler-[...]-linux-x64/chrome-sandbox is owned by root and has mode 4755.
+zsh: trace trap (core dumped)  ./camunda-modeler
+```
+
+To remedy this, configure your system to allow sandboxing by [creating an AppArmor profile](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478458250), or review [this issue](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478581677) for an in-depth explanation of available options. If you don't have the necessary permissions to permit sandboxing, you may choose to disable the sandbox, though this is not recommended.
+
 ## Other questions?
 
 Head over to the [Modeler category on the forum](https://forum.camunda.io/c/modeler/6) to receive help from the community.
diff --git a/versioned_docs/version-8.5/components/modeler/desktop-modeler/troubleshooting.md b/versioned_docs/version-8.5/components/modeler/desktop-modeler/troubleshooting.md
@@ -171,6 +171,18 @@ DEBUG=* ZEEBE_NODE_LOG_LEVEL=DEBUG GRPC_VERBOSITY=DEBUG GRPC_TRACE=all camunda-m
 </TabItem>
 </Tabs>
 
+## Desktop Modeler does not start on Ubuntu 24 / modern Linux
+
+Modern Linux operating systems introduce restrictions on user namespaces, a sandboxing (isolation) mechanism Modeler uses. You may see an error message when you start the application:
+
+```sh
+$ ./camunda-modeler
+[46193:1114/170934.837319:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that [...]/camunda-modeler-[...]-linux-x64/chrome-sandbox is owned by root and has mode 4755.
+zsh: trace trap (core dumped)  ./camunda-modeler
+```
+
+To remedy this, configure your system to allow sandboxing by [creating an AppArmor profile](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478458250), or review [this issue](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478581677) for an in-depth explanation of available options. If you don't have the necessary permissions to permit sandboxing, you may choose to disable the sandbox, though this is not recommended.
+
 ## Other questions?
 
 Head over to the [Modeler category on the forum](https://forum.camunda.io/c/modeler/6) to receive help from the community.
diff --git a/versioned_docs/version-8.6/components/modeler/desktop-modeler/troubleshooting.md b/versioned_docs/version-8.6/components/modeler/desktop-modeler/troubleshooting.md
@@ -171,6 +171,18 @@ DEBUG=* ZEEBE_NODE_LOG_LEVEL=DEBUG GRPC_VERBOSITY=DEBUG GRPC_TRACE=all camunda-m
 </TabItem>
 </Tabs>
 
+## Desktop Modeler does not start on Ubuntu 24 / modern Linux
+
+Modern Linux operating systems introduce restrictions on user namespaces, a sandboxing (isolation) mechanism Modeler uses. You may see an error message when you start the application:
+
+```sh
+$ ./camunda-modeler
+[46193:1114/170934.837319:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that [...]/camunda-modeler-[...]-linux-x64/chrome-sandbox is owned by root and has mode 4755.
+zsh: trace trap (core dumped)  ./camunda-modeler
+```
+
+To remedy this, configure your system to allow sandboxing by [creating an AppArmor profile](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478458250), or review [this issue](https://github.com/camunda/camunda-modeler/issues/4695#issuecomment-2478581677) for an in-depth explanation of available options. If you don't have the necessary permissions to permit sandboxing, you may choose to disable the sandbox, though this is not recommended.
+
 ## Other questions?
 
 Head over to the [Modeler category on the forum](https://forum.camunda.io/c/modeler/6) to receive help from the community.