Use an External PostgreSQL Database¶

TestGen stores its application metadata — projects, connections, profiling results, test definitions, and run history — in a PostgreSQL database. By default, the installer runs this database as a PostgreSQL container alongside the application.

For production deployments, DataKitchen recommends pointing TestGen at a dedicated PostgreSQL server instead. A separate database server lets you manage backups, high availability, and version upgrades independently of the application.

The server can be either:

A PostgreSQL instance on the same virtual machine as TestGen.
A managed PostgreSQL service, such as Amazon RDS, Azure Database for PostgreSQL, or Google Cloud SQL.

Note

Choose the database location before installing. TestGen does not migrate metadata between databases, so switching from the container database to an external server after install means starting over with an empty database.

Prerequisites¶

Request access to the private enterprise Docker image from your DataKitchen representative.
To handle enterprise workloads, install TestGen on a Linux virtual machine with at least 4 CPUs, 16 GB memory, and 100 GB disk space, for example, t3.xlarge on Amazon EC2, c4-standard-4 on Google Compute Engine, or B4ms on Azure Virtual Machines.
Install the following software, and verify that the versions are supported.

Software	Supported versions	Command to check version
Python 3	3.9+	`python3 --version`
Docker + Docker Compose	Docker: 27+ Compose: 5.0+	`docker -v` `docker compose version`

A running PostgreSQL server, version 14 or later, reachable from the machine where TestGen will run.
An administrative PostgreSQL account that can create roles.

Create the TestGen database role¶

Connect to the PostgreSQL server with an administrative account and create a login role for TestGen.

CREATE ROLE testgen WITH LOGIN PASSWORD '<postgres password>' CREATEDB CREATEROLE;

The CREATEDB and CREATEROLE privileges are required: on first start, TestGen creates its datakitchen database, the testgen schema, and two limited-access roles (testgen_execute and testgen_report) used by the application.

Note

On managed services such as Amazon RDS or Azure Database for PostgreSQL, grant the equivalent role membership instead of CREATEROLE superuser-style privileges — for example, on RDS run GRANT rds_superuser TO testgen; after creating the role, or grant the testgen role to your master user so it can create the additional roles.

Allow connections from the TestGen container¶

How TestGen reaches the database depends on where the server runs.

Managed cloud servicePostgreSQL on the same VM

No PostgreSQL server configuration is needed. Make sure that:

The service's network rules (security group, firewall, or virtual network rules) allow inbound connections from the TestGen machine on the PostgreSQL port (5432 by default).
You note the server's endpoint hostname for the install step.

The TestGen container reaches a database on the host through the Docker bridge gateway, so the server must listen on that interface and accept the connection. Edit the PostgreSQL configuration files (paths shown are for PostgreSQL 16 on Ubuntu; adjust the version directory for your install).

In /etc/postgresql/16/main/postgresql.conf, set listen_addresses to include localhost and the Docker bridge gateway address (172.17.0.1 is the default Docker bridge).
```
listen_addresses = 'localhost, 172.17.0.1'
```
In /etc/postgresql/16/main/pg_hba.conf, add a line under # IPv4 local connections to allow password-authenticated connections from the Docker bridge subnet.
```
host    all             all             172.17.0.0/16           scram-sha-256
```
Restart PostgreSQL to apply the changes.
```
systemctl restart postgresql
```

Install TestGen against the external database¶

To use an external database, you supply your own docker-compose.yml instead of letting the installer generate one. When a compose file already exists in the install directory, the installer reuses it.

Log in to Docker with the credentials provided by your DataKitchen representative.
```
docker login -u <username> -p <password>
```
Create and navigate to a new install directory, for example, "/testgen".

In the install directory, create a docker-compose.yml file with the following contents.

name: dataops-testgen

x-common-variables: &common-variables
  TESTGEN_USERNAME: <UI login username>
  TESTGEN_PASSWORD: <UI login password>
  TG_DECRYPT_SALT: <random string>
  TG_DECRYPT_PASSWORD: <random string>
  TG_JWT_HASHING_KEY: <base64-encoded random string>
  TG_METADATA_DB_HOST: <postgres host>
  TG_METADATA_DB_PORT: "5432"
  TG_METADATA_DB_USER: testgen
  TG_METADATA_DB_PASSWORD: <postgres password>
  TG_INSTANCE_ID: <instance name>
  TG_UI_BASE_URL: <UI base URL>
  TG_BASE_URL: <API base URL>

services:
  engine:
    image: datakitchen/dataops-testgen-enterprise:v5
    container_name: testgen
    restart: unless-stopped
    environment: *common-variables
    volumes:
      - testgen_data:/var/lib/testgen
    ports:
      - 8501:8501
      - 8530:8530
    extra_hosts:
      - host.docker.internal:host-gateway

volumes:
  testgen_data:

Replace the placeholders.

Placeholder	Value
`TESTGEN_USERNAME`, `TESTGEN_PASSWORD`	Username and password for the initial system administrator account. After installing, sign in with these credentials to create accounts for your team. This account has no special status — once other system administrators exist, any of them can remove it if it is no longer needed.
`TG_DECRYPT_SALT`, `TG_DECRYPT_PASSWORD`	Random strings used to encrypt stored connection credentials.
`TG_JWT_HASHING_KEY`	A base64-encoded random string used to sign session tokens.
`TG_METADATA_DB_HOST`	The PostgreSQL host. For a server on the same VM, use `host.docker.internal`, not `localhost`. For a managed service, use its endpoint hostname.
`TG_METADATA_DB_PORT`	The PostgreSQL port. Defaults to `5432`.
`TG_METADATA_DB_USER`, `TG_METADATA_DB_PASSWORD`	The role and password created in Create the TestGen database role.
`TG_INSTANCE_ID`	A name that identifies this TestGen instance.
`TG_UI_BASE_URL`	The URL used to access the UI, for example, `http://<host>:8501`.
`TG_BASE_URL`	The externally reachable URL for the API and MCP server, for example, `http://<host>:8530`.

Download the latest version of dk-installer into the same directory.

curl -o dk-installer.py 'https://raw.githubusercontent.com/DataKitchen/data-observability-installer/main/dk-installer.py'

Run the install command. Because a docker-compose.yml is present, the installer uses it instead of generating one with a database container.
```
python3 dk-installer.py tg install
```
When the install completes, verify that the UI is accessible at the TG_UI_BASE_URL you configured and that you can log in with the credentials from the terminal output.

Tip

To enable HTTPS, configure email notifications, or set up single sign-on, add the corresponding environment variables under the x-common-variables section. See Configure HTTPS, Configure Email Server, and Configure SSO Authentication.