Configure the server
Configuration is read at startup. After changing a setting, recreate or restart the affected service so it reads the new environment.
Know where a setting is applied
The repository's .env supplies Compose interpolation values. A variable reaches the container only when the Compose service forwards it through environment or another explicit mechanism.
A standalone Node process does not automatically load .env. Supply its environment directly. The standard application image starts the server; it does not run migrations automatically.
For the local stack, this example changes the published port and permitted browser origin:
ULDA_SERVER_PORT=3001
CORS_ORIGINS=http://localhost:5173
Apply it after the stack has been initialized:
docker compose up -d --no-build server
The application then remains on port 3000 inside the container and is published on loopback port 3001. The production recipe uses a separate Compose file; keep that file selection on subsequent commands.
Network and application
| Setting | Default | Purpose |
|---|---|---|
SERVER_HOST | 0.0.0.0 | Address inside the application's network namespace. |
SERVER_PORT | 3000 | Application HTTP port. |
CORS_ORIGINS | http://localhost:3000 | Comma-separated exact browser origins. |
LOG_LEVEL | info | debug, info, warn or error. |
In Compose, ULDA_PUBLISH_ADDRESS defaults to 127.0.0.1 and controls the host binding. The two supplied recipes set the container's bind address and port explicitly.
Browser origins include the scheme and port. CORS does not authenticate a user or authorize access to a resource. Remote clients need an operator-provided HTTPS/WSS endpoint.
Connect PostgreSQL
Supply standard PostgreSQL environment variables:
PGHOST=operator-postgres
PGPORT=5432
PGDATABASE=ulda
PGUSER=ulda_runtime
PGPASSWORD_FILE=/run/secrets/db_password
This example describes the container environment. The supplied Compose recipe selects each service's role and mounts its password file for you.
Alternatively, configure a protected DATABASE_URL. Do not combine PGPASSWORD_FILE with PGPASSWORD, DATABASE_URL or PGSERVICE. File secrets are read at startup; changing a file does not rotate a PostgreSQL account password.
| Setting | Default | Purpose |
|---|---|---|
DATABASE_POOL_MAX | 10 | Maximum pooled connections; the migration job uses 2. |
DATABASE_CONNECTION_TIMEOUT_MS | 5000 | Connection establishment and pool checkout. |
DATABASE_IDLE_TIMEOUT_MS | 30000 | Unused pooled connections. |
DATABASE_STATEMENT_TIMEOUT_MS | 10000 | PostgreSQL statement timeout. |
DATABASE_LOCK_TIMEOUT_MS | 5000 | PostgreSQL lock wait timeout. |
DATABASE_IDLE_IN_TRANSACTION_TIMEOUT_MS | 10000 | Idle transaction timeout. |
SQL timeouts are not client write receipts or proof of rollback after a lost response. See operations.
Keep the SDK profile compatible
The documented SDK profile uses compactV1, N = 5, SHA-256, 256-bit origin blocks and a four-byte age.
ULDA_CORE_VERSION is configuration metadata; changing it does not install another Core package. The Hello handshake does not negotiate profile or capacity settings. The SDK can use both X and S resources, so the server's ULDA_MODE metadata is not a rule that every resource must use one mode.
Size the deployment
Server admission budgets bound work; they do not promise throughput.
| Setting | Default |
|---|---|
MAX_CONNECTIONS | 1,000 |
MAX_RESOURCE_BYTES | 64 MiB |
MAX_TRANSFER_BYTES | 128 MiB |
MAX_STAGED_BYTES | 256 MiB |
MAX_SUBSCRIPTIONS_PER_SOCKET | 32,768 |
Environment values for byte limits are integers in bytes. Raising a server budget does not raise the SDK's own limits. In particular, application JSON remains limited to 1 MiB per content in SDK 1.1.0.
The SDK endpoint caps a witness at 167 bytes and an Engine.IO frame at 1,100,000 bytes, even when the general server settings are larger. The supplied Compose files do not forward MAX_WITNESS_BYTES or MAX_SOCKET_MESSAGE_BYTES from .env; changing those requires an explicit override.
Use admission limits for the full budget table and accounting rules. The source configuration reference also lists accepted environment ranges.