fix(docker): support RPi CM4 compatibility by parameterizing platform

[namdamdoi68-oss]

Summary

This PR resolves issue #2101 where running the default Docker compose setup crashes on older ARMv8-A hardware (such as Raspberry Pi 4 or Raspberry Pi CM4) because ClickHouse and backend images require ARMv8.2-A instruction set.

Solution

Instead of hardcoding any platforms or custom Dockerfiles, this PR parameterizes the platform option under clickhouse, backend, and python-backend services inside docker-compose.yaml.

• By default, it resolves to "" (native architecture), ensuring zero disruption and 100% native performance for existing x86_64, standard arm64, and Apple Silicon users.
• Raspberry Pi 4 / CM4 users can now run in emulation mode (using QEMU) easily by setting the corresponding platform environment variables:

  export OPIK_CLICKHOUSE_PLATFORM=linux/amd64
  export OPIK_BACKEND_PLATFORM=linux/amd64
  export OPIK_PYTHON_BACKEND_PLATFORM=linux/amd64
  ./opik.sh

Closes #2101

[andrescrz]

👋 Review summary

What looks good

• Clean, minimal, backward-compatible approach — ${VAR:-} defaults to an empty platform, so existing x86_64 / Apple Silicon / arm64 users are completely unaffected.
• Good instinct to make it an opt-in env knob rather than hardcoding platforms or adding custom Dockerfiles.
• Documented the workaround in the README rather than leaving it tribal knowledge.

Overall
A couple of things to reconsider before this can close #2101. The root cause in #2101 is the CPU feature level (RPi4/CM4 is ARMv8.0-A; ClickHouse and the backend require ARMv8.2-A), not the arm64-vs-amd64 architecture — native arm64 runs fine on Apple Silicon / Graviton2+ because those meet ARMv8.2-A. Parameterizing platform only enables amd64 emulation, which (a) needs QEMU/binfmt setup that isn't documented (see inline), (b) is untested by anyone on this hardware, and (c) is likely too slow to be usable on an RPi4. So this is a reasonable escape-hatch, but I'd stop short of "Closes #2101" — consider reframing as "document emulation as a best-effort workaround" and/or officially noting RPi4/CM4 as unsupported.

Minor: platform: ${VAR:-} resolves to platform: "", which modern compose treats as unset — fine, though worth a sanity check against the older docker-compose versions RPi users often run.

Inline comments: 2 blockers.

🤖 Review posted via /review-github-pr

[namdamdoi68-oss]

Hello @andrescrz,

I have addressed all the review feedback:

1. Docker Compose Configuration: Added the platform overrides (platform: ${OPIK_PYTHON_BACKEND_PLATFORM:-} and platform: ${OPIK_GUARDRAILS_BACKEND_PLATFORM:-}) to the demo-data-generator and guardrails-backend services.
2. Documentation: Updated README.md to document the QEMU emulation registration prerequisite (docker run --privileged --rm tonistiigi/binfmt --install amd64) and softened the support framing, adding warning notes regarding ClickHouse and JVM performance constraints on 4GB RPi4 hardware.
3. Code Quality: Added module and function-level docstrings to the verify_compose_yaml.py script as suggested by Baz Bot.

Please let me know if there's anything else needed!

[andrescrz]

Hi @namdamdoi68-oss

Thanks a lot for taking the time to work on this and submit a contribution—we really appreciate the effort and your interest in improving the project.

I left some feedback on both the overall approach and the implementation details.

At a high level, this change provides a workaround, but we're not convinced it will deliver the experience we want on lower-end devices such as the Raspberry Pi 4 / Compute Module 4, where it relies on running amd64 Docker images.

Before introducing this, we'd want to verify that the approach consistently provides an acceptable level of quality. We'd rather not support Opik on these devices yet than offer an experience that doesn't meet expectations.

More broadly, this is a workaround rather than a solution to the underlying issue, so we'd prefer to keep the issue open for now regardless of this PR.

Regarding the implementation itself, we're hesitant to introduce configurable Docker platform resolution. In general, we prefer to rely on Docker's automatic platform resolution, as it reduces the risk of user misconfiguration. We'd only consider exposing this as a configuration option if the benefits clearly outweigh the additional complexity and potential for incorrect setups.

Finally, could you provide some evidence that this approach works reliably in practice? For example, a short video demonstrating Opik running successfully on the target devices would be very helpful in evaluating the proposal.

Thanks again for the contribution and for engaging with the project. Even if we decide not to move forward with this particular approach, we'd be happy to review future contributions that address the underlying issue in a different way.

[andrescrz]

Please do not commit all these MD files, they don't belong to Opik code base.

[andrescrz]

For architectural reasons, we aren't completely sure if we want to allow overriding the platform, instead of allowing docker to automatically determine and pull/use the right images.

This introduces an extra layer of complexity (users might override the env vars, forget to unset them and report unnecessary issues/bugs), unless there's a reason that makes this worthy.

For this particular case, I don't think this approach completely meets the goal of allowing Opik running in RPi CM4, as emulation seems more like a workaround than an actual fix.

We need to evaluate if the workaround is worthy introducing this.

[andrescrz]

This emulation workaround suggest 3rd party components from our official documentation. We will need to evaluate if this is worthy the benefit.

[andrescrz]

This shouldn't be included in the code base.