site: merge container docs and add a section about docker desktop (#2091)

## Which issue does this PR close?

- Closes #719

## What changes are included in this PR?
With all the recent changes to our test setup and containers (#2071,
#2074, #2078), `make test` now works with Docker Desktop. I tested this
locally! (requires #2090)

This PR updates our documentation to reflect that docker desktop works.
We used to have 2 pages for containers, 1 for orbstack another for
podman. I merged them together and also added a section for Docker
Desktop

Preview: 
<img width="1522" height="1010" alt="Screenshot 2026-01-29 at 11 35
55 AM"
src="https://github.com/user-attachments/assets/567df138-a15b-4e2e-a91e-2166b4f93f5a"
/>

## Are these changes tested?

Author: kevinjqliu

CONTRIBUTING.md

@@ -101,10 +101,7 @@ cargo 1.69.0 (6e9a83356 2023-04-12)
 
 #### Install Docker or Podman
 
-Currently, iceberg-rust uses Docker to set up environment for integration tests. Native Docker has some limitations, please check (https://github.com/apache/iceberg-rust/pull/748). Please use Orbstack or Podman.
-
-For MacOS users, you can install [OrbStack as a docker alternative](website/src/reference/orbstack.md).
-For Podman users, refer to [Using Podman instead of Docker](website/src/reference/podman.md)
+Currently, iceberg-rust uses Docker to set up environment for integration tests. See [Container Runtimes](website/src/reference/container-runtimes.md) for setup instructions.
 
 ## Build
 

website/src/SUMMARY.md

@@ -32,6 +32,5 @@
 
 # Reference
 
-- [Using Podman instead of Docker](./reference/podman.md)
-- [OrbStack as a docker alternative](./reference/orbstack.md)
+- [Container Runtimes](./reference/container-runtimes.md)
 - [Setup GPG key](./reference/setup_gpg.md)

website/src/reference/podman.md …site/src/reference/container-runtimes.mdwebsite/src/reference/podman.md renamed to website/src/reference/container-runtimes.md website/src/reference/podman.md renamed to website/src/reference/container-runtimes.md

@@ -17,26 +17,82 @@
   ~ under the License.
 -->
 
-# Using Podman instead of Docker
+# Container Runtimes
 
-Iceberg-rust does not require containerization, except for integration tests, where "docker" and "docker-compose" are used to start containers for minio and various catalogs. Below instructions setup "rootful podman" and docker's official docker-compose plugin to run integration tests as an alternative to docker or Orbstack.
+Iceberg-rust uses containers for integration tests, where `docker` and `docker compose` start containers for MinIO and various catalogs. You can use any of the following container runtimes.
+
+## Docker Desktop
+
+[Docker Desktop](https://www.docker.com/products/docker-desktop/) is available for macOS, Windows, and Linux.
+
+1. Install Docker Desktop by downloading the [installer](https://www.docker.com/products/docker-desktop/) or using Homebrew on macOS.
+    ```shell
+    brew install --cask docker
+    ```
+
+2. Launch Docker Desktop and complete the setup.
+
+3. Verify the installation.
+    ```shell
+    docker --version
+    docker compose version
+    ```
+
+4. Try some integration tests!
+    ```shell
+    make test
+    ```
+
+## OrbStack (macOS)
+
+[OrbStack](https://orbstack.dev/) is a lightweight alternative to Docker Desktop on macOS.
+
+1. Install OrbStack by downloading the [installer](https://orbstack.dev/download) or using Homebrew.
+    ```shell
+    brew install orbstack
+    ```
+   
+2. Migrate Docker data (if switching from Docker Desktop).
+    ```shell
+    orb migrate docker
+    ```
+   
+3. (Optional) Add registry mirrors.
+   
+    You can edit the config directly at `~/.orbstack/config/docker.json` and restart the engine with `orb restart docker`.
+   
+    ```json
+    {
+        "registry-mirrors": ["<mirror_addr>"]
+    }
+    ```
+
+4. Try some integration tests!
+    ```shell
+    make test
+    ```
+
+## Podman
+
+[Podman](https://podman.io/) is a daemonless container engine. The instructions below set up "rootful podman" with docker's official docker-compose plugin.
 
 1. Have podman v4 or newer.
     ```shell
     $ podman --version
     podman version 4.9.4-rhel
     ```
+
 2. Create a docker wrapper script:
    
-  * Create a fresh `/usr/bin/docker` file and add the below contents:
+    Create a fresh `/usr/bin/docker` file and add the below contents:
     ```bash
     #!/bin/sh
     [ -e /etc/containers/nodocker ] || \
     echo "Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg." >&2
     exec sudo /usr/bin/podman "$@"
     ```
 
-  * Set new `/usr/bin/docker` file to executable.
+    Set new `/usr/bin/docker` file to executable.
     ```shell
     sudo chmod +x /usr/bin/docker
     ```
@@ -78,23 +134,24 @@ Iceberg-rust does not require containerization, except for integration tests, wh
     cargo test -p iceberg --test file_io_s3_test
     ```
 
-# References
+### Note on rootless containers
 
-* <https://docs.docker.com/compose/install/linux>
-* <https://www.redhat.com/sysadmin/podman-docker-compose>
+As of podman v4, ["To be succinct and simple, when running rootless containers, the container itself does not have an IP address"](https://www.redhat.com/sysadmin/container-ip-address-podman). This causes issues with iceberg-rust's integration tests, which rely upon IP-addressable containers via docker-compose. As a result, podman "rootful" containers are required to ensure containers have IP addresses.
+
+### Podman troubleshooting
+
+**Error:** `short-name "apache/iceberg-rest-fixture" did not resolve to an alias and no unqualified-search registries are defined in "/etc/containers/registries.conf"`
 
-# Note on rootless containers
+**Fix:** Add or modify the `/etc/containers/registries.conf` file:
+```toml
+[[registry]]
+prefix = "docker.io"
+location = "docker.io"
+```
 
-As of podman v4, ["To be succinct and simple, when running rootless containers, the container itself does not have an IP address"](https://www.redhat.com/sysadmin/container-ip-address-podman) This causes issues with iceberg-rust's integration tests, which rely upon ip-addressable containers via docker-compose. As a result, podman "rootful" containers are required throughout to ensure containers have IP addresses. Perhaps as a future work or with updates to default podman networking, the need for "rootful" podman containers can be eliminated.
+### Podman references
 
+* <https://docs.docker.com/compose/install/linux>
+* <https://www.redhat.com/sysadmin/podman-docker-compose>
 * <https://www.redhat.com/sysadmin/container-ip-address-podman>
 * <https://github.com/containers/podman/blob/main/docs/tutorials/basic_networking.md>
-
-# Debugging Note:
- - Fix for error: `Error: short-name "apache/iceberg-rest-fixture" did not resolve to an alias and no unqualified-search registries are defined in "/etc/containers/registries.conf"`
-    - Add or modify the `/etc/containers/registries.conf` file:
-    ```toml
-    [[registry]]
-    prefix = "docker.io"
-    location = "docker.io"
-    ```