geode icon indicating copy to clipboard operation
geode copied to clipboard

[GEODE-10513] Fix ARM64 documentation preview with platform-specific Docker build

Open JinwooHwang opened this issue 2 weeks ago • 0 comments

Overview

This PR fixes documentation preview failures on ARM64/Apple Silicon machines by explicitly specifying the AMD64 platform for Docker builds.

Problem

The documentation preview script failed on ARM64 machines (Apple Silicon Macs) because:

  • The ruby:2.6.8 Docker image has limited or no native ARM64 support
  • Docker was attempting to use native ARM64 images, causing compatibility issues
  • Users on Apple Silicon could not preview documentation locally

Solution

Explicitly specify --platform=linux/amd64 for both Docker build and run commands to:

  • Force Docker to use AMD64 architecture via emulation (Rosetta 2)
  • Ensure consistent behavior across different host architectures
  • Maintain compatibility with the existing Ruby 2.6.8 image

Changes

dev-tools/docker/docs/Dockerfile

  • Added --platform=linux/amd64 to the FROM ruby:2.6.8 instruction

dev-tools/docker/docs/preview-user-guide.sh

  • Added --platform linux/amd64 flag to docker build command
  • Added --platform linux/amd64 flag to docker run command

Testing

  • Verified documentation preview works on ARM64 (Apple Silicon) machines
  • Confirmed backward compatibility with AMD64 machines
  • Successfully builds and runs the documentation preview container

Impact

  • Low risk: Changes are isolated to documentation tooling
  • No production impact: Only affects local development documentation preview
  • Improves developer experience: Enables ARM64 users to preview docs locally

Related Issues

  • Fixes GEODE-10513

Checklist:

  • [x] Changes are isolated to documentation tooling
  • [x] Tested on ARM64 architecture
  • [x] Backward compatible with AMD64
  • [x] No impact on production code

For all changes, please confirm:

  • [x] Is there a JIRA ticket associated with this PR? Is it referenced in the commit message?
  • [x] Has your PR been rebased against the latest commit within the target branch (typically develop)?
  • [x] Is your initial contribution a single, squashed commit?
  • [x] Does gradlew build run cleanly?
  • [ ] Have you written or updated unit tests to verify your changes?
  • [ ] If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under ASF 2.0?

JinwooHwang avatar Dec 08 '25 13:12 JinwooHwang