Setting Up the AAS Repository#

The configuration below provides a minimal standalone deployment.

Note

For a standalone AAS Repository 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 AAS Repository is Docker Compose.

The minimal configuration includes three services:

  1. PostgreSQL

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

  3. BaSyx AAS Repository (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

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

docker-compose.yml including PostgreSQL 18, the BaSyx Configuration Service, and BaSyx Go AAS Repository

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 Repository#

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.

Save the example as docker-compose.yml, then run:

docker compose up -d

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

Once the Repository is ready, check its health:

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

Expect HTTP 200 with {"status":"UP"}. Open Swagger UI to explore the API. To help you with the first steps using the repository, follow Using the AAS Repository.

Include any configured context path in every URL. For example, SERVER_CONTEXTPATH=/api/v3 makes the health URL http://localhost:8084/api/v3/health and Swagger URL http://localhost:8084/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 AAS Repository 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 Repository routes, an authenticated request is allowed when either ABAC or ReBAC grants access; anonymous requests and endpoints outside those routes remain ABAC-only. In particular, $history, $recent-changes, and event feed endpoints remain ABAC-only. If multiple ReBAC-capable BaSyx services share the same database, enable ReBAC consistently across them. Services running without ReBAC do not apply ReBAC grants or ownership semantics. See Relationship-Based Access Control for configuration and access-management details.

Using BaSyx Go Components without Docker#

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

Published BaSyx container images provide a ready-to-run distribution of the service. The minimal Compose example above is intentionally unsecured and is not, by itself, a production-ready deployment configuration.

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 AAS Repository service directory:

cd basyx-go-components/cmd/aasrepositoryservice

Linux / macOS#

Build the executable with:

go build -o aasrepositoryservice

Windows#

Build the executable with the .exe extension:

go build -o aasrepositoryservice.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:

./aasrepositoryservice -config ./config.yaml

Windows PowerShell#

Run the service with:

.\aasrepositoryservice.exe -config .\config.yaml

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