Integrate/MQTT: Add entry point page, micro tutorial, and category item #247
Conversation
|
Warning Rate limit exceeded@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 27 minutes and 37 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (5)
WalkthroughAdds MQTT documentation and index entries: inserts Changes
Sequence Diagram(s)sequenceDiagram
participant Publisher as MQTT Publisher
participant Broker as MQTT Broker (Mosquitto)
participant Lorry as LorryStream
participant Crate as CrateDB
participant User as User
Publisher->>Broker: Publish JSON message to topic
Lorry->>Broker: Subscribe to topic
Broker-->>Lorry: Deliver message
Lorry->>Crate: Insert message as row into table
User->>Crate: Query table to verify data
Crate-->>User: Return stored rows
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/integrate/mqtt/index.md (1)
5-6: Consider avoiding external hotlink for the logo.Hotlinking the MQTT logo introduces an external runtime dependency. Prefer vendoring the asset into the docs’ static files if allowed.
docs/integrate/mqtt/learn.md (1)
42-46: Portability note: Docker host networking.--network=host is unsupported on Docker Desktop (macOS/Windows). Consider adding a note with alternatives (user-defined bridge or host.docker.internal).
Example alternatives (outside the selected range):
- Use a bridge network:
- docker network create mqtt-demo
- Add --network=mqtt-demo to all docker run aliases and containers
- Or, keep host networking on Linux and document replacing localhost with host.docker.internal in the MQTT/CrateDB URLs on Docker Desktop.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/integrate/index.md(1 hunks)docs/integrate/mqtt/index.md(1 hunks)docs/integrate/mqtt/learn.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/mqtt/learn.md
🪛 LanguageTool
docs/integrate/mqtt/learn.md
[style] ~20-~20: Two successive sentences begin with the same adverb. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ively to that, you can also use Podman. Alternatively to Mosquitto, you can also use a differ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/integrate/mqtt/index.md
[uncategorized] ~20-~20: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...cations, oil and gas, etc. is a leading open source server agent to help you collect metric...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/index.md
52-52: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (3)
docs/integrate/mqtt/index.md (1)
45-49: Good: Cross-ref target and naming align with integration patterns.Using the ref link “mqtt-learn” from the index page matches the documented “-learn” convention for tutorials.
docs/integrate/index.md (1)
49-49: LGTM: Added MQTT entry in toctree in the right spot.Placement between mongodb and mysql preserves ordering and integrates the new section.
docs/integrate/mqtt/learn.md (1)
61-66: Ensure the target table exists before running the relayUnless Lorry is configured to auto-create the destination schema, the relay command will fail with a missing-table error. Please verify your preferred approach and update the docs accordingly:
• Location: docs/integrate/mqtt/learn.md (lines 61–66)
• Option A: Manually create the table once before invoking the relay-Invoke the data transfer pipeline. +Create the target table (once). +```shell +crash -c "CREATE TABLE IF NOT EXISTS testdrive (temperature double, humidity double)" +``` + +Invoke the data transfer pipeline.lorry relay
"mqtt://localhost/testdrive/%23?content-type=json"
"crate://localhost/?table=testdrive"• Option B: Configure Lorry’s Crate sink to auto-create the table (e.g., using an object-column schema) Please confirm which mode you’d like to document. </details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
docs/integrate/mqtt/learn.md (4)
33-33: Fix unused link reference by linking the first Mosquitto mention.This satisfies markdownlint MD053 (“unused link reference”).
Apply this diff:
-Start Mosquitto. +Start [Eclipse Mosquitto].
35-37: Pin Mosquitto image tag for reproducibility and to match client version.You’re using
eclipse-mosquitto:2.0for clients, butlatestfor the broker. Pin the broker to2.0for consistency and to ensure/mosquitto-no-auth.confbehavior doesn’t change underlatest.Apply this diff:
-docker run --name=mosquitto --rm -it --network=mqtt-demo \ - --publish=1883:1883 docker.io/eclipse-mosquitto:latest \ +docker run --name=mosquitto --rm -it --network=mqtt-demo \ + --publish=1883:1883 docker.io/eclipse-mosquitto:2.0 \ mosquitto -c /mosquitto-no-auth.conf
28-31: Consider pinning CrateDB to a known-good version to avoid breakage.Using
crate:latestcan change behavior over time and break the tutorial. Pin a stable version (adjust to your supported baseline).Apply this diff as a starting point (update the version if needed):
- --env=CRATE_HEAP_SIZE=2g docker.io/crate:latest -Cdiscovery.type=single-node + --env=CRATE_HEAP_SIZE=2g docker.io/crate:6.0.0 -Cdiscovery.type=single-node
33-38: Add a short security disclaimer about anonymous MQTT access.A brief note helps prevent users from deploying the demo config in production.
Apply this diff:
docker run --name=mosquitto --rm -it --network=mqtt-demo \ --publish=1883:1883 docker.io/eclipse-mosquitto:2.0 \ mosquitto -c /mosquitto-no-auth.conf + +> Note: This broker configuration allows anonymous access for demonstration purposes only. +> Do not expose it to untrusted networks. For production, configure authentication/TLS.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrate/mqtt/learn.md(1 hunks)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-12T22:04:12.504Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:0-0
Timestamp: 2025-08-12T22:04:12.504Z
Learning: The eclipse-mosquitto:2.0 Docker image includes a pre-configured `/mosquitto-no-auth.conf` file that contains listener 1883 and allow_anonymous true settings, making it suitable for tutorials requiring anonymous MQTT broker access without additional configuration.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:57:26.315Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.315Z
Learning: Docker Desktop for Mac supports --network=host networking and works well with the commands in the CrateDB MQTT integration tutorial. The user amotl confirmed this works correctly on their macOS installation with Docker Desktop installed via brew.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:59:18.823Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.823Z
Learning: Docker Desktop host networking on Windows (even in version 4.34+) has significant limitations: Linux containers only, Layer 4 protocols only, cannot bind to host NIC IPs, potential listener scaling issues (~18 concurrent ports), and various WSL2 compatibility problems. For tutorials, explicit port mapping with bridge networks is more reliable than --network=host on Windows.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:57:26.315Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.315Z
Learning: Docker Desktop added opt-in host networking support in version 4.34 (August 2024) for macOS, Windows, and Linux Desktop. The feature requires manual enablement in Settings → Resources → Network → "Enable host networking" and the user must be signed in to Docker Desktop. This explains why some Docker Desktop users (like amotl) have working --network=host while others may not.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:59:18.823Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.823Z
Learning: For Windows Docker command aliases, PowerShell functions with args are recommended over Set-Alias for commands with arguments. Command Prompt uses doskey with $* for argument forwarding. Both require platform-specific setup (PowerShell profile or doskey batch file with registry AutoRun).
Applied to files:
docs/integrate/mqtt/learn.md
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/learn.md
100-100: Link and image reference definitions should be needed
Unused link or image reference definition: "eclipse mosquitto"
(MD053, link-image-reference-definitions)
🔇 Additional comments (2)
docs/integrate/mqtt/learn.md (2)
1-1: Anchor naming matches the Guide’s conventions; LGTM.Using
(mqtt-learn)=aligns with the documented “-learn” anchor pattern used across integrations.
76-97: End-to-end workflow reads well and is correct.Topic subscription, publish, relay via LorryStream, and verification with crash are coherent and accurate.
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/integrate/mqtt/learn.md (2)
33-33: Use the defined reference link or remove the unused definition (fixes MD053).You define
[Eclipse Mosquitto]at the bottom but never reference it; markdownlint flags it as unused.Apply this diff to link the heading:
-Start Mosquitto. +Start [Eclipse Mosquitto].Alternatively, remove the reference definition at the bottom if you prefer not to link here.
66-71: Use proper code fence language for CMD block.The block contains Windows Command Prompt
doskeymacros. Usecmdfor clearer highlighting.Apply this diff:
-```shell +```cmd doskey crash=docker run --rm -it --network=mqtt-demo ghcr.io/crate/cratedb-toolkit crash $* doskey lorry=docker run --rm -i --network=mqtt-demo ghcr.io/daq-tools/lorrystream lorry $* doskey mosquitto_pub=docker run --rm -i --network=mqtt-demo eclipse-mosquitto:2.0 mosquitto_pub $* doskey mosquitto_sub=docker run --rm -i --network=mqtt-demo eclipse-mosquitto:2.0 mosquitto_sub $*
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrate/mqtt/learn.md(1 hunks)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-12T22:04:12.504Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:0-0
Timestamp: 2025-08-12T22:04:12.504Z
Learning: The eclipse-mosquitto:2.0 Docker image includes a pre-configured `/mosquitto-no-auth.conf` file that contains listener 1883 and allow_anonymous true settings, making it suitable for tutorials requiring anonymous MQTT broker access without additional configuration.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:57:26.315Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.315Z
Learning: Docker Desktop for Mac supports --network=host networking and works well with the commands in the CrateDB MQTT integration tutorial. The user amotl confirmed this works correctly on their macOS installation with Docker Desktop installed via brew.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:59:18.823Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.823Z
Learning: Docker Desktop host networking on Windows (even in version 4.34+) has significant limitations: Linux containers only, Layer 4 protocols only, cannot bind to host NIC IPs, potential listener scaling issues (~18 concurrent ports), and various WSL2 compatibility problems. For tutorials, explicit port mapping with bridge networks is more reliable than --network=host on Windows.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:57:26.315Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:57:26.315Z
Learning: Docker Desktop added opt-in host networking support in version 4.34 (August 2024) for macOS, Windows, and Linux Desktop. The feature requires manual enablement in Settings → Resources → Network → "Enable host networking" and the user must be signed in to Docker Desktop. This explains why some Docker Desktop users (like amotl) have working --network=host while others may not.
Applied to files:
docs/integrate/mqtt/learn.md
📚 Learning: 2025-08-12T21:59:18.823Z
Learnt from: amotl
PR: crate/cratedb-guide#247
File: docs/integrate/mqtt/learn.md:38-46
Timestamp: 2025-08-12T21:59:18.823Z
Learning: For Windows Docker command aliases, PowerShell functions with args are recommended over Set-Alias for commands with arguments. Command Prompt uses doskey with $* for argument forwarding. Both require platform-specific setup (PowerShell profile or doskey batch file with registry AutoRun).
Applied to files:
docs/integrate/mqtt/learn.md
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/learn.md
102-102: Link and image reference definitions should be needed
Unused link or image reference definition: "eclipse mosquitto"
(MD053, link-image-reference-definitions)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (1)
docs/integrate/mqtt/learn.md (1)
45-75: Strong cross-platform design and networking setup.Great job switching to a shared bridge network (
mqtt-demo) with container-name addressing and providing Linux/macOS, PowerShell, and CMD shortcuts. This will work consistently across environments and avoids Desktop host-networking pitfalls.
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
docs/ingest/etl/index.md (1)
211-235: Add MQTT to the “Alphabetically sorted” list for consistencyThe section claims alphabetical completeness but doesn’t list MQTT yet. Please add it to aid discoverability.
Apply this diff to insert MQTT in alphabetical order (after mongodb, before mysql):
- {ref}`mongodb` +- {ref}`mqtt` - {ref}`mysql`
🧹 Nitpick comments (3)
docs/integrate/mqtt/index.md (3)
4-6: Avoid hotlinking the MQTT logo (prefer vendored assets or local fallback)Relying on an external image (mqtt.org) can break previews/offline builds and introduces third‑party requests. Consider vendoring the SVG under the docs’ static assets and referencing it locally; optionally add a fallback alt-only rendering if the asset is unavailable.
26-33: Optional: Clarify prerequisites for the uvx exampleSome readers may not have uv/uvx installed. Consider adding a short note linking to install instructions, or point them to the Learn tutorial for a Docker-only path.
37-41: Tighten phrasing and fix hyphenationThe current hyphenation/punctuation is awkward (“backplane-, message relay-, or pipeline-subsystem”, “allowing to orchestrate”). Suggested copy is more idiomatic.
Apply this diff:
-[LorryStream] is a lightweight and polyglot stream-processing library, to be -used as a data backplane-, message relay-, or pipeline-subsystem. -[Node-RED] is a workflow automation tool allowing to orchestrate message flows -and transformations via a comfortable web interface. +[LorryStream] is a lightweight and polyglot stream-processing library, used as a +data backplane, message relay, or pipeline subsystem. +[Node-RED] is a workflow automation tool that allows you to orchestrate message flows +and transformations via a comfortable web interface.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/ingest/etl/index.md(1 hunks)docs/integrate/mqtt/index.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/index.md
51-51: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (5)
docs/ingest/etl/index.md (1)
148-154: New MQTT entry in Streams — LGTMThe addition is well-placed and the copy succinctly describes MQTT. The {ref}
mqttanchor resolves to the new integration page’s label.docs/integrate/mqtt/index.md (4)
13-21: “About” section reads clean and accurate — LGTMThe MQTT description is focused and correctly scoped. Good fix.
44-49: Ensure the “mqtt-learn” ref target exists, or link to the doc by nameThe card uses :link-type: ref to “mqtt-learn”. Per the team’s convention (retrieved learnings), tutorials use a “-learn” anchor, but please verify that docs/integrate/mqtt/learn.md defines (mqtt-learn)=. If not, either add that anchor to learn.md or change this card to link to the doc by name.
Option A — keep ref, ensure anchor exists at the top of learn.md:
(mqtt-learn)= # Learn: MQTTOption B — switch to doc link here:
-:link: mqtt-learn -:link-type: ref +:link: learn +:link-type: doc
50-54: markdownlint MD034 (bare URL) is a false positive in directive attributeThe bare URL is provided as a target to 🔗 within a directive, not as inline Markdown content. Safe to keep as-is.
58-62: Hidden toctree correctly registers the Learn page — LGTMEnsures navigation and cross-referencing work without cluttering the page.
amotl
added
sanding-1200
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/integrate/mqtt/index.md (2)
29-32: Clarify %23 encoding in the example (minor doc UX).Add a brief inline note so readers immediately understand that %23 encodes the # wildcard.
Apply this diff:
```shell uvx --from=lorrystream lorry relay \ - "mqtt://localhost/testdrive/%23?content-type=json" \ + # %23 encodes '#', subscribing to 'testdrive/#' + "mqtt://localhost/testdrive/%23?content-type=json" \ "crate://localhost/?table=testdrive"--- `50-54`: **Silence markdownlint MD034 for the external URL in the card.** markdownlint flags “Bare URL” on directive fields even though this is valid Sphinx-Design usage. Disable MD034 for this line only. Reference: Static analysis hint MD034 on Line 51. Apply this diff: ```diff ::: {grid-item-card} Tutorial: Use Node-RED -:link: https://community.cratedb.com/t/ingesting-mqtt-messages-into-cratedb-using-node-red/803 +<!-- markdownlint-disable-next-line MD034 --> +:link: https://community.cratedb.com/t/ingesting-mqtt-messages-into-cratedb-using-node-red/803 :link-type: url Ingesting MQTT messages into CrateDB using Node-RED. :::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrate/mqtt/index.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/index.md
51-51: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (6)
docs/integrate/mqtt/index.md (6)
1-3: Anchor and title follow doc IA conventions.Top-level label (mqtt)= and H1 align with integration anchor patterns used elsewhere in the guide.
4-8: Logo block is correct and accessible.Right-floated logo with alt text and lazy loading is good; clearfix ensures proper flow.
13-21: “About” section reads clearly and fixes earlier conflation.The copy now accurately describes MQTT without mixing in unrelated tooling.
44-49: Ensure the target label exists::link: mqtt-learnrequires(mqtt-learn)=in learn.md.If the learn page doesn’t define the
(mqtt-learn)=label, this card won’t resolve with:link-type: ref.Apply at the top of docs/integrate/mqtt/learn.md:
(mqtt-learn)= # Learn: MQTT with LorryStreamWould you like me to scan the repo for the label and open a follow-up if it’s missing?
58-62: Hidden toctree entry for Learn is correct.Keeps the page tidy while exposing the tutorial in navigation.
65-67: Reference links are well-defined and consistently used.Good practice to centralize external URLs.
amotl
changed the title
amotl
changed the title
| Invoke the data transfer pipeline. | ||
| ```shell | ||
| lorry relay \ | ||
| "mqtt://mosquitto/testdrive/%23?content-type=json" \ | ||
| "crate://cratedb/?table=testdrive" | ||
| ``` |
There was a problem hiding this comment.
Of course, this is just a toy example, because it has been exactly conceived for the purpose of having an easy tutorial. More intense user testing and validation in mature environments, not even corporate ones, is urgently needed to avoid embarrassing readers.
Hints: SSL/TLS, Auth, Managed MQTT, Managed CrateDB.
There was a problem hiding this comment.
Who can test this tutorial? Either @hammerhead, @karynzv, @surister or @stephanec76 perhaps?
docs/integrate/mqtt/index.md
Outdated
| :::{toctree} | ||
| :maxdepth: 1 | ||
| :hidden: | ||
| Learn <learn> |
There was a problem hiding this comment.
I suggest we call this "Tutorial" instead (here and other relevant places).
There was a problem hiding this comment.
There has been a ticket that was asking for feedback. Now it is too late for the current iteration.
We've now organically started using
learn.mdas the canonical page name for the basic introductory tutorial about any given integration thing.
There was a problem hiding this comment.
Maybe just change the visible label?
There was a problem hiding this comment.
Now it is too late for the current iteration.
I strongly disagree with that approach. That issue was posted last year, no one reviewed it and we are doing a redesign. We surely need to be able to change things now for the better.
Maybe just change the visible label?
That's the most important 👍
There was a problem hiding this comment.
Hi. It is not an approach, just evidence: Over here, I am reporting about the status quo how the learn term hit the street, so it is too late for the current iteration, certainly for this patch as it would become an outlier then. However, we can easily do a renaming in the next iteration? I think we are really fluent here to mix and match.
There was a problem hiding this comment.
I'm fine if we can just update the end user visible labels to Tutorial - that will bring menu naming into alignment with the other text already calling it a tutorial.
There was a problem hiding this comment.
Sure. Updated with 755d465.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/integrate/mqtt/index.md (3)
19-22: Mention Mosquitto to match PR scope.The page currently doesn’t mention Eclipse Mosquitto, despite the PR framing this integration around Mosquitto + LorryStream. Add a brief mention to set context.
Apply this diff:
MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas. It enables efficient, reliable messaging between devices and backends over constrained networks. + +In our examples, we use Eclipse Mosquitto as the MQTT broker.
26-32: Verify consistency with “all commands use Docker.”The Synopsis uses
uvxto run LorryStream directly, which may conflict with the PR description that “all commands and components are executed using Docker.” Either:
- keep this as-is and adjust the PR copy accordingly, or
- provide a Docker-based invocation example or a tabs block (Docker/uvx).
Would you like me to draft a Docker-based example for LorryStream here?
4-6: Consider vendoring the MQTT logo to avoid external dependencies and tracking.Loading assets from mqtt.org during build/view can introduce fragility and external requests. If feasible, store the SVG under the project’s static assets and reference it locally.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/integrate/mqtt/index.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/mqtt/index.md
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mqtt/index.md
51-51: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (2)
docs/integrate/mqtt/index.md (2)
1-3: Good structure: anchor, sections, and visible “Tutorial” label align with our docs pattern.
- Anchor
(mqtt)=in index.md and the separate learn page follow the integration pattern you outlined earlier.- Using “Tutorial ” as the visible label brings menu naming in line with prior feedback while keeping the learn.md filename.
Also applies to: 34-36, 58-62
44-47: Reference link valid:mqtt-learnanchor foundVerified that
docs/integrate/mqtt/learn.mddefines(mqtt-learn)=at line 1, so themqtt-learncard link is correct and no changes are needed.
There was a problem hiding this comment.
LGTM
I suggest that we have one reviewer testing it before merging as @bmunkholm is saying.
amotl
force-pushed
the
integrate-mqtt
branch
2 times, most recently
from
c2ea074 to
2bc2dc3
Compare
The rig uses Eclipse Mosquitto and LorryStream to invoke the data transfer procedure, all based on using Docker.
Otherwise let's add another task to the LoD tracker? We will probably need to do it anyway, because the test matrix goes up when approaching mature environments and scenarios (Hints: SSL/TLS, Auth, Managed MQTT, Managed CrateDB), and if we don't literally test them, the tutorial really just covers basic grounds. This is certainly better than nothing, yet remember it is 2025 already, and ubiquitous computing isn't here since yesterday ;]. |
Done. |
3 participants
About
Using Eclipse Mosquitto and LorryStream to invoke a data transfer procedure from an MQTT topic into a CrateDB table, all based on using Docker for executing any command.
Preview
References
/cc @karynzv, @hammerhead, @surister