Add Detailed Usage Descriptions for Federated Catalog

[oliverbusch]

Feature Request

The current documentation for the Federated Catalog provides an extensive overview of the architecture, key components, and deployment considerations. However, it lacks detailed usage descriptions that would guide users on how to practically implement and use these components. Adding comprehensive usage descriptions will enhance the usability of the documentation and facilitate smoother implementation and deployment processes.

Which Areas Would Be Affected?

Documentation

Why Is the Feature Desired?

Incorporating these detailed usage descriptions will provide users with practical, actionable guidance, enabling effective use and integration of the Federated Catalog components into their projects.

Solution Proposal

Requested Features:

• Federated Catalog:
  • Step-by-step guide on setting up the Federated Catalog.
  • Instructions on configuring the Federated Catalog Crawler (FCC).
  • Practical deployment examples in different environments.

[paullatzelsperger]

@oliverbusch I believe everything you ask for is already there. It might not yet be consolidated in a central location (we're working on that), or be replicated in every repo, but the information is there:

Step-by-step guide on setting up the Federated Catalog.

the README.md has a dedicated section how to build and run the FCC with Docker and as a native Java process.

Instructions on configuring the Federated Catalog Crawler (FCC).

All relevant config properties should be documented using autodoc. to generate human-readable documentation, simply execute:

./gradlew autodoc
./gradlew mergeManifest
./gradlew doc2md

then a markdown file should be in the build/ folder. For more details check here

Practical deployment examples in different environments.

There is a launcher to run the FC in a standalone configuration. Since it is built on EDC modules, modularity and pluggability are in its DNA. I recommend reading up on general EDC architectural and coding principles. In addition, please also read the documentation about Management Domains. There is probably several other ways how the FC could be deployed, but we're not going to (be able to) provide an exhaustive list.

Lastly, checkout MVD for a practical application, embedded and standalone.

So, assuming that you've read all the relevant EDC documentation: what exactly are you missing?

[oliverbusch]

@paullatzelsperger I am looking for information on setting up the FC in the [Type 2b: Distributed Management Domains containing a Catalog Server and separate Control/Data Plane runtimes topology] (url)

And in particular, how the FCC can/must be configured.

According to the "distributed" documentation, I would assume that I configure the FCC with the following rest call.

{{HOST}}/api/management/v3/assets

{
    "@context": {},
    "@id": "linked-asset-provider-qna",
    "@type": "CatalogAsset",
    "properties": {
        "description": "This is a linked asset that points to the catalog of ALICE.",
        "isCatalog": "true"
    },
    "dataAddress": {
        "@type": "DataAddress",
        "type": "HttpData",
        "baseUrl": "{{PROVIDER_ALICE_DSP_URL}}/api/dsp"
    }
}

{
    "@context": {},
    "@id": "linked-asset-provider-qna",
    "@type": "CatalogAsset",
    "properties": {
        "description": "This is a linked asset that points to the catalog of BOB.",
        "isCatalog": "true"
    },
    "dataAddress": {
        "@type": "DataAddress",
        "type": "HttpData",
        "baseUrl": "{{PROVIDER_BOB_DSP_URL}}/api/dsp"
    }
}

But I'm not sure if this is really the case.

[paullatzelsperger]

this is pretty much verbatim the use case that MVD models, so you should be able to go from there.

[oliverbusch]

Thanks for the quick feedback, Perhaps I would not have asked if the FC API link had worked and an example had been linked.
](#229)

Yes, this is very close to the use case from the MVD. But if you approach the topic from the FC component, you will only find the necessary information via detours, e.g. via the MVD and the Postman commands.

[paullatzelsperger]

like i said, we are currently undergoing a major documentation overhaul, which should address this.
I converted the issue into a discussion and took the liberty of marking the answer, to preserve it for future readers.