Welcome to the BaSyx Go project! This guide is designed to help new developers onboard quickly, understand the architecture, and contribute effectively.
Note
We also provide a wiki at https://wiki.basyx.org with a extensive user and developer documentation.
- BaSyx Go Components
- Table of Contents
- 1. Project Overview
- 2. Architecture Overview
- 3. Setup & Installation
- 4. Environment Variables & Configuration
- 5. Code Style & Conventions
- 6. Module Structure
- 7. Common Workflows
- 8. API Usage
- 9. Contribution Guidelines
- 10. Repository Automation
- 11. Security & Supply Chain Verification
- 12. Troubleshooting & Error Reference
- 13. Glossary of Terms & Abbreviations
- Database Schema
- Frequently Asked Questions
- Further Reading
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.
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.
- Go >= 1.26.5
- Docker & Docker Compose
- PostgreSQL (for local development)
- Clone the repository:
git clone https://github.com/eclipse-basyx/basyx-go-components.git cd basyx-go-components - Install dependencies:
go mod tidy
- 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
- Run integration tests:
go test -v ./internal/submodelrepository/integration_tests - Use Docker Compose for multi-service setup:
To run BaSyx with distinct PostgreSQL writer and streaming-standby reader endpoints, see the PostgreSQL read replica example.
docker compose -f examples/BaSyxMinimalExample/docker-compose.yml up
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.
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.
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: 0Or 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=0All 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: 16777216uploadMaxSizeBytes 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 /uploadPUT /shells/{aasIdentifier}/asset-information/thumbnailPUT /shells/{aasIdentifier}/submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/attachmentPUT /submodels/{submodelIdentifier}/submodel-elements/{idShortPath}/attachment
For aasenvironmentservice, startup preconfiguration can import AAS files automatically:
general:
aasPreconfigPaths:
- ./examples/BaSyxMinimalExample/aas
- ./myDevice.aasxOr via environment variable:
GENERAL_AAS_PRECONFIG_PATHS=./examples/BaSyxMinimalExample/aas,./myDevice.aasxEach 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.
- 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
cmd/- Service entry points, configs, Dockerfilescmd/*/openapi.yaml- Service OpenAPI specifications and API contractsinternal/- Core business logic, persistence, integration testspkg/- Generated Go server stubs and reusable service packagesexamples/- Minimal working examples, Docker Compose setupsdocu/- Documentation, error explanations, security notesdocu/basyx-database-wiki/- Database schema documentation, includingbasyxconfigurationserviceschema-version and clean/dirty state behavior
See structure.md and related files for details on each module.
- Build and run services:
go run ./cmd/<service>/main.go -config ./cmd/<service>/config.yaml
- Use VSCode launch scripts in
.vscode/launch.jsonfor debugging
- Run all Go package tests:
go test -v ./... - Run integration tests for a component:
go test -v ./internal/<component>/integration_tests
- Run linter:
bash scripts/lint.sh
- 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 partfile) - 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 - AAS v3.2 history and recent changes: user guide and runtime notes
- See structure_cmd.md for details
- 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
- 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
- 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.
- See docu/errors.md for common error scenarios and solutions
- For security and authorization, see docu/security/REGISTRY_SECURITY.md
- 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.
See basyx-database-wiki and sql_examples for details on tables, relationships, and large object handling.
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
For any questions, open an issue or contact the maintainers.