Install Releem for PostgreSQL on Docker

Run the Releem Agent in a Docker container for PostgreSQL.

Prerequisites

Create the monitoring account and configure pg_stat_statements from PostgreSQL permissions, including query read access if you use the example below. Keep the extension available in postgres, which the Agent uses for its statistics connection. Install Docker, and make sure the Agent container can reach PostgreSQL. With Docker's default bridge network, 127.0.0.1 inside the Agent container does not identify a separate PostgreSQL container or the Docker host. For a remote connection, enable TLS on PostgreSQL and use the documented hostssl rule for the exact Agent source. Install Docker Compose only if you want to use the Compose method below. Choose a memory limit in MB for PostgreSQL; use 0 only when PostgreSQL can use the host's full memory budget.

Manual installation

Choose Docker or Docker Compose. Replace every bracketed value before starting the Agent.

Docker

Run the container with persistent configuration directories:

docker run -d --name releem-agent \
  -e RELEEM_API_KEY="[RELEEM_API_KEY]" \
  -e RELEEM_HOSTNAME="[SERVER_NAME]" \
  -e PG_HOST="[POSTGRESQL_HOST]" \
  -e PG_PORT="5432" \
  -e PG_SSL="true" \
  -e PG_USER="releem" \
  -e PG_PASSWORD="[MONITORING_PASSWORD]" \
  -e MEMORY_LIMIT="[MEMORY_LIMIT]" \
  -e RELEEM_QUERY_OPTIMIZATION="true" \
  --restart unless-stopped \
  -v /etc/postgresql/releem.conf.d/:/etc/postgresql/releem.conf.d/ \
  releem/releem-agent:[VERSION_FROM_DOCKER_HUB]

Check the startup log:

docker logs --tail=100 releem-agent

Docker Compose

Create compose.yaml:

services:
  releem-agent:
    image: "releem/releem-agent:[VERSION_FROM_DOCKER_HUB]"
    container_name: releem-agent
    environment:
      RELEEM_API_KEY: "[RELEEM_API_KEY]"
      RELEEM_HOSTNAME: "[SERVER_NAME]"
      PG_HOST: "[POSTGRESQL_HOST]"
      PG_PORT: "5432"
      PG_SSL: "true"
      PG_USER: "releem"
      PG_PASSWORD: "[MONITORING_PASSWORD]"
      MEMORY_LIMIT: "[MEMORY_LIMIT]"
      RELEEM_QUERY_OPTIMIZATION: "true"
    restart: unless-stopped
    volumes:
      - /etc/postgresql/releem.conf.d/:/etc/postgresql/releem.conf.d/

Start the Agent:

docker compose up -d
docker compose logs --tail=100 releem-agent

Use a version shown on Releem Agent tags on Docker Hub. Keep a Compose file containing credentials out of version control.

Connect the generated configuration to PostgreSQL

Complete this section if you want the PostgreSQL container to load configuration files generated by the Releem Agent. The Agent and PostgreSQL containers must use the same host directory.

1. Mount the host directory in the PostgreSQL service or container:

services:
  postgres:
    volumes:
      - /etc/postgresql/releem.conf.d/:/etc/postgresql/releem.conf.d/:ro

2. Add this line to the active postgresql.conf inside the database container. Preserve existing include entries and make sure PostgreSQL can read the directory and its files:

include_dir = '/etc/postgresql/releem.conf.d'

You can also use include_dir = 'conf.d' when you mount the same host directory at the conf.d directory relative to the active postgresql.conf.

3. Review the generated configuration, then reload or restart the PostgreSQL container during your approved maintenance window. The Agent does not control the database container's restart. Use the PostgreSQL configuration-error and effective-value checks in a database administrator session.

The shared directory receives a recommendation only when the Agent applies it, so it can be empty or hold a previous configuration. To apply a recommendation manually, extract the current file from the Agent container as described in manual application.

If you do not connect the generated configuration directory, add pg_stat_statements to shared_preload_libraries in the active PostgreSQL configuration and create the extension in postgres, as described in PostgreSQL permissions, so Releem can collect query data.

Restart the PostgreSQL container after changing shared_preload_libraries. Confirm that the settings are effective before relying on the related metrics or Query Optimization data.

Installer parameters

• PG_HOST, PG_PORT, PG_USER, and PG_PASSWORD configure the PostgreSQL connection. The RELEEM_PG_HOST, RELEEM_PG_PORT, RELEEM_PG_LOGIN, and RELEEM_PG_PASSWORD names are also accepted. PostgreSQL collection starts when the user and password are set; do not also set MySQL DB_USER and DB_PASSWORD for this Agent.
• PG_SSL / RELEEM_PG_SSL_MODE set to true use sslmode=require. They do not provide verify-full certificate and hostname verification. Set false only for an explicitly approved local connection without TLS; omission also disables SSL.
• RELEEM_API_KEY connects the Agent to your Releem account.
• RELEEM_HOSTNAME sets the server name displayed in the Dashboard.
• MEMORY_LIMIT limits the memory considered for PostgreSQL recommendations; 0 uses the host total.
• RELEEM_QUERY_OPTIMIZATION=true enables query collection. Remove the line for baseline monitoring only; review the query permissions before enabling it.

Expected result

After you start the Agent, the Dashboard should show Agent Status: Connected and current metrics or a current data timestamp.

Verify the installation

Confirm both the Agent connection and current metrics in the Dashboard. If either is missing, check the Agent logs. For an included recommendation, verify the effective PostgreSQL values after the required reload or restart.

Troubleshooting

Use Troubleshoot the Releem Agent. Check the monitoring credentials, database host and port, container networking, HBA source rule, and pg_stat_statements setup. If recommended settings are absent, check both containers' mounts and the active include path, then use the PostgreSQL recovery procedure. Correct the reported permission, network, or configuration issue before you re-run or restart the supported procedure.