basyx-go-components

README

BaSyx Go Components

Welcome to the BaSyx Go project! This guide is designed to help new developers onboard quickly, understand the architecture, and contribute effectively.

See the changelog for release changes and upgrade considerations.

[!NOTE] We also provide a wiki at https://wiki.basyx.org with a extensive user and developer documentation.

Table of Contents

• BaSyx Go Components
  • Changelog
  • Table of Contents
  • 1. Project Overview
  • 2. Architecture Overview
  • 3. Setup & Installation
    • Prerequisites
    • Steps
  • 4. Environment Variables & Configuration
    • Database Initialization
    • Logging
    • OpenTelemetry Tracing
  • 5. Code Style & Conventions
  • 6. Module Structure
  • 7. Common Workflows
    • Build & Run
    • Test
    • Lint
  • 8. API Usage
  • 9. Contribution Guidelines
  • 10. Repository Automation
    • Create a Release
  • 11. Security & Supply Chain Verification
  • 12. Troubleshooting & Error Reference
  • 13. Glossary of Terms & Abbreviations
  • Database Schema
  • Frequently Asked Questions
  • Further Reading

---

1. Project Overview

BaSyx Go Components is an open-source implementation of the Eclipse BaSyx framework in Go, providing Asset Administration Shell (AAS) API components like registries, repositories, and more. The project is modular, scalable, and designed for industrial digital twin scenarios.

2. Architecture Overview

The project is composed of DB-backed microservices for AAS and Submodel registries, AAS and Submodel repositories, AAS Environment, Discovery, Digital Twin Registry, AASX file server, Concept Description Repository, Company Lookup, and DPP API. The BaSyx Configuration Service initializes and migrates the PostgreSQL schema, and historyevidenceverifier supports operational history-evidence checks. Security is enforced via OIDC and ABAC middleware. See docu/security/README.md for a detailed flow and architecture diagram.

3. Setup & Installation

Prerequisites

• Go >= 1.27.0
• Docker & Docker Compose
• PostgreSQL (for local development)

Steps

1. Clone the repository:

   git clone https://github.com/eclipse-basyx/basyx-go-components.git
   cd basyx-go-components
   

2. Install dependencies:

   go mod tidy
   

3. Start services (example):

   go run ./cmd/basyxconfigurationservice/main.go -config ./cmd/basyxconfigurationservice/config.yaml -databaseSchema ./database/base.sql -customPatchPath ./database/patches
   go run ./cmd/submodelrepositoryservice/main.go -config ./cmd/submodelrepositoryservice/config.yaml
   

4. Run integration tests:

   go test -v ./internal/submodelrepository/integration_tests
   

5. Use Docker Compose for multi-service setup:

   docker compose -f examples/BaSyxMinimalExample/docker-compose.yml up
   

   To run BaSyx with distinct PostgreSQL writer and streaming-standby reader endpoints, see the PostgreSQL read replica example.

4. Environment Variables & Configuration

Database Initialization

DB-backed BaSyx services expect the shared PostgreSQL schema to be initialized before startup. Run basyxconfigurationservice once against the target database before starting repository, registry, discovery, or environment services. The configuration service loads database/base.sql, applies versioned patches from database/patches, and records the schema version and schema state in basyxsystem. Runtime services validate that the schema state is clean and that the version matches during startup; they fail fast if the configuration service has not completed successfully. If a schema patch fails during execution, the database is marked dirty until the configuration service completes a compatible patch run successfully.

For operator-facing setup guidance, see the BaSyx wiki

The basyxconfigurationservice image should use the same BaSyx version or build revision as the DB-backed runtime components in the same setup. This is especially important when using mutable image tags. The latest tag tracks the newest release, and the SNAPSHOT tag tracks the current main-branch snapshot; both tags may point to different image digests over time. For reproducible deployments, pin a concrete version tag, commit/SNAPSHOT tag, or image digest instead.

If a setup uses mutable tags and pulls images on every start or restart, include basyxconfigurationservice in the deployment and run it before the DB-backed components. Otherwise a freshly pulled runtime component may expect a newer schema version than the database currently contains, causing startup validation to fail.

Logging

All commands support logging.format (text or json) and logging.level (debug, info, warn, or error), with LOGGING_FORMAT and LOGGING_LEVEL environment overrides. Diagnostic records are written to stderr. See the logging guide for the output contract and Docker, Kubernetes, systemd, and Loki collection guidance.

OpenTelemetry Tracing

All HTTP services support optional environment-driven OpenTelemetry tracing, W3C context extraction, delegated-operation propagation, and structured-log correlation. Tracing is disabled by default. See the telemetry guide for configuration and the observability example for a Collector, Tempo, Alloy, Loki, and Grafana setup.

Configuration is managed via YAML files in cmd/<service>/config.yaml and environment variables. Key variables include database connection settings (see docu/errors.md for troubleshooting):

logging:
    format: text
    level: info

server:
    readHeaderTimeoutSeconds: 15
    readTimeoutSeconds: 300
    writeTimeoutSeconds: 300
    idleTimeoutSeconds: 60
    shutdownTimeoutSeconds: 10

postgres:
    # Either set dsn or the individual connection fields below. Do not mix them.
    # dsn: postgres://user:password@db:5432/basyx?sslmode=require
    host: localhost
    port: 5432
    user: postgres
    password: postgres
    dbname: basyx
    sslmode: disable
    sslcert: ""
    sslkey: ""
    sslrootcert: ""
    connectTimeoutSeconds: 0
    applicationName: ""
    fallbackApplicationName: ""
    searchPath: ""
    options: ""
    timezone: ""
    maxOpenConnections: 50
    maxIdleConnections: 25
    connMaxLifetimeMinutes: 5
    connMaxIdleTimeMinutes: 0

    # Optional read-only endpoint for eligible reads in PostgreSQL-backed HTTP services.
    # Omit this block to reuse the writer pool.
    # reader:
    #     host: postgres-reader
    #     port: 5432
    #     user: postgres
    #     password: postgres
    #     dbname: basyx
    #     sslmode: require
    #     maxOpenConnections: 50
    #     maxIdleConnections: 25
    #     connMaxLifetimeMinutes: 5
    #     connMaxIdleTimeMinutes: 0

Or via .env:

SERVER_READ_HEADER_TIMEOUT_SECONDS=15
SERVER_READ_TIMEOUT_SECONDS=300
SERVER_WRITE_TIMEOUT_SECONDS=300
SERVER_IDLE_TIMEOUT_SECONDS=60
SERVER_SHUTDOWN_TIMEOUT_SECONDS=10

# Either set POSTGRES_DSN or the individual connection variables below. Do not mix them.
# POSTGRES_DSN=postgres://user:password@db:5432/basyx?sslmode=require
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DBNAME=basyx
POSTGRES_SSLMODE=disable
POSTGRES_SSLCERT=
POSTGRES_SSLKEY=
POSTGRES_SSLROOTCERT=
POSTGRES_CONNECTTIMEOUTSECONDS=0
POSTGRES_APPLICATIONNAME=
POSTGRES_FALLBACKAPPLICATIONNAME=
POSTGRES_SEARCHPATH=
POSTGRES_OPTIONS=
POSTGRES_TIMEZONE=
POSTGRES_MAXOPENCONNECTIONS=50
POSTGRES_MAXIDLECONNECTIONS=25
POSTGRES_CONNMAXLIFETIMEMINUTES=5
POSTGRES_CONNMAXIDLETIMEMINUTES=0

# Optional reader connection. Set either POSTGRES_READER_DSN or the individual
# reader connection variables. Omit all reader variables to reuse the writer.
# POSTGRES_READER_DSN=postgres://user:password@postgres-reader:5432/basyx?sslmode=require
# POSTGRES_READER_HOST=postgres-reader
# POSTGRES_READER_PORT=5432
# POSTGRES_READER_USER=postgres
# POSTGRES_READER_PASSWORD=postgres
# POSTGRES_READER_DBNAME=basyx
# POSTGRES_READER_SSLMODE=require
# POSTGRES_READER_SSLCERT=
# POSTGRES_READER_SSLKEY=
# POSTGRES_READER_SSLROOTCERT=
# POSTGRES_READER_CONNECTTIMEOUTSECONDS=10
# POSTGRES_READER_APPLICATIONNAME=
# POSTGRES_READER_FALLBACKAPPLICATIONNAME=
# POSTGRES_READER_SEARCHPATH=
# POSTGRES_READER_OPTIONS=
# POSTGRES_READER_TIMEZONE=
# POSTGRES_READER_MAXOPENCONNECTIONS=50
# POSTGRES_READER_MAXIDLECONNECTIONS=25
# POSTGRES_READER_CONNMAXLIFETIMEMINUTES=5
# POSTGRES_READER_CONNMAXIDLETIMEMINUTES=0

All HTTP timeout values are in seconds and must be greater than zero. The legacy Viper-derived names such as SERVER_READTIMEOUTSECONDS still work; readable aliases with underscores and BASYX_ prefixes, such as BASYX_SERVER_READ_TIMEOUT_SECONDS, are also supported.

PostgreSQL pool limits apply to every service process or Kubernetes pod. Size the deployment so that the sum of maxOpenConnections across all replicas and database-backed services stays below PostgreSQL's usable connection budget, with capacity reserved for administration and migrations. The defaults are 50 open connections, 25 idle connections, and a five-minute connection lifetime. Zero uses the common default for these three values; when the default idle limit would exceed an explicitly smaller open limit, it is capped at the open limit. connMaxIdleTimeMinutes: 0 disables idle-time recycling. An explicitly configured idle limit greater than the open limit is rejected during startup.

All PostgreSQL-backed HTTP services support an optional postgres.reader connection with independent pool limits. Eligible repository, registry, discovery, company lookup, DPP, and AASX file reads use this endpoint, including the corresponding APIs hosted by the AAS Environment. Mutations, transaction work, schema checks, asynchronous jobs, authorization policy storage, upload staging, and reads that guard mutations remain on the writer. The Configuration Service and the history evidence command-line tooling are writer-only because they perform schema or mixed administrative work. Reader results are eventually consistent and can lag behind a successful write. Replica lag also applies to deletions and authorization-relevant attribute changes, so a reader may briefly return the preceding resource state; deployments requiring immediate revocation must keep affected reads on the writer or use replication guarantees that meet the required revocation window. Configuring a reader is an explicit acceptance of that behavior: startup fails when the configured reader is unavailable, and requests are not silently rerouted to the writer. Account for the writer and reader limits separately when calculating the total PostgreSQL connection budget.

Binary uploads and AASX package expansion are bounded independently:

general:
    uploadMaxSizeBytes: 134217728
    aasxMaxPartCount: 10000
    aasxMaxOPCMetadataSizeBytes: 16777216
    aasxMaxPartExpandedSizeBytes: 134217728
    aasxMaxTotalExpandedSizeBytes: 536870912
    aasxMaxThumbnailSizeBytes: 16777216

uploadMaxSizeBytes limits the uploaded file content for AASX packages, File element attachments, and thumbnails. Multipart metadata and framing use a separate bounded allowance, so a file whose content exactly matches the configured limit is accepted. The default 128 MiB file limit therefore accommodates common 50 MiB PDF attachments. The AASX limits constrain entry count, expanded OPC metadata, each expanded part, all expanded payload parts combined, and thumbnails respectively. The 512 MiB total expansion default allows a package to contain multiple large payload parts while the 128 MiB per-part limit continues to bound any single expanded file. All limits must be positive, and the total expanded limit must be greater than or equal to the per-part limit, which must be greater than or equal to the thumbnail limit.

AASX request bodies and generated specification parts use transaction-scoped PostgreSQL large objects for seekable staging; no writable local temporary directory is required. Package parts, attachments, thumbnails, and generated AASX output are streamed. The parsed AAS object model remains in memory because the current AAS SDK requires an in-memory model representation.

• POST /upload
• PUT /shells/{aasIdentifier}/asset-information/thumbnail
• PUT /shells/{aasIdentifier}/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/attachment
• PUT /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/attachment

For aasenvironmentservice, startup preconfiguration can import AAS files automatically:

general:
    aasPreconfigPaths:
        - ./examples/BaSyxMinimalExample/aas
        - ./myDevice.aasx

Or via environment variable:

GENERAL_AAS_PRECONFIG_PATHS=./examples/BaSyxMinimalExample/aas,./myDevice.aasx

Each configured source can be a file or directory. Directories are scanned recursively for .aasx, .json, and .xml files.

Upload and startup preconfiguration use the AAS 3.2 parsing stack. For backward compatibility, XML payloads with lower or equal AAS v3 namespace versions (for example https://admin-shell.io/aas/3/0) are adapted to the current namespace before parsing, and a warning is logged.

5. Code Style & Conventions

• Use Go modules (go.mod) for dependency management
• Follow GoDoc conventions (godoc_tips.md)
• Run the linter before submitting PRs:

  bash scripts/lint.sh
  

• Use //nolint:<linter> comments sparingly and explain why
• Auto-generated model files may not conform to all linter rules

6. Module Structure

• cmd/ - Service entry points, configs, Dockerfiles
• cmd/*/openapi.yaml - Service OpenAPI specifications and API contracts
• internal/ - Core business logic, persistence, integration tests
• pkg/ - Generated Go server stubs and reusable service packages
• examples/ - Minimal working examples, Docker Compose setups
• docu/ - Documentation, error explanations, security notes
• docu/basyx-database-wiki/ - Database schema documentation, including basyxconfigurationservice schema-version and clean/dirty state behavior

See structure.md and related files for details on each module.

7. Common Workflows

Build & Run

• Build and run services:

  go run ./cmd/<service>/main.go -config ./cmd/<service>/config.yaml
  

• Use VSCode launch scripts in .vscode/launch.json for debugging

Test

• Run all Go package tests:

  go test -v ./...
  

• Run integration tests for a component:

  go test -v ./internal/<component>/integration_tests
  

Lint

• Run linter:

  bash scripts/lint.sh
  

8. API Usage

• OpenAPI specs are in cmd/<service>/openapi.yaml
• Use generated server stubs and reusable API packages in pkg/
• Example endpoint: /submodels/{id}/submodel-elements/{idShort}/attachment
• AAS environment import endpoint: /upload (multipart/form-data with file part file)
• Supported upload media types: application/aasx+xml, application/aasx+json, application/asset-administration-shell+xml, application/asset-administration-shell+json, application/json, application/xml, text/xml
• Query fragment filters use existential parent-level evaluation by default. Set "$match": true explicitly when a request filter must be evaluated against the current fragment row. See the query language guide.
• AAS v3.2 history and recent changes: user guide and runtime notes
• See structure_cmd.md for details

9. Contribution Guidelines

• Fork the repository and create a feature branch
• Write clear commit messages and PR descriptions
• Add/update GoDoc comments for all exported code
• Run tests and linter before submitting
• Cover new features with integration tests
• Document public APIs in OpenAPI YAML files
• Add a changelog fragment for every notable user-visible or security-related change. Open a draft PR to obtain its number, install the CI version with go install github.com/miniscruff/changie@v1.26.0, then run changie new.
• Do not edit CHANGELOG.md directly. It is generated from the reviewed files under .changes/ during a release.

10. Repository Automation

• CI/CD pipelines run tests and linter on each PR
• Ensure your local environment matches CI versions (see linter.md)
• Use provided tasks in VSCode or CLI for build/test/lint automation

Create a Release

1. Open Actions → Release → Run workflow.
2. Enter a new tag such as v1.0.10.

The workflow batches the reviewed Changie fragments, commits the generated changelog to the current default branch, creates an annotated tag and a draft GitHub release, and starts the Docker/SBOM build and vulnerability scan. The draft is published automatically only after every release image is built, signed, attested, and its SBOM assets are attached. Rerunning the same version reconciles incomplete work without creating another release. Repository Actions must have permission to push the generated release commit to the default branch.

11. Security & Supply Chain Verification

• Security reporting policy: Eclipse BaSyx SECURITY.md
• Supply-chain trust model, signing, attestations, and SBOM verification: docu/security/SUPPLY_CHAIN_SECURITY.md
• Runtime security architecture (OIDC + ABAC): docu/security/README.md

Release and snapshot images are signed with Cosign keyless identity and include provenance and SBOM attestations. For full verification commands, see docu/security/SUPPLY_CHAIN_SECURITY.md.

12. Troubleshooting & Error Reference

• See docu/errors.md for common error scenarios and solutions
• For security and authorization, see docu/security/REGISTRY_SECURITY.md

13. Glossary of Terms & Abbreviations

• AAS: Asset Administration Shell – digital representation of assets
• Submodel: Modular part of an AAS
• SME: Submodel Element
• OIDC: OpenID Connect – authentication protocol
• ABAC: Attribute-Based Access Control
• OpenAPI: Specification for RESTful APIs

---

For further details, see the docs folder, the BaSyx wiki, and links above. If you encounter issues, please open an issue on GitHub or consult the error documentation.

Database Schema

See basyx-database-wiki and sql_examples for details on tables, relationships, and large object handling.

Frequently Asked Questions

Q: How do I add a new component?

• Add main.go in cmd/<COMPONENT_NAME>/main.go
• Implement the logic in internal/<COMPONENT_NAME>/
• Save and use OpenAPI specs in cmd/<COMPONENT_NAME>/openapi.yaml
• Add tests in internal/<COMPONENT_NAME>/integration_tests/

Q: How do I handle file attachments?

• Use the standardized File SME attachment and asset-information thumbnail endpoints.
• Internal uploads store /aasx/files/<opaque-token>/<safe-filename> in the model. This is an AASX package-part path, not a new HTTP endpoint.
• See the repository integration tests for upload/download examples.

Q: Where do I find API documentation?

• OpenAPI YAML files in cmd/*/openapi.yaml
• GoDoc for package-level documentation

Further Reading

• Eclipse BaSyx Documentation
• IDTA AAS Specification

---

For any questions, open an issue or contact the maintainers.