> For the complete documentation index, see [llms.txt](https://open-dataspaces.gitbook.io/ods-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://open-dataspaces.gitbook.io/ods-docs/developer-guide/04-deployment-and-configuration.md). # Chapter 4 System Build and Operations Setup Procedures (Data as a Product) This chapter presents the procedures for building a minimum configuration system capable of performing data exchange between participants, using the deploy definition files provided by ODS SDK for Onboarding (hereinafter "SDK"). ## System Build Procedures (4.1–4.3) ## 4.1 System Architecture The system architecture to be built in this chapter is as shown in Figure 3. Rectangles represent components or services, and arrows represent dependencies between them. ```mermaid graph LR subgraph a["Authentication System"] AuthN_DB["Authentication System RDBMS"] AuthN_SV["Authentication System"] end subgraph b["Authorization System"] AuthZ_DB["Authorization System RDBMS"] AuthZ_SV["ReBAC Authorization System"] end subgraph d["Data Space Infrastructure"] L3["L3: Identity Component"] L2["L2: Web API Transfer Module"] end IS["Data Provider\nIndustry Service\n(Sample)"] AuthN_SV -- "Read/Write Stored Data" --> AuthN_DB AuthZ_SV -- "Read/Write Stored Data" --> AuthZ_DB L3 -- "Authentication Request" --> AuthN_SV L3 -- "Authorization Request" --> AuthZ_SV L2 -- "Access Token Verification Request" --> L3 L2 -- "Authorization Request" --> AuthZ_SV L2 -- "Request Forwarding" --> IS ``` **Figure 3　System Architecture Provided by the SDK** This SDK uses PostgreSQL as the RDBMS, Keycloak as the authentication system, and OpenFGA as the ReBAC authorization system. In the following sections, the Identity Component and Web API Transfer Module may be referred to simply as L3 and L2, respectively. ## 4.2 Initial Configuration of Each Component The SDK provides files that aggregate the deploy definition files for each service, which can be used to start and stop all services at once. The usage instructions for the Docker Compose version are shown below. Clone the SDK repository locally. ```bash $ git clone https://github.com/open-dataspaces/SDK-docker-compose.git ``` Navigate into the cloned directory and clone the repositories for L2, L3, and the clearing and payment service. ``` $ cd SDK-docker-compose $ git clone --depth 1 https://github.com/open-dataspaces/L2-dp-webapi.git $ git clone --depth 1 https://github.com/open-dataspaces/L3-identity-component.git $ git clone --depth 1 https://github.com/open-dataspaces/DCS-Payment.git ``` Run Docker Compose using the docker-compose.yml file located at the top level of the repository to start all services. ```bash $ docker compose up -d ``` The setup is complete when all services have started, as shown below. For procedures on starting and stopping components individually, refer to "4.5 Starting and Stopping." ``` [+] Running 17/17 ✔ gateway Built 0.0s ✔ payment-app Built 0.0s ✔ l3-app Built 0.0s ✔ Volume "ods_pgdata" Created 0.0s ✔ Volume "ods_postgres_data" Created 0.0s ✔ Volume "ods_pgdata_openfga" Created 0.0s ✔ Container minio Started 1.0s ✔ Container postgres Started 1.1s ✔ Container fluentd Started 1.1s ✔ Container l3-app Started 1.0s ✔ Container payment-db Healthy 11.5s ✔ Container postgres-openfga Started 1.0s ✔ Container payment-app Started 12.0s ✔ Container keycloak Started 1.7s ✔ Container openfga Started 1.6s ✔ Container ods-minio-init-1 Started 1.4s ✔ Container gateway Started 2.2s ``` Next, perform the initial configuration for L3, OpenFGA, and L2 by running the scripts provided by the SDK. For details, refer to the [SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose/blob/main/README.md). ## Operations Setup Procedures (4.3–4.8) ## 4.3 Data Configuration for Starting Operations Before starting operations, it is necessary to register participant business information in L3. For details, refer to the [relevant section of the SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose?tab=readme-ov-file#%E9%81%8B%E7%94%A8%E9%96%8B%E5%A7%8B%E3%81%AB%E5%90%91%E3%81%91%E3%81%9F%E5%90%84%E7%A8%AE%E3%83%87%E3%83%BC%E3%82%BF%E8%A8%AD%E5%AE%9A). ## 4.4 Environment Configuration Between Components It is necessary to configure the L3 URL in L2's configuration file so that L2 can communicate with L3. For details, refer to the [relevant section of the SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose?tab=readme-ov-file#%E3%82%B3%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%8D%E3%83%B3%E3%83%88%E9%96%93%E3%81%AE%E7%92%B0%E5%A2%83%E8%A8%AD%E5%AE%9A). ## 4.5 Starting and Stopping The procedures for starting and stopping each component individually are as follows. ### L3: Identity Component Start ``` $ docker compose -f l3/docker-compose.yml up -d ``` Stop ``` $ docker compose -f l3/docker-compose.yml down ``` ### Logging Service Start ``` $ docker compose -f logging/docker-compose.yml up -d ``` Stop ``` $ docker compose -f logging/docker-compose.yml down ``` ### L2: Web API Transfer Module Start (L3 and Logging must be started beforehand) ``` $ docker compose up -d gateway ``` Stop ``` $ docker compose -f l2/docker-compose.yml down ``` ### Clearing and Payment Service Start (L3 must be started beforehand) ``` $ docker compose -f payment/docker-compose.yml up -d ``` Stop ``` $ docker compose -f payment/docker-compose.yml down ``` ## 4.6 Application Integration Data providers must configure authorization settings for the APIs published by the industry service, for the business entity created in "4.3 Data Configuration for Starting Operations." For details, refer to the [relevant section of the SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose?tab=readme-ov-file#%E3%82%A4%E3%83%B3%E3%83%80%E3%82%B9%E3%83%88%E3%83%AA%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E9%80%A3%E6%90%BA%E6%96%B9%E6%B3%95). Data users must set the headers shown in Table 2 in their HTTP requests. **Table 2: Required Header Information** | Header Name | Description | | ------------: | ----------------------------------------------------------------------------------------------------------- | | API-Key | API key issued by this service | | Authorization | Access token issued by L3 (Identity Component) in JWT format | | X-TrackingId | Log output item for provenance management (UUID format) | | X-ODS-xxx | Item subject to logging. Specify for xxx the string designated by the service provider (e.g., X-ODS-UserId) | ## 4.7 Executing and Verifying Data Exchange Data users acquire data from providers using the following procedure. 1. Obtain an access token: Follow [L3 Reference Implementation Tutorial 5-3. User Authentication (Authorization Code Flow)](https://github.com/pj-ods-a/open-data-spaces-l3-public/blob/main/docs/tutorials/README.md#5-3-%E3%83%A6%E3%83%BC%E3%82%B6%E5%BD%93%E4%BA%BA%E8%AA%8D%E8%A8%BC%E8%AA%8D%E5%8F%AF%E3%82%B3%E3%83%BC%E3%83%89%E3%83%95%E3%83%AD%E3%83%BC) to obtain an access token. 2. Access data: Use the obtained access token to access data. A sample command is shown below. ``` $ curl -X POST "http://localhost:8090/test " \ -H 'api-key: 2dfd3409-ce01-4451-96fa-7e10c9681422y' \ -H "Authorization: bearer $ACCESS_TOKEN" \ -H 'X-ODS-UserId: 112233' \ -H "Content-Type: application/json" \ -H "Prefer: return=representation" \ -d '{"userid":112233}' | jq . ``` For details, refer to the [relevant section of the SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose?tab=readme-ov-file#%E3%83%87%E3%83%BC%E3%82%BF%E4%BA%A4%E6%8F%9B). ## 4.8 Monitoring (Log Management) The types of logs output by each component are as follows. ### L2: Web API Transfer Module Logs output by L2 serve as the basis for billing records and are therefore collected by the logging service and stored as files in object storage. For information on output destinations, rotation intervals, and other details, refer to the [relevant section of the SDK documentation](https://github.com/open-dataspaces/SDK-docker-compose?tab=readme-ov-file#%E7%9B%A3%E8%A6%96). ### L3: Identity Component L3 outputs logs to standard output and standard error. When running in a container, logs can be viewed with the following command. ``` $ docker logs l3-app ``` ### Clearing and Payment Service The clearing and payment service outputs logs to standard output and standard error. When running in a container, logs can be viewed with the following command. ``` $ docker logs payment-app ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://open-dataspaces.gitbook.io/ods-docs/developer-guide/04-deployment-and-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.