docs: update the troubleshooting guide

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

website/docs/troubleshooting/index.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 7
+---
+
+# Troubleshooting
+
+If you cannot find your issue here or in the documentation, please fill an issue on our [repository](https://github.com/containers/podman-desktop/issues). You can also explore the [discussions](https://github.com/containers/podman-desktop/discussions) and do a search on similar issues on the [repository](https://github.com/containers/podman-desktop/issues).
+
+## Using the **Troubleshooting** page
+
+Podman Desktop has a **Troubleshooting** page to help identify and fix most common errors.
+
+#### Procedure
+
+1. To open the **Troubleshooting** page, click the **<icon icon="fa-solid fa-lightbulb" size="lg" />** icon.
+1. To test the connection to the container engine, click the **Ping** button.
+
+   Expect a reply such as: _Responded: 79,75 (9.10ms)_.
+
+1. To test Click the **Check containers** button.
+
+   Expect a reply such as: _Responded: 16 containers (108.70ms)_.
+
+1. When connection to the container engine failed, to recreate connections to the sockets, click the **Reconnect providers** button.
+
+   Expect a reply such as: _Done in (5.00ms)_.
+
+1. Search for errors in the **Logs** section.

website/docs/troubleshooting/troubleshooting-on-linux.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 30
+---
+
+# Troubleshooting on Linux
+
+You can find here troubleshooting help for issues specific to Linux.
+
+## Podman Desktop does not manage native Podman
+
+Podman Desktop manages Podman machines in virtual machines, and does not handle native Podman installation configuration files.

website/docs/troubleshooting/troubleshooting-on-macos.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 20
+---
+
+# Troubleshooting on macOS
+
+You can find here troubleshooting help for issues specific to macOS.
+
+### Podman machine on Apple Silicon
+
+#### Issue
+
+If you are using an Apple Silicon and brew, you might encounter the following error when starting Podman from Podman Desktop:
+
+```shell-session
+Error: qemu exited unexpectedly with exit code 1, stderr: qemu-system-x86_64: invalid accelerator hvf
+qemu-system-x86_64: falling back to tcg
+qemu-system-x86_64: unable to find CPU model 'host'
+```
+
+#### Explanation
+
+Podman machine is running as a `x86_64` process and it could be due to a dual install of homebrew: one for `x86_64` and one for `arm64`.
+
+#### Solution
+
+1. Uninstall your `x86_64` Podman machine by using one of these methods:
+
+   - Uninstall Podman machine on your `x86_64` brew install, from a terminal running under rosetta:
+
+     ```shell-session
+     $ brew uninstall podman-machine
+     ```
+
+   - Uninstall brew `x86_64` as most brew recipe have now arm64 support. Follow [these instructions](https://github.com/homebrew/install#uninstall-homebrew) from a terminal running under rosetta.
+
+1. Run a terminal in native mode (default) and install Podman machine
+
+   ```shell-session
+   $ brew install podman-machine
+   ```
+
+1. Delete your Podman machine virtual machines.
+
+   ```shell-session
+   $ podman machine rm podman-machine-default
+   ```
+
+1. Create a Podman machine:
+
+   ```shell-session
+   $ podman machine init
+   ```