Setting Up the Submodel Registry#

The configuration below provides a minimal standalone deployment.

Note

For a standalone Submodel Registry with Keycloak and ABAC, see the BaSyx Secured Example.

The Docker example uses latest for both BaSyx Go images. For native builds, use one stable source release and its matching database assets as described in Version Scope.

Using Docker Compose#

The easiest way to use and set up the Submodel Registry is Docker Compose.

The minimal configuration includes three services:

  1. PostgreSQL

  2. BaSyx Configuration Service (Go), which initializes the database

  3. BaSyx Submodel Registry (Go)

services:
  postgres:
    image: postgres:18
    container_name: postgres_basyx
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin123
      POSTGRES_DB: basyxTestDB
    command: ["postgres", "-c", "listen_addresses=*"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U admin -d basyxTestDB"]
      interval: 10s
      timeout: 5s
      retries: 5

  basyx_configuration:
    container_name: basyx_configuration
    image: eclipsebasyx/basyxconfigurationservice-go:latest
    pull_policy: always
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=admin123
      - POSTGRES_DBNAME=basyxTestDB
      - POSTGRES_MAXOPENCONNECTIONS=50
      - POSTGRES_MAXIDLECONNECTIONS=25
      - POSTGRES_CONNMAXLIFETIMEMINUTES=5
      - POSTGRES_CONNMAXIDLETIMEMINUTES=0
    depends_on:
      postgres:
        condition: service_healthy

  submodel_registry:
    container_name: submodel_registry
    image: eclipsebasyx/submodelregistry-go:latest
    pull_policy: always
    environment:
      - SERVER_PORT=8083
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=admin123
      - POSTGRES_DBNAME=basyxTestDB
    ports:
      - "8083:8083"
    depends_on:
      basyx_configuration:
        condition: service_completed_successfully

docker-compose.yml including PostgreSQL 18, the BaSyx Configuration Service, and BaSyx Go Submodel Registry

Use the same image tag for every BaSyx Go service sharing this database, including the Configuration Service. For reproducible deployments, replace latest with the same concrete BaSyx version tag for all of these services. Alternatively, pin each service image to the corresponding immutable image digest from the same release. The latest tag is mutable and advances when a new release is published.

Start and Check the Registry#

Warning

This minimal local Compose setup does not declare a named PostgreSQL volume. An image-created anonymous volume is not automatically reused after docker compose down, so recreating the containers can make previously stored data appear to be lost. Add a correctly mounted named volume before storing persistent data, and migrate existing data explicitly rather than expecting a new volume declaration to copy it. See Persistent State.

The services can be started by running the following command in the directory of the compose file:

docker compose up -d

The Configuration Service is a one-time initialization/migration job. An exit code of 0 is expected. The Submodel Registry starts only after that job completes successfully.

Once the Registry is ready, check its health:

curl -i http://localhost:8083/health

In Windows PowerShell, use curl.exe instead of curl to invoke curl rather than the PowerShell alias. Expect HTTP 200 with {"status":"UP"}. Open Swagger UI, then follow Using the Submodel Registry to register your first descriptor.

The example uses port 8083 and an empty context path. If server.contextPath is configured, include it in health, Swagger, and API URLs. For example, SERVER_CONTEXTPATH=/api/v3 makes the health URL http://localhost:8083/api/v3/health and Swagger URL http://localhost:8083/api/v3/swagger.

Security Configuration#

The local Compose example does not enable authorization and is not a secured deployment. To enable OIDC-based ABAC, set ABAC_ENABLED=true, mount the access-rule and OIDC trust-list files, and configure their container paths. When ABAC_POLICY_FILE_IMPORT is omitted, the effective import mode is if_missing, so editing a mounted policy file and restarting does not replace an active policy already stored in PostgreSQL. See OIDC and ABAC Configuration and Security Files before exposing the service.

The standalone Submodel Registry also supports experimental relationship-based access control (ReBAC). ReBAC is disabled by default, requires OIDC and ABAC, and can be enabled with REBAC_ENABLED=true. For ReBAC-covered Registry routes, an authenticated request is allowed when either ABAC or ReBAC grants access; anonymous requests and endpoints outside those routes remain ABAC-only. See Relationship-Based Access Control for configuration and access-management details.

Using BaSyx Go Components without Docker#

If you need to run the Submodel Registry without Docker, build the binary from source for your target platform.

Warning

Published BaSyx container images provide a ready-to-run distribution of the component. The Compose file above is intentionally minimal and unsecured; it is not a complete production deployment. Add the persistence, access control, networking, monitoring, backup, and operational controls required by your environment before using it in production.

Prerequisites#

  • Go at the version declared by the selected release’s go.mod.

  • PostgreSQL 16 or newer, initialized by a Configuration Service built from the same source revision as the HTTP service.

  • Git

Cloning the Repository#

Download the source code:

git clone https://github.com/eclipse-basyx/basyx-go-components
git -C basyx-go-components checkout RELEASE_TAG

Replace RELEASE_TAG with the stable release you intend to build. Initialize PostgreSQL using the Configuration Service and database schema files from the same checkout.

Building the Binary#

Change to the Submodel Registry service directory:

cd basyx-go-components/cmd/submodelregistryservice

Linux / macOS#

Build the executable with:

go build -o submodelregistryservice

Windows#

Build the executable with the .exe extension:

go build -o submodelregistryservice.exe

Running the Service#

Before running the service, ensure PostgreSQL is available and that the BaSyx database schema has already been initialized by the BaSyx Configuration Service. Configure the PostgreSQL connection through environment variables or the provided config.yaml.

Linux / macOS#

Run the service with:

./submodelregistryservice -config ./config.yaml

Windows PowerShell#

Run the service with:

.\submodelregistryservice.exe -config .\config.yaml

The Submodel Registry does not initialize the database schema itself. Database initialization and migrations are handled by the BaSyx Configuration Service.