Merge pull request #452 from holochain/hotfix-add-advice-for-ubuntu

add instructions for fixing security error in Ubuntu 24.04

Author: pdaoust

.cspell/custom-words.txt

@@ -27,6 +27,8 @@ QUIC
 rustc
 rustflags
 rustup
+setgid
+setuid
 subl
 Tauri
 Ulhaq

.cspell/words-that-should-exist.txt

@@ -15,8 +15,10 @@ howtos
 interoperating
 permissioned
 permissivity
+redistributable
 runtimes
 sandboxed
+sandboxing
 scaffolder
 spacebar
 todo

src/pages/get-started/2-hello-world.md

@@ -30,6 +30,17 @@ nix develop
 ```shell
 npm install
 ```
+
+!!! info Warning for Ubuntu 24.04 and later
+Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that cause the following command to fail. Here's a simple fix. In your terminal, run this command:
+
+```shell
+chmod 4755 node_modules/electron/dist/chrome-sandbox && sudo chown root:root node_modules/electron/dist/chrome-sandbox
+```
+
+You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
+!!!
+
 ```shell
 npm start
 ```

src/pages/get-started/3-forum-app-tutorial.md

@@ -795,6 +795,16 @@ Before you get started editing the UI, it's helpful to be able to actually run t
 
 ## 8. Run your application in dev mode
 
+!!! info Warning for Ubuntu 24.04 and later
+Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that cause the following command to fail. Here's a simple fix. In your terminal, run this command:
+
+```shell
+chmod 4755 node_modules/electron/dist/chrome-sandbox && sudo chown root:root node_modules/electron/dist/chrome-sandbox
+```
+
+You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
+!!!
+
 At this stage, we'll incorporate some of the UI components that have been scaffolded by the scaffolding tool into our main application interface. Our aim here is to make all the functionality of our forum application accessible from a single, unified interface. We'll use Svelte to accomplish this, as it is the framework that we have chosen for the UI layer of our application.
 
 Start the forum hApp in develop mode from the command line: go to your terminal and, from the root folder (`my_forum_app/`), enter:

src/pages/get-started/install-advanced.md

@@ -265,4 +265,28 @@ rm -rf /nix
 rm ~/.nix-profile
 ```
 
-[Detailed uninstallation instructions for macOS](https://gist.github.com/chriselsner/3ebe962a4c4bd1f14d39897fc5619732#uninstalling-nix)
+[Detailed uninstallation instructions for macOS](https://gist.github.com/chriselsner/3ebe962a4c4bd1f14d39897fc5619732#uninstalling-nix)
+
+## Fixing the SUID sandbox error in Ubuntu 24.04
+
+Ubuntu 24.04 [introduced an AppArmor security policy](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that causes `hc spin`, which is used to test applications and their UIs, to fail with a fatal error. If you have a `package.json` that lists `@holochain/hc-spin` as a dev dependency, you may see this error message:
+
+::: output-block
+```
+[FATAL:setuid_sandbox_host.cc(158)] 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 <path_to_your_application_project>/node_modules/electron/dist/chrome-sandbox is owned by root and has mode 4755.
+```
+:::
+
+You can fix the issue by entering the following command in your project's root directory:
+
+```shell
+chmod 4755 node_modules/electron/dist/chrome-sandbox && sudo chown root:root node_modules/electron/dist/chrome-sandbox
+```
+
+You'll have to do this for every hApp project that uses `@holochain/hc-spin`.
+
+There are other fixes [outlined in the Ubuntu 24.04 release notes](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that can solve the problem; if you'd like to learn more, read through them all and choose the one that feels most appropriate for you.
+
+### Redistributable applications created with [`holochain-kangaroo-electron`](https://github.com/holochain-apps/holochain-kangaroo-electron) are also affected
+
+Because the template repo `holochain-kangaroo-electron` also bundles Electron's chrome-sandbox in the binary that you'd distribute, your users will see the same error message when they try to run your application if you've used this repo. We're still researching the best solution, but since Ubuntu is recommending it, we recommend applying the first solution in the release notes, which involves creating an AppArmor profile for your app. This profile could then be distributed and installed alongside it. (Note: this won't work with portable application packages that aren't installed as root, such as `AppImage`s.)