From bacb2963a73933beed13fe64027a9708c8fe363c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 3 Jul 2023 17:33:19 +0200 Subject: [PATCH] docs: update the troubleshooting guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- website/docs/troubleshooting.md | 284 ------------------ .../img/containers_error.png | Bin website/docs/troubleshooting/index.md | 28 ++ .../troubleshooting-on-linux.md | 11 + .../troubleshooting-on-macos.md | 53 ++++ .../troubleshooting-on-windows.md | 54 ++++ .../troubleshooting-openshift-local.md | 31 ++ .../troubleshooting/troubleshooting-podman.md | 129 ++++++++ 8 files changed, 306 insertions(+), 284 deletions(-) delete mode 100644 website/docs/troubleshooting.md rename website/docs/{ => troubleshooting}/img/containers_error.png (100%) create mode 100644 website/docs/troubleshooting/index.md create mode 100644 website/docs/troubleshooting/troubleshooting-on-linux.md create mode 100644 website/docs/troubleshooting/troubleshooting-on-macos.md create mode 100644 website/docs/troubleshooting/troubleshooting-on-windows.md create mode 100644 website/docs/troubleshooting/troubleshooting-openshift-local.md create mode 100644 website/docs/troubleshooting/troubleshooting-podman.md diff --git a/website/docs/troubleshooting.md b/website/docs/troubleshooting.md deleted file mode 100644 index a08d07a2cc595..0000000000000 --- a/website/docs/troubleshooting.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -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. -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. - -## Podman Issues - -### Unable to see any image or container after downloading Podman Desktop - -#### System Requirements - -The tool connects to Podman using the socket on the host on macOS and on a named pipe on Windows. -This is available only on Podman 4.0.2+ -So, please check your version and update. - -On Windows, the named pipe is `//./pipe/docker_engine` when Docker Desktop is not installed. It will be solved by / . During that time, you might start Docker Desktop so the named pipe is the one expected. - -#### Check connection - -Check at least a Podman machine is running on Windows & macOS: - -```bash -podman machine list -``` - -And check a connection can be made with the CLI - -```sh -$ podman run quay.io/podman/hello -!... Hello Podman World ...! - - .--"--. - / - - \ - / (O) (O) \ - ~~~| -=(,Y,)=- | - .---. /` \ |~~ - ~/ o o \~~~~.----. ~~ - | =(X)= |~ / (O (O) \ - ~~~~~~~ ~| =(Y_)=- | - ~~~~ ~~~| U |~~ - -Project: https://github.com/containers/podman -Website: https://podman.io -Documents: https://docs.podman.io -Twitter: @Podman_io -``` - -### Unable to locate Podman Engine - -#### Issue - -Despite having Podman Engine installed, you may receive an error as follows - -`Error: No such keg: /usr/local/Cellar/podman` -or any similar error denoting that Podman Engine does not exist. - -#### Explanation - -The Podman Installer and Homebrew use different locations to store the Podman Engine files in the file system. For example, Podman Installer installs Podman Engine in the path `/opt/podman` whereas Homebrew uses the path `/usr/local` for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. - -#### Solution - -To check where exactly is your Podman Engine installed, run the command- - -```sh -which podman -``` - -This returns the path where the Podman Engine would be installed. This would help determine further action. - -For example, if you’re looking to completely uninstall Podman Engine from your system for a fresh installation, running `which podman` returns the exact path where Podman still exists. This could be the path where Podman Installer stores Podman Engine i.e. `/opt/podman`. Once you know the path, run: - -```sh -sudo rm -rf /opt/podman -``` - -Or - -```sh -sudo rm -rf path-where-podman-exists -``` - -Here, you would replace `path-where-podman-exists` with the output of `which podman`. - -You can now proceed for a fresh installation of Podman Desktop - -### Unable to see information about active containers - -#### Issue - -In this scenario, the screen may be displaying "No Containers" as shown below despite active containers runnning in the background. -![img](img/containers_error.png) - -#### Solution - -There are three ways to work this out. - -1. To solve this issue, open the Terminal and run the following commands- - - ```shell-session - podman machine stop - podman machine start - ``` - -2. If this does not work for you, you might proceed with the following commands- - - ```shell-session - $ podman machine rm - $ podman machine init - ``` - -3. If both of the abovementioned steps don't work for you, run the following commands- - - ```shell-session - $ rm -rf ~/.local/share/containers/podman - $ rm -rf ~/.config/containers/ - ``` - - After this, you can start off again by initializing a new Podman Machine and loading up the containers. - -### Unable to set custom binary path for Podman on macOS - -#### Issue - -When setting a custom binary path (under Preferences -> Custom binary path), Podman is unable to find `gvproxy` and `podman-mac-helper`: - -```sh -Error: unable to start host networking: "could not find \"gvproxy\" in one of [/usr/local/opt/podman/libexec /opt/homebrew/bin /opt/homebrew/opt/podman/libexec /usr/local/bin /usr/local/libexec/podman /usr/local/lib/podman /usr/libexec/podman /usr/lib/podman $BINDIR/../libexec/podman]. To resolve this error, set the helper_binaries_dir key in the `[engine]` section of containers.conf to the directory containing your helper binaries." -``` - -#### Solution - -1. Download `gvproxy` from the [gvisor-tap-vsock release page](https://github.com/containers/gvisor-tap-vsock/releases). -2. Build the `podman-mac-helper` from the source code on the [Podman GitHub page](https://github.com/containers/podman/tree/main/cmd/podman-mac-helper). -3. Add the `helpers_binaries_dir` entry to `~/.config/containers/conf`: - -```sh -[containers] - -helper_binaries_dir=["/Users/user/example_directory"] -``` - -**NOTE**: A pre-built binary will be added to the Podman release page so you do not have to build `podman-mac-helper`. An [issue is open for this](https://github.com/containers/podman/issues/16746). - -### Warning about Docker compatibility mode - -#### Issue - -When running the Podman provider, a warning shows regarding Docker compatibility mode on the dashboard: - -```sh -⚠️ Docker Socket Compatibility: Podman is not emulating the default Docker socket path: '/var/run/docker.sock'. Docker-specific tools may not work. See troubleshooting page on podman-desktop.io for more information. -``` - -This may appear when either: - -- The Docker socket is not mounted correctly -- Docker Desktop is also being ran at the same time - -#### Solution - -**On macOS:** - -1. Stop Docker Desktop (if install) -2. Run the `podman-mac-helper` binary: - - ```sh - sudo podman-mac-helper install - ``` - - for additional options please run the command: - - ```sh - sudo podman-mac-helper install --help - ``` - -3. Restart the Podman machine (the default Docker socket path will be recreated and Podman will emulate it) - -**On Linux / Windows:** - -1. Stop Docker Desktop (if installed) -2. Restart the Podman machine (the default Docker socket path will be recreated and Podman will emulate it) - -_Note:_ If Docker Desktop is started again, it will automatically re-alias the default Docker socket location and the Podman compatibilty warning will re-appear. - -## Code Ready Containers - -- Check that Podman preset is defined. (`crc config get preset`) -- Check that `crc` binary is available in the user PATH (`/usr/local/bin/crc`) -- Check that `crc setup --check-only` is running without errors. - -## Other Issues - -### Fixing corrupted Podman Machine in Windows - -If at all you are not able to stop your Podman Machine, you will find such an error in the Logs- -`Error: Error stopping sysd: exit status 1` - -It is highly unlikely that you may be stuck in such a situation but if you are, here's a quick fix for it. - -Assuming the name of the Podman Machine to be `my-machine`, run the following commands in the terminal: - -```sh -wsl --list -``` - -This shall display a list of active distributions i.e. `my-machine` in this case. - -Then, - -```sh -wsl --unregister my-machine -``` - -(Replacing `my-machine` with the name that is displayed under `wsl --list` for your Podman Machine) - -This will stop the Podman Machine for you. - -### 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 - -You can - -1. Uninstall Podman machine on your `x86_64` brew install (for example from a terminal running under rosetta) `brew uninstall podman-machine` -2. or uninstall brew `x86_64` as most brew receipe have now arm64 support: follow [these instructions](https://github.com/homebrew/install#uninstall-homebrew) from a terminal running under rosetta - -Then run a terminal in native mode (default) and install Podman machine `brew install podman-machine` - -Finally clean the Podman machine VMs that had been previously created, and create new ones. - -```shell-session -$ podman machine rm podman-machine-default -$ podman machine init -``` - -You should be a happy camper from here. - -### The terminal session attaches to Podman Desktop when launching it from the command line in Windows - -#### Issue - -When you start Podman Desktop from the command line in Windows the terminal session attaches to it. You cannot quit the terminal because it will kill Podman Desktop as well. - -#### Solution - -Set the environment variable `ELECTRON_NO_ATTACH_CONSOLE` to true before launching Podman Desktop. diff --git a/website/docs/img/containers_error.png b/website/docs/troubleshooting/img/containers_error.png similarity index 100% rename from website/docs/img/containers_error.png rename to website/docs/troubleshooting/img/containers_error.png diff --git a/website/docs/troubleshooting/index.md b/website/docs/troubleshooting/index.md new file mode 100644 index 0000000000000..1a68091cfb88c --- /dev/null +++ b/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. +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. diff --git a/website/docs/troubleshooting/troubleshooting-on-linux.md b/website/docs/troubleshooting/troubleshooting-on-linux.md new file mode 100644 index 0000000000000..713440a06a12d --- /dev/null +++ b/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. diff --git a/website/docs/troubleshooting/troubleshooting-on-macos.md b/website/docs/troubleshooting/troubleshooting-on-macos.md new file mode 100644 index 0000000000000..69ba065f7f295 --- /dev/null +++ b/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 + ``` diff --git a/website/docs/troubleshooting/troubleshooting-on-windows.md b/website/docs/troubleshooting/troubleshooting-on-windows.md new file mode 100644 index 0000000000000..e4f2478dba1a7 --- /dev/null +++ b/website/docs/troubleshooting/troubleshooting-on-windows.md @@ -0,0 +1,54 @@ +--- +sidebar_position: 10 +--- + +# Troubleshooting on Windows + +You can find here troubleshooting help for issues specific to Windows. + +## Deleting a corrupted Podman Machine + +#### Issue + +1. You are not able to stop your Podman Machine. + + ``` + $podman machine stop + ``` + +2. The Logs contain this error: + + ``` + Error: Error stopping sysd: exit status 1 + ``` + +#### Workaround + +1. To display the active WSL distribution list: in the terminal, run: + + ```sh + > wsl --list + ``` + +1. The command returns the list of active WSL distributions. Identify your Podman Machine in the list, such as `podman-machine-default`. + +1. To stop, unregister, and uninstall your Podman Machine: in the terminal, replace `podman-machine-default` by your Podman machine name, and run: + + ```sh + > wsl --unregister podman-machine-default + ``` + +#### Additional resources + +- https://learn.microsoft.com/en-us/windows/wsl/basic-commands#unregister-or-uninstall-a-linux-distribution + +## The terminal session attaches to Podman Desktop when launching it from the command line + +#### Issue + +1. When you start Podman Desktop from the command line in Windows the terminal session attaches to it. +1. When you quit the terminal, it kills Podman Desktop. + +#### Solution + +- Set the environment variable `ELECTRON_NO_ATTACH_CONSOLE` to true before launching Podman Desktop. diff --git a/website/docs/troubleshooting/troubleshooting-openshift-local.md b/website/docs/troubleshooting/troubleshooting-openshift-local.md new file mode 100644 index 0000000000000..45cc023f8fae8 --- /dev/null +++ b/website/docs/troubleshooting/troubleshooting-openshift-local.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 30 +--- + +# Troubleshooting OpenShift Local + +You can find here troubleshooting help for issues specific to OpenShift Local. + +1. To verify that your user can run `crc`, check that the `crc` binary is available in the user PATH (`/usr/local/bin/crc` on macOS and Linux). + +2. To verify that the host is ready to run OpenShift Local, in a terminal, run this command and verify the output has no errors: + + ``` + $ crc setup --check-only + ``` + + Sample output: + + ``` + INFO Using bundle path + INFO Checking if running as non-root + INFO Checking if running inside WSL2 + INFO Checking if crc-admin-helper executable is cached + crc-admin-helper executable is not cached + ``` + +3. To verify the configured preset, in a terminal, run: + + ``` + $ crc config get preset + ``` diff --git a/website/docs/troubleshooting/troubleshooting-podman.md b/website/docs/troubleshooting/troubleshooting-podman.md new file mode 100644 index 0000000000000..8a24445afd23c --- /dev/null +++ b/website/docs/troubleshooting/troubleshooting-podman.md @@ -0,0 +1,129 @@ +--- +sidebar_position: 2 +--- + +# Troubleshooting Podman + +## Check for available space before initializing a Podman machine + +#### Issue + +When the available disk space left is not enough, initializing a Podman machine might fail. + +#### Workaround + +Verify the available space before initializing a Podman machine. + +## Unable to see any image or container + +#### Issue + +1. You installed Podman Desktop and Podman. +1. On Windows and macOS, you initialized and started a Podman machine. +1. You pulled images to Podman. +1. You started containers in Podman. +1. You are unable to see any image or container in Podman Desktop. + + ![img](./img/containers_error.png) + +### Verifying system requirements + +1. Podman Desktop requires Podman 4.0.2 or greater, to connect to Podman by using the socket on the host on macOS and a named pipe on Windows. + +2. On Windows, when Docker Desktop is not running, Podman Desktop requires Podman 4.1 or greater, to start Podman with the expected named pipe. Else Podman start with the named pipe is `//./pipe/docker_engine` See: / . + +### Verifying that on + +1. On Windows and macOS, verify that at least one Podman machine is running: + + ```shell-session + $ podman machine list + ``` + +### Verifying the connection to Podman + +1. To verify that you can connect to Podman by using the CLI, run a dummy container: + + ```shell-session + $ podman run quay.io/podman/hello + !... Hello Podman World ...! + + .--"--. + / - - \ + / (O) (O) \ + ~~~| -=(,Y,)=- | + .---. /` \ |~~ + ~/ o o \~~~~.----. ~~ + | =(X)= |~ / (O (O) \ + ~~~~~~~ ~| =(Y_)=- | + ~~~~ ~~~| U |~~ + + Project: https://github.com/containers/podman + Website: https://podman.io + Documents: https://docs.podman.io + Twitter: @Podman_io + ``` + +1. To restart the Podman machine, in a terminal, run: + + ```shell-session + podman machine stop + podman machine start + ``` + +1. To delete the Podman machine, and create another Podman machine, in a terminal, run: + + ```shell-session + $ podman machine rm + $ podman machine init + ``` + +1. To delete all containers-related configuration files: + + ```shell-session + $ rm -rf ~/.local/share/containers/podman + $ rm -rf ~/.config/containers/ + ``` + + After this, you can start off again by initializing a new Podman Machine and loading up the containers. + +### Warning about Docker compatibility mode + +#### Issue + +When running the Podman provider, a warning shows regarding Docker compatibility mode on the dashboard: + +```sh +⚠️ Docker Socket Compatibility: Podman is not emulating the default Docker socket path: '/var/run/docker.sock'. Docker-specific tools may not work. See troubleshooting page on podman-desktop.io for more information. +``` + +This may appear when either: + +- The Docker socket is not mounted correctly +- Docker Desktop is also being ran at the same time + +#### Solution + +**On macOS:** + +1. Stop Docker Desktop (if install) +2. Run the `podman-mac-helper` binary: + + ```sh + sudo podman-mac-helper install + ``` + + for additional options please run the command: + + ```sh + sudo podman-mac-helper install --help + ``` + +3. Restart the Podman machine (the default Docker socket path will be recreated and Podman will emulate it) + +**On Linux / Windows:** + +1. Stop Docker Desktop (if installed) +2. Restart the Podman machine (the default Docker socket path will be recreated and Podman will emulate it) + +_Note:_ If Docker Desktop is started again, it will automatically re-alias the default Docker socket location and the Podman compatibilty warning will re-appear.