#DocumentDB Deployment

This page covers DocumentDB on PostgreSQL, including Azure DocumentDB. To run directly on PostgreSQL, without the MongoDB wire protocol, see PostgreSQL Deployment.

The DocumentDB path stores data through the MongoDB wire protocol. PostgreSQL is reached through DocumentDB, an open-source engine that provides that 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.