Run the Iceberg preview.

What you will run

An Iceberg REST catalog and its storage on one local Linux amd64 host. Port 80 serves both the catalog and Iceberg FileIO. The GUI is not ready for use in this container and is not published.

You need Docker, a free host port 80, and disposable data. This profile creates four sparse 16 GiB disk images; configured disk capacity is not a usable-capacity guarantee. Monitor actual filesystem space. Native Apple Silicon or other arm64 execution is not claimed by this guide.

1. Start with a named volume

docker run -d --name crowdb-iceberg \
  -p 127.0.0.1:80:80 \
  -v crowdb-data:/opt/crowdb/data \
  --stop-timeout 120 \
  crowdb/crowdb-iceberg:0.1.0

Docker creates the named volume if it does not exist. Reuse it only with a compatible, exact image version; this preview does not promise cross-version upgrades. Never attach the same volume to two running containers.

The loopback mapping keeps the endpoint local. Do not publish this HTTP preview directly to the internet. If your host already runs a website on port 80, use a separate evaluation host or configure reachable catalog and FileIO endpoints according to the upstream guide. Merely changing the host port and catalog URL is insufficient.

2. Check startup

docker inspect --format '{{.State.Health.Status}}' crowdb-iceberg

Wait for healthy. A starting state means initialization or recovery may still be in progress. For an unhealthy or exited container, inspect the logs and readiness check:

docker logs --tail 100 crowdb-iceberg
docker exec crowdb-iceberg crowdb-monitor liveness
docker exec crowdb-iceberg crowdb-monitor readiness

Successful probes exit with status zero. An unhealthy Docker health check alone does not restart a container. A Docker restart policy handles container exits; it is not a replacement for investigating the failure.

3. Retrieve your credentials

docker exec crowdb-iceberg crowdb-monitor credentials show --format env

The output includes ICEBERG_URI and ICEBERG_TOKEN, as well as credentials for the optional independent S3 service. Keep the output private. Copy the two Iceberg values into your client’s environment. Do not paste tokens into GitHub issues or a public demo.

The local URI is http://localhost. Use the token generated by your own deployment. Credentials remain the same when the data volume is reused.

4. Write and query with PyIceberg

PyIceberg 0.11.1 is covered by a container test that creates a table, appends Arrow data, scans the saved table, and summarizes it with pandas. The orders walkthrough shows the complete script and expected result.

Use the ICEBERG_URI and ICEBERG_TOKEN printed by your own container. PyIceberg obtains file credentials from the catalog response, so the example does not require a separate S3 endpoint or a manual credential request.

5. Stop, resume, or remove the container

Stop and resume the same container without deleting its data:

docker stop --time 120 crowdb-iceberg
docker start crowdb-iceberg

To remove the container when the evaluation is finished, stop it first:

docker stop --time 120 crowdb-iceberg
docker rm crowdb-iceberg

The named volume crowdb-data remains. These instructions deliberately do not delete it. Stop the container before backing up the whole volume, preserve ownership, private permissions and sparse files, and restore with the exact image version. Copying only disk images is insufficient.

Optional: independent S3 access

The general S3 API is a separate endpoint. Add -p 127.0.0.1:81:81 when creating the container to publish it. Connect to http://localhost:81 using path-style addressing, region us-east-1, and the printed AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.

An S3 upload does not register an Iceberg table. The Iceberg path does not need this extra port.

Limits worth reading before a larger test

Everything runs on one host; this deployment provides no host fault tolerance. Physical reclamation is disabled in this profile, so deleted Iceberg content can continue to occupy space. There is no production guarantee and no supported on-disk upgrade path between versions.

Do not edit bootstrap manifests or secrets to bypass a rejected volume. Use the original image and credentials, and inspect the logs. For restart policy, log rotation, bind-mount permissions, backups, recovery, and crash diagnostics, validate the procedure against the image version you run.

Read the complete Iceberg container manual →