docs: production deployment guide for build/runtime separation (no Rust at runtime)

[membphis]

Background

luarocks install lua-qjson builds the Rust native library at install time, so
the install environment needs Rust/Cargo (README §Installing). The original
framing of this issue assumed the goal was to make the install step itself
Rust-free, via pre-built binaries shipped to GitHub Releases / LuaRocks.

After discussion, that is not the actual requirement. qjson's runtime
dependency is only the compiled libqjson.so + the Lua wrappers + LuaJIT —
Rust is a pure build-time dependency. The real need is simply: the runtime
environment (e.g. a production APISIX image) must not carry Rust, while having
Rust in the build environment is perfectly acceptable.

This is a textbook build/runtime separation, which the current toolchain already
supports today — it's just undocumented. The gap is documentation, not missing
distribution machinery.

Goal

Document how to deploy qjson so that the runtime environment contains no Rust
toolchain, by separating the build stage (has Rust, runs luarocks install)
from the runtime stage (only the compiled artifacts + LuaJIT).

Non-goals

• Pre-built binaries on GitHub Releases / LuaRocks (original Option A/B/C).
• Cross-compilation matrix or changes to release.yml.
• Making the luarocks install step itself Rust-free.

These remain possible future work (a separate "prebuilt distribution" issue) if
demand from third-party luarocks install users ever materializes — but they
are explicitly out of scope here.

Acceptance Criteria

• README (or a docs/ page) has a "Production deployment / no Rust at runtime" section
• A working Docker multi-stage example is provided where the runtime stage contains no Rust/Cargo
• The docs enumerate exactly what the runtime needs: qjson.so, qjson.lua, qjson/lib.lua, qjson/table.lua, plus LuaJIT
• The docs show using luarocks install --tree=<dir> to stage artifacts into one directory for a clean COPY
• The example is verified: a runtime image with no cargo/rustc can require("qjson") and parse successfully

Task Checklist

1. Documentation

• 1.1 Add a "Production deployment (no Rust at runtime)" section to README or docs/
• 1.2 Write a multi-stage Dockerfile example (builder w/ Rust → clean runtime)
• 1.3 List the exact runtime file set and their install paths

2. Verification

• 2.1 Build the multi-stage image and confirm require("qjson") works in a runtime stage with no Rust toolchain

Notes / Decisions

• The original pre-built-binary framing was a generic comparison-to-lua-cjson
  idea (auto-generated issue), larger than the actual need.
• Confirmed requirement: Rust at luarocks install time is acceptable; only the
  runtime must be Rust-free.
• Mechanism: luarocks install --tree=/qjson-rock lua-qjson in a builder stage,
  then COPY --from=builder /qjson-rock /usr/local/ into a Rust-free runtime.

[coderabbitai]

🔗 Related PRs

#43 - test: add cjson and simdjson fixture coverage [merged]
#45 - feat: release v0.1.0 [merged]
#58 - docs: fix install instructions and qualify ARM64 performance claims [merged]
#78 - test(fuzz): add nesting-depth stack-safety target [merged]
#85 - chore: add cargo-audit CI gate and CHANGELOG skeleton [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!