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
8090available
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.