External Services/Services documentation

[dominiquekleeven]

Closes #102

Depends on: openremote/openremote#1979

BLOCKING: the new docs refer to the service-ml-forecast repository which is not public yet, nor does it currently publish the docker image referenced in the developer guide.

New pages/sections

Developer Guide

• External Services - Comprehensive guide covering what external services are, the different types (global vs regular), development requirements, registration process, deployment with Docker Compose and HAProxy configuration, security considerations, and reference implementations. Includes detailed API endpoints, heartbeat mechanisms, and practical examples with mermaid sequence diagrams.

User Guide

• Services - User-friendly introduction to services in OpenRemote, explaining how to find and use them in the Manager UI, troubleshooting common issues, and understanding service status indicators.
• ML Forecasting Service - Dedicated user guide for the ML Forecasting Service, covering features, access instructions, detailed configuration form with parameter explanations, and how to view generated forecasts in the Insights UI. Includes guidance on when to adjust model parameters and regressor usage.

Mermaid Plugin:

• Added Mermaid plugin (@docusaurus/[email protected]) for diagram support in documentation, this allows us to use code to create and maintain diagrams. These are very concise and easy to maintain.

GitHub also supports mermaid, see example :)

flowchart TD
    A[External Service] --> B[Register API Call]
    B --> C[Get instanceId]
    C --> D[Send Heartbeats]
    D --> E[Available in Manager UI]

Loading

These can also be easily generated by most LLMs which allows you to use natural language to describe and tweak them.

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation for external services in OpenRemote, covering both developer and user perspectives. It introduces the Mermaid plugin for diagram support and creates new documentation sections explaining how to develop, deploy, and use external services.

Key Changes

• Added Mermaid plugin support for creating maintainable diagrams in documentation
• Created comprehensive developer guide for external services covering registration, deployment, and security
• Added user-friendly service documentation with troubleshooting and usage instructions

Reviewed Changes

Copilot reviewed 6 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
package.json	Added Mermaid plugin dependency for diagram support
docusaurus.config.ts	Configured Mermaid theme and markdown support
docs/user-guide/services/category.json	Created services section in user guide navigation
docs/user-guide/services/services.md	General user guide for finding and using services
docs/user-guide/services/service-ml-forecast.md	Detailed user guide for ML Forecasting Service
docs/developer-guide/external-services.md	Comprehensive developer guide for external services

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[dominiquekleeven]

BLOCKING: the new docs refer to the service-ml-forecast repository which is not public yet, nor does it currently publish the docker image referenced in the developer guide.

Text, structure and general flow of things can be reviewed.

[dominiquekleeven]

Updated the developer guide to have a clear flow on how to setup your own service e.g. from scratch.

Updated the openapi.yaml