Setting Up the Digital Product Passport API#
This setup runs the DPP API and Configuration Service with PostgreSQL 18. It exposes the DPP API at http://localhost:8088 and enables history so that the complete usage walkthrough can retrieve an earlier passport state.
Note
For unsecured and Keycloak-secured deployments, see the BaSyx DPP API Example.
Prerequisites and Security Posture#
Docker with Docker Compose
host port
8088availablePostgreSQL 16 or newer for existing external database deployments
Warning
This local example uses illustrative credentials and explicitly disables ABAC. Its APIs accept unauthenticated requests and must not be exposed to an untrusted network. Replace the credentials, configure transport security, and enable Runtime Security before using this topology beyond local development.
Compose Configuration#
Save the following as docker-compose.yml:
services:
postgres:
image: postgres:18
environment:
POSTGRES_USER: basyx_demo
POSTGRES_PASSWORD: change-me
POSTGRES_DB: basyxDpp
healthcheck:
test: ["CMD-SHELL", "pg_isready -U basyx_demo -d basyxDpp"]
interval: 10s
timeout: 5s
retries: 5
volumes:
- dpp_postgres:/var/lib/postgresql
basyx_configuration:
image: eclipsebasyx/basyxconfigurationservice-go:latest
environment:
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
POSTGRES_USER: basyx_demo
POSTGRES_PASSWORD: change-me
POSTGRES_DBNAME: basyxDpp
depends_on:
postgres:
condition: service_healthy
dpp_api:
image: eclipsebasyx/dppapi-go:latest
environment:
SERVER_PORT: 8080
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
POSTGRES_USER: basyx_demo
POSTGRES_PASSWORD: change-me
POSTGRES_DBNAME: basyxDpp
BASYX_HISTORY_MODE: api
ABAC_ENABLED: "false"
ports:
- "8088:8080"
depends_on:
basyx_configuration:
condition: service_completed_successfully
volumes:
dpp_postgres:
The health check waits for PostgreSQL before the one-shot Configuration Service starts. The DPP API starts only after schema initialization or migration completes successfully. The Configuration Service is not required in normal request traffic after the database is prepared.
Use the same concrete BaSyx Go release tag for the Configuration Service and DPP API. For a reproducible deployment, alternatively pin both images to the corresponding immutable image digests from the same release. Do not combine a database migrated by one release with a runtime that expects another schema version.
BASYX_HISTORY_MODE=api records DPP-related AAS and Submodel changes required by the historical-read example. History is disabled by default in the stock service. Enabling it later does not reconstruct earlier states.
Start and Check Readiness#
Start the project:
docker compose up -d
The Configuration Service container completing with exit code 0 is expected. Wait until the DPP API is ready:
curl -i http://localhost:8088/health
Continue when the response is HTTP 200 with {"status":"UP"}. Swagger UI is available at http://localhost:8088/swagger.
Configuration and Integrations#
The DPP API uses the shared server, PostgreSQL, history, Registry-integration, observability, and security settings described in General Configuration. Configure a reader database only when the deployment can tolerate replica lag for read operations. Mutations and transaction-sensitive reads use the writer database.
The service can maintain AAS and Submodel descriptors in the same PostgreSQL database when the corresponding Registry-integration flags are enabled. A separate Registry process can expose those descriptors only when it uses that database. Registry services are not required for the DPP API itself.
The standalone DPP API does not expose the Submodel Repository attachment endpoint. If DPP content refers to database-managed File attachments, configure general.externalUrl with an externally reachable base URL for a deployment that exposes the corresponding /submodels/.../attachment route. Generated related-resource URLs use that route. If a managed attachment must be serialized without a valid general.externalUrl, the DPP read fails with 500 Internal Server Error.
The DPP API uses the file-backed ABAC policy setup rather than the database-backed ABAC policy-management API. Experimental ReBAC covers current-state DPP routes when enabled. Historical reads remain subject to the configured authentication and ABAC policies, but ReBAC does not cover the historical route. Historical resolution cannot apply a backend authorization filter to stored snapshots; when ABAC requires such a filter, the historical DPP is not returned. See Runtime Security and Relationship-Based Access Control before securing the service.
Persistent State and Stopping#
The named volume dpp_postgres stores the PostgreSQL data. docker compose down retains it; docker compose down -v deletes the database, including passports, recorded history, and Configuration Service state.
Warning
Do not remove the volume when the data must be retained. Back up PostgreSQL before upgrades or destructive operations and follow the existing-database guidance.