#PostgreSQL Deployment

The Enterprise Stack stores its data through the MongoDB wire protocol and has no native PostgreSQL driver. PostgreSQL is supported through DocumentDB, an open-source engine that provides the MongoDB wire protocol on top of PostgreSQL: PostgreSQL extensions plus a gateway. The API connects to the gateway, never to PostgreSQL directly.

The engine does not support retryable writes, which is why retryWrites=false is required. See Database configuration for what the profile controls.

#Prerequisites

Before you begin, ensure you have:

• An Enterprise Stack license, see Licensing. The API refuses to start without an active license.
• For the bundled container: Docker.
• For your own PostgreSQL: root access to the PostgreSQL host, a backup, and a maintenance window for a PostgreSQL restart. Check the DocumentDB Linux packages quick start for supported distributions and PostgreSQL versions.

#Option 1: Bundled DocumentDB Container

For evaluation and development. The Enterprise Stack Quickstart ships docker-compose-documentdb.yml, which runs the stack against the documentdb-local image:

docker compose -f docker-compose-documentdb.yml up

To run the image yourself, use a pinned tag, not latest, and wait for DocumentDB is ready in the logs:

docker run -d --name documentdb \
  -p 127.0.0.1:10260:10260 \
  -v documentdb-data:/data \
  ghcr.io/documentdb/documentdb/documentdb-local:{tag} \
  --username {username} \
  --password {password}

The image accepts plaintext connections by default. Usernames beginning with documentdb, citus, pg, or internal_role are reserved. Check the gateway before you start the API:

mongosh {host}:10260 \
  -u {username} \
  -p {password} \
  --authenticationMechanism SCRAM-SHA-256 \
  --eval 'db.runCommand({ ping: 1 })'

#Option 2: Your Own PostgreSQL

DocumentDB's Linux packages install the extensions and a gateway with the documentdb-setup wizard. The wizard adopts a PostgreSQL instance on the same host as the gateway; it does not support a remote PostgreSQL. The gateway itself can run as a standalone process or as a PostgreSQL background worker, see Components.

#Step 1: Add DocumentDB to PostgreSQL

Follow Adopt an existing PostgreSQL instance in Operating a package install. Check the same guide for whether in-place upgrades are supported, and pin the DocumentDB version you deploy. What matters for the Enterprise Stack:

• TLS with a matching name. The packaged gateway enforces TLS and serves a self-signed certificate by default. Replace it with a certificate whose subject alternative name is the host name the API will use, see Replace the self-signed certificate in the same guide.
• Network access. The API connects only to the gateway, on port 10260 by default, never to PostgreSQL. The gateway listens on all interfaces by default: firewall its port to the hosts that run the Enterprise Stack, see Before exposing it to a network in the same guide.

#Step 2: Create a Trust Store

The Java driver ignores tlsInsecure in the connection string, so the gateway certificate must be in a JKS trust store, even if it is self-signed:

echo | openssl s_client -connect {host}:10260 -servername {host} 2>/dev/null | openssl x509 > gateway.crt
keytool -importcert -noprompt \
  -alias documentdb-gateway \
  -file gateway.crt \
  -keystore documentdb-truststore.jks \
  -storetype JKS \
  -storepass {trustStorePassword}

#Configure database.conf

For your own PostgreSQL:

databaseType = mongodb

mongodb = {
    connectionString = "mongodb://{username}:{password}@{host}:10260/?directConnection=true&retryWrites=false&tls=true"
    database = "waltid-enterprise"

    profile = DOCUMENTDB_POSTGRES

    ssl = {
        enable = true
        trustStoreLocation = "/config/documentdb-truststore.jks"
        trustStorePassword = "{trustStorePassword}"
        invalidHostNameAllowed = false
    }
}

For the bundled container, which accepts plaintext, drop &tls=true from the connection string and set ssl = { enable = false }.

• Percent-encode special characters in the username and password.
• TLS settings are only read from the ssl block. Keep exactly one ssl block in the configuration.
• Set invalidHostNameAllowed = true only if the certificate name cannot match {host}.

The same values can be set as JVM overrides, for example -Dconfig.override.mongodb.profile=DOCUMENTDB_POSTGRES, see Docker deployment. The quickstart's docker-compose-documentdb-external.yml runs the stack against your own gateway.

#Start and Verify

A new database has no license state. Activate the license as described in Licensing. A license binds to one installation at a time.

On startup the API logs the selected profile:

Using database profile: DocumentDB (PostgreSQL engine)

#Next Steps

• Database configuration — all database.conf fields and profiles.
• Licensing — activate the license for the new database.
• Docker deployment — run the Enterprise Stack image.