Jinwoo Hwang created GEODE-10518:
------------------------------------
Summary: Documentation Updates for Jakarta EE 10 Migration
Key: GEODE-10518
URL: https://issues.apache.org/jira/browse/GEODE-10518
Project: Geode
Issue Type: Improvement
Reporter: Jinwoo Hwang
Assignee: Jinwoo Hwang
Fix For: 2.1.0
h2. Summary
The current Docker-based documentation preview environment fails to build on
ARM64 architectures, preventing contributors using modern platforms from
previewing Apache Geode documentation locally.
h2. Description
h3. Problem Statement
The current Docker-based documentation preview environment fails to build on
ARM64 architectures, preventing contributors using modern platforms from
previewing Apache Geode documentation locally. This creates a significant
barrier to documentation contributions and limits the diversity of platforms
that can be used for development.
h3. Platforms Affected
The issue impacts an increasingly large segment of the contributor base:
*Apple Silicon Macs:*
* MacBook Pro M1/M2/M3/M4
* MacBook Air M1/M2/M3
* Mac Mini M1/M2/M3
* iMac M1/M3/M4
* Mac Studio M1 Max/Ultra, M2 Max/Ultra
*Cloud Platforms:*
* AWS Graviton (EC2 instances: t4g, m6g, c6g, r6g families)
* Azure ARM-based VMs
* Oracle Cloud Ampere instances
*Other ARM64 Systems:*
* Linux workstations with ARM64 processors
* Development containers on ARM64 hosts
* Raspberry Pi 4/5 (64-bit OS)
h3. Current Behavior
When attempting to build the documentation preview Docker image on ARM64
systems:
{code:bash}
cd dev-tools/docker/docs
./preview-user-guide.sh
{code}
The build fails during Ruby gem installation with errors similar to:
{noformat}
Building native extensions. This could take a while...
ERROR: Error installing libv8:
ERROR: Failed to build gem native extension.
libv8 requires python 2 to be installed in order to build
Gem::Ext::BuildError: ERROR: Failed to build gem native extension
{noformat}
Or linker errors on macOS:
{noformat}
ld: Assertion failed: (targetAtom != NULL), function Fixup, file ld.hpp, line
1094.
clang++: error: linker command failed with exit code 1
{noformat}
h3. Root Cause Analysis
The documentation build system uses Bookbinder, a Ruby-based static site
generator that has the following dependency chain:
{noformat}
bookbindery (10.1.18)
└── therubyracer (0.12.3)
└── libv8 (3.16.14.19)
└── V8 JavaScript Engine (2013 vintage)
{noformat}
*Technical Issues:*
# *{{libv8}}* gem version {{3.16.14.19}} was released in 2013, predating ARM64
architecture support
# Pre-compiled binaries only exist for x86_64 platforms
({{{}libv8-3.16.14.19-x86_64-linux{}}})
# No pre-compiled ARM64 binaries are available
({{{}libv8-3.16.14.19-arm64-linux{}}} does not exist)
# Source compilation fails due to:
## Incompatible build scripts requiring deprecated Python 2
## V8 source code from 2013 not designed for ARM64 architecture
## Modern ARM64 toolchains incompatible with legacy build system
## Architecture-specific assembly code that doesn't support ARM64
h3. Impact Assessment
h4. Contributor Experience
*Current Friction Points:*
* Contributors with ARM64 systems cannot preview documentation changes locally
* Must rely on CI/CD pipeline builds to see rendered output
* Significantly slower feedback loop for documentation improvements
* Discourages documentation contributions from affected platforms
* Creates inequality in contributor experience based on hardware architecture
h4. Market Trends
The impact is growing as ARM64 adoption accelerates:
*Apple Silicon Market Share:*
* 100% of new Macs sold since November 2020 are ARM64-based
* Estimated 40%+ of active Mac developer base on Apple Silicon (as of 2024)
* Trend continuing with all future Mac releases
*Cloud Infrastructure:*
* AWS Graviton instances offer 40% better price/performance ratio
* Many organizations migrating to ARM64 cloud instances
* CI/CD systems increasingly using ARM64 runners for cost savings
*Developer Preferences:*
* New developers joining the project are more likely to have ARM64 systems
* ARM64 adoption in developer community expected to exceed 50% by 2026
h3. Scope of Issue
h4. Files Affected
The issue is isolated to the documentation preview tooling:
{noformat}
dev-tools/docker/docs/
├── Dockerfile # Base image platform not specified
├── preview-user-guide.sh # Docker commands lack platform specification
└── README.md # No ARM64 compatibility notes
{noformat}
h4. User Workflows Impacted
# *Local Documentation Preview:* Primary use case - completely broken
# *Documentation Development:* Cannot iterate quickly on doc changes
# *Contributor Onboarding:* New contributors on ARM64 hit immediate roadblock
# *Documentation Reviews:* Reviewers on ARM64 cannot verify changes locally
h4. Workarounds Currently Required
Contributors on ARM64 platforms must resort to:
*Option 1: Wait for CI/CD*
* Push changes to remote branch
* Wait for CI pipeline to build documentation
* View in CI artifacts or deployed preview
* Iteration time: 10-30 minutes per change
*Option 2: Use Remote x86_64 System*
* SSH to x86_64 server or VM
* Set up complete development environment remotely
* Increases complexity and resource requirements
*Option 3: Run x86_64 VM Locally*
* VMware/Parallels/UTM virtual machine
* Resource intensive (requires 4-8GB RAM for VM)
* Nested virtualization performance penalty
* Additional licensing costs (for commercial VM software)
*Option 4: Read Raw Markdown*
* No styling, navigation, or final rendering
* Cannot verify cross-references or generated content
* Unsuitable for quality assurance
----
h2. Benefits of Fixing This Issue
h3. Improved Contributor Inclusivity
* *Removes barrier to entry* for ARM64 users wanting to contribute
documentation
* *Levels the playing field* - all contributors have same local preview
capabilities
* *Encourages participation* from diverse hardware platforms
* *Reduces frustration* for new contributors encountering immediate technical
blockers
h3. Faster Documentation Iteration
* *Immediate feedback* on documentation changes (seconds vs. minutes)
* *Increased productivity* with quick preview-edit-preview cycles
* *Better quality* documentation through easier local testing
* *Reduced CI load* from fewer "preview only" commits
h3. Future-Proofing
* *Aligns with industry trends* toward ARM64 adoption
* *Prepares for majority-ARM64 future* in developer ecosystem
* *Reduces technical debt* before problem impacts more contributors
* *Demonstrates project modernization* and attention to contributor experience
h3. Cost Efficiency
* *Lower cloud costs* for contributors using ARM64 cloud instances
* *Better resource utilization* - no need for x86_64 VMs or remote systems
* *Reduced mental overhead* - one consistent workflow across platforms
h3. Community Growth
* *Attracts new contributors* who might otherwise be turned away
* *Retains existing contributors* who upgrade to ARM64 hardware
* *Improves project reputation* as being contributor-friendly
* *Demonstrates commitment* to modern development practices
----
h2. Reproduction Steps
h3. Environment
* *Platform:* ARM64 (Apple Silicon Mac, AWS Graviton, or ARM64 Linux)
* *OS:* macOS 14+ or Linux (Ubuntu 22.04+)
* *Docker:* Docker Desktop 4.0+ (Mac) or Docker Engine 20.10+ (Linux)
* *Architecture:* {{uname -m}} returns {{arm64}} or {{aarch64}}
h3. Steps to Reproduce
{code:bash}
# 1. Clone Apache Geode repository
git clone https://github.com/apache/geode.git
cd geode
# 2. Navigate to documentation Docker setup
cd dev-tools/docker/docs
# 3. Attempt to run preview script
./preview-user-guide.sh
{code}
h3. Expected Result
* Docker image builds successfully
* Documentation is compiled by Bookbinder
* Web server starts on port 9292
* Documentation is accessible at {{[http://localhost:9292/docs/guide/115/]}}
h3. Actual Result
Build fails during {{libv8}} gem installation with native extension compilation
errors.
*Error output includes:*
{noformat}
ERROR: Error installing libv8:
ERROR: Failed to build gem native extension.
/usr/local/bundle/gems/libv8-3.16.14.19/ext/libv8/builder.rb:86:in
`setup_python!':
libv8 requires python 2 to be installed in order to build (RuntimeError)
{noformat}
And/or:
{noformat}
ld: Assertion failed: (targetAtom != NULL)
clang++: error: linker command failed with exit code 1
make: *** [preparser] Error 1
{noformat}
----
h2. Additional Context
h3. Related Technologies
*Docker Multi-Platform Support:*
Docker supports building and running containers for different architectures
through:
* {{--platform}} flag for explicit architecture specification
* QEMU emulation for cross-architecture execution
* BuildKit multi-platform builds
*Ruby Gem Ecosystem:*
* RubyGems supports platform-specific binary gems
* Native extensions require compilation for each platform
* Pre-compiled binaries significantly speed up installation
* Legacy gems may not have ARM64 binaries available
h3. Dependency Analysis
*Gem Versions in Use:*
{noformat}
bookbindery: 10.1.18 (last updated 2019)
therubyracer: 0.12.3 (last updated 2016, unmaintained)
libv8: 3.16.14.19 (last updated 2013, V8 from Chrome 28)
{noformat}
*Available Pre-compiled Platforms:*
{noformat}
✓ libv8-3.16.14.19-x86_64-linux
✓ libv8-3.16.14.19-x86_64-darwin
✓ libv8-3.16.14.19-x86-linux
✗ libv8-3.16.14.19-arm64-linux (does not exist)
✗ libv8-3.16.14.19-aarch64-linux (does not exist)
{noformat}
h3. Alternatives Considered (for context only)
This section documents options that were considered but are not part of the
proposed solution:
*Alternative A: Native Ruby Installation*
* Requires local Ruby 2.6.x installation
* Requires Python 2 installation
* Requires build tools (gcc, make, etc.)
* Still fails to compile {{libv8}} on ARM64
* Not viable on ARM64 platforms
*Alternative B: Update to Modern Gems*
* Would require replacing {{therubyracer}} with {{mini_racer}}
* Would require updating {{bookbindery}} or replacing with modern tool
* Large scope - affects entire documentation toolchain
* Risk of breaking existing documentation builds
* Separate major effort beyond this issue's scope
*Alternative C: Use Remote x86_64 Systems*
* Does not solve the local preview problem
* Adds complexity and resource requirements
* Not a real fix, just a workaround
----
h2. Environment Details
h3. Confirmed Failing Platforms
*Tested and Confirmed Failing:*
* macOS 14.x on Apple M1/M2/M3 (arm64)
* Ubuntu 22.04 on AWS Graviton t4g instances (aarch64)
* Debian 12 on ARM64 (aarch64)
h3. Working Platforms
*Known Working (for comparison):*
* macOS on Intel processors (x86_64)
* Ubuntu/Debian/RHEL on Intel/AMD processors (x86_64)
* Windows 11 on Intel/AMD with WSL2 (x86_64)
----
h2. Success Criteria
When this issue is resolved, the following should be true:
# *Build Success:* Documentation preview Docker image builds without errors on
ARM64 platforms
# *Functionality:* Preview server starts and serves documentation on ARM64
systems
# *Performance:* Build and runtime performance is acceptable (within 2x of
native)
# *Compatibility:* Existing x86_64 platforms continue to work without
regression
# *Documentation:* Build process and platform requirements are clearly
documented
----
h2. References
h3. External Links
* [Docker Multi-Platform
Builds|https://docs.docker.com/build/building/multi-platform/]
* [RubyGems Platform Support|https://guides.rubygems.org/platforms/]
* [libv8 Gem on RubyGems|https://rubygems.org/gems/libv8/versions/3.16.14.19]
* [Bookbinder Documentation|https://github.com/pivotal-cf/bookbinder]
* [Apple Silicon Migration
Guide|https://developer.apple.com/documentation/apple-silicon]
h3. Related Community Discussions
* Apache Geode mailing list discussions about ARM64 support
* GitHub Issues: Search for "ARM64", "Apple Silicon", "M1" in apache/geode
repository
* Developer community feedback on documentation workflow pain points
h3. Market Data
* [Apple Silicon Mac Sales Data|https://www.apple.com/newsroom/]
* [AWS Graviton Performance Analysis|https://aws.amazon.com/ec2/graviton/]
* [ARM Architecture Adoption
Trends|https://www.arm.com/markets/computing-infrastructure]
----
h2. Notes
h3. Constraints
* Must maintain backward compatibility with existing x86_64 workflows
* Should not require changes to {{geode-docs}} content or structure
* Should not require updates to Ruby gem versions or dependencies
* Must work with existing {{bookbindery}} toolchain
* Should not introduce significant performance regressions
h3. Testing Requirements
* Test on multiple ARM64 platforms (macOS, Linux)
* Verify no regression on x86_64 platforms
* Measure build time and runtime performance
* Validate documentation renders correctly
* Test with both script and manual Docker commands
h3. Documentation Requirements
* Update {{README.md}} in {{dev-tools/docker/docs}} with platform
compatibility information
* Add troubleshooting section for common ARM64 issues
* Document performance expectations on emulated platforms
* Include examples for both x86_64 and ARM64 platforms
----
h2. Affected Stakeholders
* *Documentation Contributors:* Primary beneficiaries, gain ability to preview
locally
* *Project Maintainers:* Reduced support burden for documentation preview
issues
* *New Contributors:* Smoother onboarding experience, fewer technical barriers
* *Review Team:* More reviewers can verify documentation changes locally
* *Community Members:* Improved documentation quality through easier
contributions
----
h2. Timeline Considerations
h3. Urgency Factors
* ARM64 adoption rate accelerating (40%+ of Mac developers as of 2025)
* Problem affects increasing percentage of contributor base over time
* Simple fix available (platform specification in Docker commands)
* Low risk of introducing regressions
h3. Impact If Not Fixed
* Continued exclusion of ARM64 users from documentation contributions
* Growing technical debt as ARM64 becomes dominant platform
* Negative perception of project as not contributor-friendly
* Lost documentation contributions from affected users
* Increased support burden answering "why doesn't this work on my Mac?"
----
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
