Setting Up the AASX File Server#
The following local setup runs the AASX File Server with PostgreSQL and the BaSyx Configuration Service.
Note
For uploading, listing, and downloading AASX packages through Swagger UI, see the BaSyx AASX File Server Example.
Using Docker Compose#
The minimal setup contains PostgreSQL, the one-time BaSyx Configuration Service database initializer, and the AASX File Server:
services:
postgres:
image: postgres:18
container_name: postgres_basyx_aasx
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_aasx
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
aasx_file_server:
container_name: aasx_file_server
image: eclipsebasyx/aasxfileserver-go:latest
environment:
- SERVER_PORT=8087
- POSTGRES_HOST=postgres
- POSTGRES_PORT=5432
- POSTGRES_USER=admin
- POSTGRES_PASSWORD=admin123
- POSTGRES_DBNAME=basyxTestDB
ports:
- "8087:8087"
depends_on:
basyx_configuration:
condition: service_completed_successfully
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.
Warning
This local example uses demonstration credentials, disables access control, and does not define a persistent PostgreSQL volume. Recreating the database container can therefore make stored packages unavailable. Do not expose this setup to an untrusted network or use it unchanged for persistent data. See Persistent State before configuring a durable deployment.
Save the example as docker-compose.yml, then start it:
docker compose up -d
curl -i http://localhost:8087/health
The Configuration Service is expected to exit with code 0. A ready File Server returns HTTP 200 with {"status":"UP"}. Swagger UI is available at http://localhost:8087/swagger.
Configuration File#
The image contains a configuration file at /config/config.yaml. This representative configuration uses the Compose database and shows the release’s package limits:
server:
port: 8087
contextPath: ""
host: 0.0.0.0
postgres:
host: postgres
port: 5432
user: admin
password: admin123
dbname: basyxTestDB
maxOpenConnections: 50
maxIdleConnections: 25
connMaxLifetimeMinutes: 5
connMaxIdleTimeMinutes: 0
general:
uploadMaxSizeBytes: 134217728
aasxMaxPartCount: 10000
aasxMaxOPCMetadataSizeBytes: 16777216
aasxMaxPartExpandedSizeBytes: 134217728
aasxMaxTotalExpandedSizeBytes: 536870912
aasxMaxThumbnailSizeBytes: 16777216
Do not combine postgres.dsn with the individual connection fields. See General Configuration for the complete shared model and mounting guidance.
Environment Variables#
Environment variable |
Purpose |
|---|---|
|
HTTP listen port. The checked-in default is |
|
Optional prefix for every service route. |
|
Writer database connection. |
|
Alternative complete writer connection string. Do not mix it with the individual connection fields. |
|
Maximum writer-pool connections. Default: |
|
Optional read-replica connection. |
|
Maximum uploaded file content size. Default: |
|
Maximum package part count. Default: |
|
Maximum expanded OPC metadata size. Default: |
|
Maximum expanded size of one part. Default: |
|
Maximum total expanded package size. Default: |
|
Maximum expanded thumbnail size. Default: |
Omit the complete postgres.reader configuration to reuse the writer connection for reads. When a replica is configured, list and download operations may briefly be eventually consistent after an upload, replacement, or deletion.
Asynchronous Upload Profile#
Asynchronous package processing requires at least two writer-pool connections. Setting POSTGRES_MAXOPENCONNECTIONS=1 disables SSP-002 and leaves only the synchronous SSP-001 routes. Check GET /description for the SSP-002 profile before using /packages-async. The default writer-pool configuration in this example provides sufficient capacity.
The service limits concurrent asynchronous work. When no execution slot is available, POST /packages-async returns 429 Too Many Requests. Retry the submission later.
Security Configuration#
The Compose example is unsecured. The File Server supports OIDC authentication, ABAC authorization, and experimental ReBAC. To enable OIDC-based ABAC, set ABAC_ENABLED=true, mount an access-rule model and OIDC trust list, and configure their container paths. The effective default policy import mode is if_missing. See the oidc and abac and Security Files sections for setup details.
ReBAC is disabled by default, requires ABAC and a readable OIDC trust list, and can be enabled with REBAC_ENABLED=true. AASX packages and asynchronous uploads are covered by ReBAC. For authenticated callers on these routes, access can be granted by either ABAC or ReBAC; anonymous callers remain ABAC-only.
If multiple ReBAC-capable BaSyx services share the same database, enable ReBAC consistently across them. A service running without ReBAC ignores ReBAC grants, does not assign owners to resources it creates, and does not remove ReBAC grants for resources it deletes. See Relationship-Based Access Control for configuration and administration details.
When ABAC/OIDC security is enabled, every /packages-async submission, status request, and result request requires an authenticated caller. Use the same bearer-token identity throughout the workflow because operation handles are scoped to their owner. With access control disabled as in this local example, the asynchronous routes accept anonymous requests.
Running without Docker#
Use PostgreSQL initialized by a Configuration Service from the same release, then build the service from the release checkout:
git clone https://github.com/eclipse-basyx/basyx-go-components
git -C basyx-go-components checkout RELEASE_TAG
cd basyx-go-components/cmd/aasxfileserverservice
go build -o aasxfileserver
./aasxfileserver -config ./config.yaml
Replace RELEASE_TAG with the stable release you intend to build, and use the Configuration Service and SQL assets from that same checkout.
On Windows, build aasxfileserver.exe and run ./aasxfileserver.exe -config ./config.yaml in PowerShell. The File Server validates the initialized database schema and does not create it itself.