Setting Up the AAS Environment#

This setup runs the latest AAS Environment and Configuration Service images with PostgreSQL 18. It exposes one application URL, http://localhost:8090, and is sufficient for the complete first-use walkthrough. No separate Registry, Discovery, or UI container is required.

Review the version distinctions before mixing images or source builds. For an existing database, do not treat startup as an upgrade procedure: follow the existing-database guidance first.

Prerequisites and Security Posture#

  • Docker with Docker Compose

  • host port 8090 available

Warning

This local example explicitly sets ABAC_ENABLED=false. Its APIs accept unauthenticated requests and must not be exposed to an untrusted network. Configure and verify Runtime Security before using this topology outside a trusted development environment.

Compose Configuration#

Save the following as docker-compose.yml:

services:
  postgres:
    image: postgres:18
    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
    volumes:
      - aas_environment_postgres:/var/lib/postgresql

  basyx_configuration:
    image: eclipsebasyx/basyxconfigurationservice-go:latest
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin123
      POSTGRES_DBNAME: basyxTestDB
    depends_on:
      postgres:
        condition: service_healthy

  aas_environment:
    image: eclipsebasyx/aasenvironment-go:latest
    environment:
      SERVER_PORT: 5004
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin123
      POSTGRES_DBNAME: basyxTestDB
      GENERAL_AASREGISTRYINTEGRATION: "true"
      GENERAL_SUBMODELREGISTRYINTEGRATION: "true"
      GENERAL_EXTERNALURL: http://localhost:8090
      ABAC_ENABLED: "false"
    ports:
      - "8090:5004"
    depends_on:
      basyx_configuration:
        condition: service_completed_successfully

volumes:
  aas_environment_postgres:

The database health check prevents initialization from starting too early. The Configuration Service initializes or migrates the schema as a one-shot job, and the AAS Environment starts only after that job exits successfully. Both Registry synchronization flags are enabled because the usage walkthrough verifies generated AAS and Submodel descriptors. GENERAL_EXTERNALURL matches the host URL clients use, so those descriptors advertise reachable endpoints.

Do not add GENERAL_DISCOVERYINTEGRATION: the AAS Environment executable forces Discovery integration on. The three services above are the complete topology for this walkthrough.

Optional Startup Preconfiguration#

The AAS Environment can import AAS data automatically during startup. Set GENERAL_AAS_PRECONFIG_PATHS to a comma-separated list of files or directories. Directories are searched recursively for .aasx, .json, and .xml files.

For example, add this to the AAS Environment service’s environment settings and mount the referenced paths into the container:

GENERAL_AAS_PRECONFIG_PATHS: /data/aas,/data/initial.aasx

The HTTP server can accept connections while preconfiguration is still running, but /health returns HTTP 503 until processing finishes. Wait for /health to return HTTP 200 before sending normal application traffic.

Start and Check Readiness#

Start the project:

docker compose up -d

The Configuration Service container completing with exit code 0 is expected. If it fails against a previously used database, inspect its logs and follow the existing-database guidance rather than deleting persistent data.

Wait until the Environment is ready:

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

Continue when the response is HTTP 200 with {"status":"UP"}. Swagger UI is available at http://localhost:8090/swagger. Then follow Using the AAS Environment.

Persistent State and Stopping#

The named volume aas_environment_postgres stores PostgreSQL 18 data at /var/lib/postgresql. docker compose stop stops the containers and docker compose down removes the containers and network while retaining the named volume. A later docker compose up -d reuses it. docker compose down -v also deletes the volume and its stored AASs, Submodels, Concept Descriptions, descriptors, Discovery mappings, and configuration state.

Warning

Do not run docker compose down -v when the data must be retained. Adding or renaming a volume later does not migrate the old database. See Persistent State for lifecycle and backup considerations.

For a larger topology with automatic AASX preconfiguration and a Web UI, see the BaSyx Minimal Example. If that example uses SNAPSHOT BaSyx image tags, replace them with latest to follow the newest stable release, or pin a concrete release tag or image digest for a reproducible deployment.