This is an automated email from the ASF dual-hosted git repository.
liurenjie1024 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 5d3152f11 site: merge container docs and add a section about docker
desktop (#2091)
5d3152f11 is described below
commit 5d3152f11ec8fbb210a48d1ce490bc1ea73b6ca0
Author: Kevin Liu <[email protected]>
AuthorDate: Thu Jan 29 19:06:12 2026 -0500
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?
---
CONTRIBUTING.md | 5 +-
website/src/SUMMARY.md | 3 +-
.../reference/{podman.md => container-runtimes.md} | 93 +++++++++++++++++-----
website/src/reference/orbstack.md | 39 ---------
4 files changed, 77 insertions(+), 63 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0d05c3dda..d1a736ed1 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/website/src/SUMMARY.md b/website/src/SUMMARY.md
index da82364f5..dfe0043ff 100644
--- a/website/src/SUMMARY.md
+++ b/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)
diff --git a/website/src/reference/podman.md
b/website/src/reference/container-runtimes.md
similarity index 53%
rename from website/src/reference/podman.md
rename to website/src/reference/container-runtimes.md
index eee93a0b3..7b4ac3851 100644
--- a/website/src/reference/podman.md
+++ b/website/src/reference/container-runtimes.md
@@ -17,18 +17,74 @@
~ 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 ] || \
@@ -36,7 +92,7 @@ Iceberg-rust does not require containerization, except for
integration tests, wh
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
[...]
+### 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"
- ```
diff --git a/website/src/reference/orbstack.md
b/website/src/reference/orbstack.md
deleted file mode 100644
index cbd656635..000000000
--- a/website/src/reference/orbstack.md
+++ /dev/null
@@ -1,39 +0,0 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
--->
-
-# OrbStack as a docker alternative on macOS
-1. Install OrbStack by downloading [installer](https://orbstack.dev/download)
or using Homebrew.
- ```shell
- brew install orbstack
- ```
-
-2. Migrate Docker data
- ```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`.
-
- ```
- {
- "registry-mirrors": ["<mirror_addr>"]
- }
- ```
