mirror of
https://github.com/podman-desktop/podman-desktop
synced 2026-04-21 17:47:22 +00:00
docs(website): updated the docker compatibility section (#9408)
Signed-off-by: Shipra Singh <shipsing@redhat.com>
This commit is contained in:
Shipra Singh
GitHub
parent
0fed5b9af2
commit
eb099860e9
10 changed files with 67 additions and 268 deletions
|
|
@ -117,7 +117,7 @@ The documentation had many editorial reviews, and new content.
|
|||
- [Revamped installation introduction](/docs/installation)
|
||||
- [Reorganized Linux installation](/docs/installation/linux-install)
|
||||
- [Installing Podman Desktop on Windows in a restricted environment](/docs/proxy
|
||||
- [Fixed documentation on `podman-mac-helper` setup](/docs/migrating-from-docker/using-podman-mac-helper)
|
||||
- Fixed documentation on `podman-mac-helper` setup
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,77 +0,0 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
title: Emulating Docker CLI with Podman
|
||||
description: Emulation Docker CLI with Podman can make it easier to migrate from Docker to Podman, as it allows you to continue using familiar Docker commands while taking advantage of the benefits of Podman.
|
||||
keywords: [podman desktop, podman, containers]
|
||||
tags: [migrating-from-docker]
|
||||
---
|
||||
|
||||
# Emulating Docker CLI with Podman
|
||||
|
||||
Consider emulating Docker CLI with Podman to migrate transparently to Podman.
|
||||
|
||||
- Continue using familiar Docker commands.
|
||||
- Take advantage of the benefits of Podman on macOS.
|
||||
- Your tools, such as [Maven](https://maven.apache.org/) or [Testcontainers](https://www.testcontainers.com/), communicate with Podman without reconfiguration.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Podman
|
||||
|
||||
### Linux / macOS
|
||||
|
||||
#### Procedure
|
||||
|
||||
1. Create a `/usr/local/bin/docker` script:
|
||||
|
||||
```shell
|
||||
#!/bin/sh
|
||||
[ -e /etc/containers/nodocker ] || \
|
||||
echo "Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg." >&2
|
||||
exec podman "$@"
|
||||
```
|
||||
|
||||
2. (Optional) Create an empty `/etc/containers/nodocker` file to avoid the `Emulate Docker CLI using podman.` message when running the script.
|
||||
|
||||
```shell-session
|
||||
# touch /etc/containers/nodocker
|
||||
```
|
||||
|
||||
3. Make the script executable:
|
||||
|
||||
```shell-session
|
||||
# chmod +x /usr/local/bin/docker
|
||||
```
|
||||
|
||||
#### Verification
|
||||
|
||||
- Use the `docker` script to run commands.
|
||||
Example:
|
||||
|
||||
```shell-session
|
||||
$ docker run -it docker.io/hello-world
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
#### Procedure
|
||||
|
||||
1. Create a `C:\Program Files\docker\bin\docker.bat` script:
|
||||
|
||||
```batch
|
||||
@echo off
|
||||
echo Emulate Docker CLI using podman. <- remove this line to avoid the `Emulate Docker CLI using podman.` message when running the script.
|
||||
podman %*
|
||||
```
|
||||
|
||||
2. Add C:\Program Files\docker\bin to the SYSTEM/USER environment variable PATH
|
||||
3. Close all cmd and powershell instances.
|
||||
|
||||
#### Verification
|
||||
|
||||
- Use the `docker` script to run commands.
|
||||
Example:
|
||||
|
||||
```PowerShell
|
||||
$ docker run -it docker.io/hello-world
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 238 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 183 KiB |
|
|
@ -8,10 +8,10 @@ tags: [migrating-from-docker]
|
|||
|
||||
# Migration from Docker to Podman Desktop
|
||||
|
||||
When you have used Docker in the past, you can continue using familiar workflows with Podman Desktop:
|
||||
If you have used Docker in the past, you can continue using familiar workflows with the Docker compatibility feature of Podman Desktop.
|
||||
|
||||
Docker compatibility is a way to configure an environment in which you can run your Docker applications, commands, and tools on a Podman engine without reconfiguration. It encompasses two stages:
|
||||
- [Import your saved containers](/docs/migrating-from-docker/importing-saved-containers) into Podman Desktop using CLI.
|
||||
- [Access the Docker Compatibility settings](/docs/migrating-from-docker/managing-docker-compatibility) to configure a Docker-compatible environment based on your needs.
|
||||
|
||||
|
||||
- [Importing saved containers to Podman to continue using familiar containers](/docs/migrating-from-docker/importing-saved-containers)
|
||||
- [Using the `DOCKER_HOST` environment variable to let your tools communicate directly with the Podman socket](/docs/migrating-from-docker/using-the-docker_host-environment-variable)
|
||||
- [Using the `podman-mac-helper` tool on macOS to redirect the Docker socket to the Podman socket](/docs/migrating-from-docker/using-podman-mac-helper)
|
||||
- [Emulating Docker CLI with Podman to continue using tools depending on the Docker CLI](/docs/migrating-from-docker/emulating-docker-cli-with-podman)
|
||||
- [Verifying that your tools are using Podman](/docs/migrating-from-docker/verifying-your-tools-are-using-podman)
|
||||
|
|
|
|||
|
|
@ -22,7 +22,8 @@ As a developer, you can:
|
|||
|
||||
- Use all Docker tools, including CLI, with the Podman engine without any reconfiguration. These tools connect to the default Podman socket, thereby enabling you to use all Docker commands with Podman. For example, you can run the `docker run` command on the Podman engine to start a container.
|
||||
|
||||
- By default, third-party Docker tool compatibility is enabled on macOS.
|
||||
- On macOS, the **Third-Party Docker Tool Compatibility** setting is enabled by default.
|
||||
- On Windows and Linux, the **Third-Party Docker Tool Compatibility** setting is not available. You can [use the `DOCKER_HOST` environment variable](/docs/migrating-from-docker/using-the-docker_host-environment-variable) to let your tools communicate directly with the Podman socket.
|
||||
|
||||
- Use the Podman CLI to run Compose applications by installing and setting up the [Compose extension](/docs/compose). For example, you can run the `docker compose up` command on the Podman engine to start your Compose v2 application. Also, ensure to place your Docker Compose file in a working directory, such as your home directory.
|
||||
|
||||
|
|
@ -40,9 +41,10 @@ As a developer, you can:
|
|||
#### Procedure
|
||||
|
||||
1. Go to **Settings > Docker Compatibility**.
|
||||
2. **Socket Mapping Status** setting: View the socket mapping status to check whether the socket is reachable.
|
||||
3. **Podman Compose CLI Support** setting: Check whether the Podman Compose CLI is supported. If not, use the **Install** icon to install and set up the Podman CLI.
|
||||
4. **Docker CLI Context** setting: Select a socket context to work with from the dropdown list.
|
||||
2. **System socket status** setting: View the socket mapping status to check whether the socket is reachable.
|
||||
3. **Docker CLI Context** setting: Select a socket context to work with from the dropdown list.
|
||||
4. **Podman Compose CLI Support** setting: Check whether the Podman Compose CLI is supported. If not, use the **Setup...** button to install and set up the CLI.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="macOS" label="macOS" className="markdown">
|
||||
|
|
@ -50,11 +52,11 @@ As a developer, you can:
|
|||
#### Procedure
|
||||
|
||||
1. Go to **Settings > Docker Compatibility**.
|
||||
2. **Socket Mapping Status** setting: View the socket mapping status to check whether the socket is reachable.
|
||||
3. **Third-Party Docker Tool Compatibility** setting: Customize the setting, if needed. When enabled, you can use third-party Docker tools with Podman.
|
||||
4. **Podman Compose CLI Support** setting: Check whether the Podman Compose CLI is supported. If not, use the **Install** icon to install and set up the Podman CLI.
|
||||
5. **Docker CLI Context** setting: Select a socket context to work with from the dropdown list.
|
||||
|
||||
2. **System socket status** setting: View the socket mapping status to check whether the socket is reachable.
|
||||
3. **Docker CLI Context** setting: Select a socket context to work with from the dropdown list.
|
||||
4. **Podman Compose CLI Support** setting: Check whether the Podman Compose CLI is supported. If not, use the **Setup...** button to install and set up the CLI.
|
||||
5. **Third-Party Docker Tool Compatibility** setting: Customize the setting, if needed. When enabled, you can use third-party Docker tools with Podman.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,78 +0,0 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
title: Using `podman-mac-helper` on macOS
|
||||
description: Using the `podman-mac-helper` tool can make it easier to migrate from Docker to Podman on macOS, as it allows you to continue using familiar Docker commands while taking advantage of the benefits of Podman.
|
||||
keywords: [podman desktop, podman, containers, migrating, docker, macos]
|
||||
tags: [migrating-from-docker, mac0S]
|
||||
---
|
||||
|
||||
# Using the `podman-mac-helper` tool to migrate from Docker to Podman on macOS
|
||||
|
||||
Consider using `podman-mac-helper` to migrate transparently to Podman on macOS.
|
||||
|
||||
- Continue using familiar Docker commands.
|
||||
- Take advantage of the benefits of Podman on macOS.
|
||||
- Your tools, such as [Maven](https://maven.apache.org/) or [Testcontainers](https://www.testcontainers.com/), communicate with Podman without reconfiguration.
|
||||
|
||||
The `podman-mac-helper` tool provides a compatibility layer that allows you to use most Docker commands with Podman on macOS.
|
||||
The service redirects `/var/run/docker` to the fixed user-assigned UNIX socket location.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- macOS
|
||||
- [Podman](/docs/installation/macos-install)
|
||||
- Docker service is [paused](https://docs.docker.com/desktop/use-desktop/pause/) and [_Start Docker Desktop when you log in_ is disabled](https://docs.docker.com/desktop/settings/mac/), or Docker is [uninstalled](https://docs.docker.com/desktop/uninstall/).
|
||||
|
||||
#### Procedure
|
||||
|
||||
1. Set up the `podman-mac-helper` service: run the command in a terminal:
|
||||
|
||||
```shell-session
|
||||
sudo podman-mac-helper install
|
||||
```
|
||||
|
||||
1. Restart your Podman machine: go to **<Icon icon="fa-solid fa-cog" size="lg" /> Settings > Resources**, and in the Podman tile, click <Icon icon="fa-solid fa-repeat" size="lg" />.
|
||||
|
||||
#### Verification
|
||||
|
||||
1. The Docker socket is a symbolic link for the Podman socket:
|
||||
|
||||
```shell-session
|
||||
$ ls -la /var/run/docker.sock
|
||||
```
|
||||
|
||||
The output points to a `podman.sock` file such as:
|
||||
|
||||
```shell-session
|
||||
/var/run/docker.sock -> /Users/username/.local/share/containers/podman/machine/podman.sock
|
||||
```
|
||||
|
||||
1. When you query the Docker socket, you receive replies from Podman rather than Docker.
|
||||
|
||||
For instance, this command outputs Podman version rather that Docker version:
|
||||
|
||||
```shell-session
|
||||
$ curl -s --unix-socket /var/run/docker.sock "http://v1.41/info" | jq -r .ServerVersion
|
||||
```
|
||||
|
||||
1. Your tools communicating to the Docker socket, such as [Maven](https://maven.apache.org/) or [Testcontainers](https://www.testcontainers.com/), communicate with Podman without reconfiguration.
|
||||
|
||||
1. (Optionally, if the `docker` CLI is installed) The docker CLI context is set to the default value `unix:///var/run/docker.sock`:
|
||||
|
||||
```shell-session
|
||||
$ docker context list
|
||||
NAME TYPE DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR
|
||||
default * moby Current DOCKER_HOST based configuration unix:///var/run/docker.sock
|
||||
```
|
||||
|
||||
1. (Optionally, if the `docker` CLI is installed) The `docker` CLI communicates with the Podman socket.
|
||||
|
||||
Therefore this command outputs Podman version rather that Docker version:
|
||||
|
||||
```shell-session
|
||||
$ docker info --format=json | jq -r .ServerVersion
|
||||
```
|
||||
|
||||
#### Additional resources
|
||||
|
||||
- [`podman-mac-helper` source](https://github.com/containers/podman/tree/main/cmd/podman-mac-helper)
|
||||
|
|
@ -17,6 +17,21 @@ Consider using the `DOCKER_HOST` environment variable to migrate transparently f
|
|||
- Take advantage of the benefits of Podman.
|
||||
- Your tools, such as [Gradle](https://gradle.org/) or [Testcontainers](https://www.testcontainers.com/), communicate with Podman without reconfiguration.
|
||||
|
||||
Using the `DOCKER_HOST` environment variable, you can connect your Docker CLI to the Podman socket.
|
||||
|
||||
:::note
|
||||
|
||||
Alternatively, you can add a `podman` context by using the `docker context create` command.
|
||||
- For example, set the value of the context in this pattern on a macOS machine:
|
||||
|
||||
`docker context create podman --docker "host=unix://$HOME.local/share/containers/podman/machine/podman.sock"`
|
||||
|
||||
Where, the path specified after the `unix://` scheme denotes the `DOCKER_HOST` value.
|
||||
|
||||
Then, you can run the `docker context use podman` command to switch to that context. This way you can use your Docker CLI to run your tasks on a remote Podman engine. When you run the `docker ps` command, it queries the Podman socket specified in the current context.
|
||||
|
||||
:::
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Podman
|
||||
|
|
@ -34,37 +49,42 @@ $ podman machine inspect --format '{{.ConnectionInfo.PodmanPipe.Path}}'
|
|||
|
||||
2. Set the `DOCKER_HOST` environment variable to your Podman pipe location. You'll need to replace back slashes with forward slashes and add the `npipe://` scheme to the path retrieved previously: <!-- markdownlint-disable MD029 -->
|
||||
|
||||
> Example:
|
||||
>
|
||||
> **prefix**podman-pipe
|
||||
>
|
||||
> **npipe://**//./pipe/podman-machine-default
|
||||
> Example:
|
||||
>
|
||||
> **prefix**podman-pipe
|
||||
>
|
||||
> **npipe://**//./pipe/podman-machine-default
|
||||
|
||||
Depending on your terminal emulator of preference there is a little variation between the commands to set a session level environment variable:
|
||||
Depending on your terminal emulator of preference, there is a little variation between the commands to set a session level environment variable:
|
||||
|
||||
##### cmd - Command Prompt
|
||||
##### cmd - Command Prompt
|
||||
|
||||
```cmd
|
||||
set DOCKER_HOST=npipe://<inspect_command_output>
|
||||
```
|
||||
```cmd
|
||||
set DOCKER_HOST=npipe://<inspect_command_output>
|
||||
```
|
||||
|
||||
##### Git Bash
|
||||
##### Git Bash
|
||||
|
||||
```bash
|
||||
export DOCKER_HOST=npipe://<inspect_command_output>
|
||||
```
|
||||
```bash
|
||||
export DOCKER_HOST=npipe://<inspect_command_output>
|
||||
```
|
||||
|
||||
##### Powershell
|
||||
##### Powershell
|
||||
|
||||
Don't miss the quotes on the value or powershell will try to interpret it as a separate command instead of a value.
|
||||
Don't miss the quotes used with the value. Otherwise, powershell will interpret it as a separate command instead of a value.
|
||||
|
||||
```powershell
|
||||
$env:DOCKER_HOST="npipe://<inspect_command_output>"
|
||||
```
|
||||
```powershell
|
||||
$env:DOCKER_HOST="npipe://<inspect_command_output>"
|
||||
```
|
||||
|
||||
Ideally you should set `DOCKER_HOST` at the system or user level environment variables (or even load it in your CL emulator init script of choice)
|
||||
Ideally, you should set `DOCKER_HOST` at the system or user level environment variables (or even load it in your CL emulator init script of choice).
|
||||
|
||||
:::note
|
||||
|
||||
Setting the `DOCKER_HOST` environment variable isn't necessary on Windows because Podman also listens to the default `docker_engine` pipe. But, it might be necessary if you get the following error: **Error: socket of machine is not set**, while trying to use the `podman compose` command.
|
||||
|
||||
:::
|
||||
|
||||
Note: Setting the `DOCKER_HOST` environment variable isn't necessary on Windows since Podman also listens to the default `docker_engine` pipe. But it may be necessary if you get the following error: **Error: socket of machine is not set** while trying to use the podman compose command.
|
||||
</TabItem>
|
||||
<TabItem value="mac" label="macOS">
|
||||
|
||||
|
|
|
|||
|
|
@ -1,76 +0,0 @@
|
|||
---
|
||||
sidebar_position: 6
|
||||
title: Verifying your tools are using Podman
|
||||
description: Verify that your tools are using Podman rather than Docker.
|
||||
keywords: [podman desktop, podman, containers, migrating, docker]
|
||||
tags: [migrating-from-docker]
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Verifying that your tools are using Podman
|
||||
|
||||
When you have configured your host to use Podman rather then Docker, consider verifying your setup works as intended.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Docker service is stopped, or not installed.
|
||||
- [Saved containers are imported to Podman](/docs/migrating-from-docker/importing-saved-containers)
|
||||
- [The `DOCKER_HOST` environment variable is set](/docs/migrating-from-docker/using-the-docker_host-environment-variable)
|
||||
- [On macOS, the `podman-mac-helper` service is running](/docs/migrating-from-docker/using-podman-mac-helper)
|
||||
- [Podman is emulating Docker CLI](/docs/migrating-from-docker/emulating-docker-cli-with-podman)
|
||||
|
||||
#### Procedure
|
||||
|
||||
1. The Docker socket replies successfully for listing all containers:
|
||||
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows">
|
||||
|
||||
```shell-session
|
||||
$ curl --unix-socket npipe:////./pipe/docker_engine "http:/v1.41/containers/json?all=true"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac" label="macOS">
|
||||
|
||||
```shell-session
|
||||
$ curl --unix-socket /var/run/docker.sock "http:/v1.41/containers/json?all=true"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```shell-session
|
||||
$ curl --unix-socket /var/run/docker.sock "http:/v1.41/containers/json?all=true"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
2. Podman commands run successfully when redirected to the Docker socket:
|
||||
|
||||
<Tabs groupId="operating-systems">
|
||||
<TabItem value="win" label="Windows">
|
||||
|
||||
```shell-session
|
||||
$ CONTAINER_HOST=npipe:////./pipe/docker_engine podman ps
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="mac" label="macOS">
|
||||
|
||||
```shell-session
|
||||
$ CONTAINER_HOST=unix:///var/run/docker.sock podman ps
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
```shell-session
|
||||
$ CONTAINER_HOST=unix:///var/run/docker.sock podman ps
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -124,6 +124,14 @@ const config = {
|
|||
'/docs/onboarding/containers/creating-a-podman-machine-with-podman-desktop',
|
||||
],
|
||||
},
|
||||
{
|
||||
to: '/docs/migrating-from-docker/managing-docker-compatibility',
|
||||
from: [
|
||||
'/docs/migrating-from-docker/using-podman-mac-helper',
|
||||
'/docs/migrating-from-docker/emulating-docker-cli-with-podman',
|
||||
'/docs/migrating-from-docker/verifying-your-tools-are-using-podman',
|
||||
],
|
||||
},
|
||||
{
|
||||
to: '/docs/openshift/developer-sandbox',
|
||||
from: [
|
||||
|
|
|
|||
Loading…
Reference in a new issue