Enterprise Server: Container settings

The settings on this page can be passed in as environment variables into the pganalyze Enterprise Server container. Any change of these settings requires a container restart to read the new configuration.

Basic configuration

• DATABASE_URL: PostgreSQL server used for storing statistics information (required)
• LICENSE_KEY: License key provided to you by the pganalyze team (required)
• DOMAIN_NAME: Domain name where you are hosting the pganalyze app (optional, but recommended, and required for SSO)
• MAILER_URL: SMTP server used to send system emails, e.g. user invites (optional, recommended)
  • MAILER_URL can include username and password when the SMTP server requires authentication. For example, when connecting to a Microsoft Outlook server, you may need to use a URL like: smtp://myusername:mypassword@example.com:25
• MAILER_FROM: “From” address used to send system emails (optional, recommended if setting MAILER_URL)
• REDIS_URL: Redis server used for scale out architecture (optional, only needed when running Redis separately)
• SECRET_KEY_BASE: Secret key used to encrypt session cookies (optional, but required when running multiple web pods. See below for details)

An example configuration looks like this:

DATABASE_URL=postgres://myusername:mypassword@example.com:5432/mydatabase
LICENSE_KEY=KEYKEYKEY
DOMAIN_NAME=pganalyze.example.com
MAILER_URL=smtp://example.com:25
MAILER_FROM=pganalyze@example.com

SMTP / email configuration

In addition to the MAILER_URL and MAILER_FROM settings above, the following options allow you to control how pganalyze Enterprise Server connects to your SMTP server:

• MAILER_SSL: SSL/TLS mode for the SMTP connection (optional, default: auto)
  • tls - always require an SSL/TLS connection
  • starttls - require the STARTTLS protocol
  • none - don’t use SSL/TLS or STARTTLS
  • auto - auto-detect STARTTLS capability (default)
• MAILER_SSL_VERIFY_MODE: Whether to verify the SMTP server’s certificate. Set to none to skip verification (optional)
• MAILER_AUTHENTICATION: Authentication mechanism used with the SMTP server (optional, default: plain)
  • plain - sends the password in clear text (default)
  • login - sends the password base64 encoded
  • cram_md5 - sends the password using the CRAM-MD5 challenge/response mechanism
• MAILER_DOMAIN: Domain to send in the HELO command, when the mail server expects a specific value (optional)

An example SMTP configuration looks like this:

MAILER_URL=smtp://myusername:mypassword@example.com:25
MAILER_SSL=none
MAILER_SSL_VERIFY_MODE=none
MAILER_AUTHENTICATION=login
MAILER_DOMAIN=example.com
MAILER_FROM=pganalyze@example.com

SSL / TLS configuration

The web container runs an NGINX reverse proxy that offers SSL support on port 5001. By default a self-signed certificate is auto-generated, but you can provide your own certificate and key using the following settings:

• SSL_CERT: The full SSL certificate, passed in directly (optional)
• SSL_KEY: The full SSL private key, passed in directly (optional)
• SSL_CERT_PATH: Path to a custom SSL certificate inside the container, e.g. a volume mount (optional)
• SSL_KEY_PATH: Path to a custom SSL private key inside the container, e.g. a volume mount (optional)

Use either the SSL_CERT / SSL_KEY pair to pass in the certificate and key directly, or the SSL_CERT_PATH / SSL_KEY_PATH pair to reference files inside the container. Do not use both pairs at the same time.

Running multiple web containers

The web container uses session cookies, which are encrypted with a secret key. By default, each pod initializes a new key when it starts up, equivalent to running:

$ openssl rand -hex 128

If you are running multiple web containers for high availability, they need to share the same encryption key. Otherwise, a session cookie created by one pod cannot be processed by another, so during a failover the user’s session would not continue.

To run multiple pods, create the key once using the openssl command above, and then pass the same value to all containers via the SECRET_KEY_BASE environment variable.

SECRET_KEY_BASE=your-generated-secret-key

Resource settings

• SIDEKIQ_CONCURRENCY: Concurrency (number of threads) for background workers, defaults to 1. Set this to 0 to turn off the workers in the combined image (requires 2023.06.0 or newer).

Access control settings

• DISABLE_DIRECT_SIGNUP: Whether direct signups to the pganalyze application are permitted (without requiring an invite or going through Single Sign-On)
• DEFAULT_ORG_ROLE: How new users are added to the organization when they sign up (optional, default: none)
  • none - new users are not organization members and have to be invited by an existing user (recommended)
  • admin - assigns the role named “Admin (All Servers)”
  • modify_all - assigns the role named “View & Modify (All Servers)”
  • view_all - assigns the role named “View (All Servers)”
  • create_workbooks_all - assigns the role named “View & Create Workbooks (All Servers)” (previously called tune_queries_all in Enterprise Server v2025.03)

Important: If you are hosting your pganalyze Enterprise Server installation on a publicly available interface (i.e. without explicit access control at the network level), we recommend setting DISABLE_DIRECT_SIGNUP to 1.

Note that DISABLE_DIRECT_SIGNUP is not compatible with the DEFAULT_ORG_ROLE setting: If DISABLE_DIRECT_SIGNUP is enabled, and DEFAULT_ORG_ROLE is not none, it will be the same as setting it to none, since direct registrations are not possible.

AWS-specific settings

When using the collector to monitor Amazon RDS or Aurora, the required IAM credentials can either be set using an IAM policy (recommended), or by explicitly setting these environment variables:

• AWS_ACCESS_KEY_ID: AWS Access Key ID (optional)
• AWS_SECRET_ACCESS_KEY: AWS Secret Access Key (optional)
• AWS_REGION: Default AWS region (optional)

When using Amazon EKS with IAM roles associated to a service account, the following additional settings can be used:

• AWS_ROLE_ARN: Role to assume for AWS API access (automatically set by EKS)
• AWS_WEB_IDENTITY_TOKEN_FILE: Location of Web Identity token file (automatically set by EKS)
• AWS_ROLE_SESSION_NAME: Session name to use when assuming roles (optional, defaults to “pganalyze”)

Google Auth integration

Configured using GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. See separate instructions.

PagerDuty integration

Configured using PAGERDUTY_APP_ID. See separate instructions.

Slack integration

Configured using SLACK_CLIENT_ID and SLACK_CLIENT_SECRET. See separate instructions.

LDAP configuration

pganalyze Enterprise Server can optionally support using an LDAP connection to verify user credentials, instead of using a username/password stored in the pganalyze database. When LDAP is enabled regular user authentication is turned off.

LDAP is commonly utilized when using Microsoft Active Directory on-premise. If possible we recommend using the SAML integration instead, including when using Azure Active Directory.

When using LDAP, it is recommended to also set DEFAULT_ORG_ROLE to a non-empty value (see above) to ensure that new LDAP users are added to the existing organization.

• LDAP_HOST: Internal hostname or IP of your LDAP server
• LDAP_PORT: Port of your LDAP server. Use port 636 for LDAPS
• LDAP_BASE_DN: Base Domain Name (DN) that all lookups should be done with. You can use this to restrict access to a subset of your LDAP accounts. Note that users need to be members of this DN.
• LDAP_LOOKUP_CN: Common Name (CN) of an account that will be used to run authentication lookups on your LDAP directory
• LDAP_LOOKUP_PASSWORD: Password for the account that will be used to run authentication lookups
• LDAP_FIELD_UID: UID field on your LDAP entries. This is usually sAMAccountName on Active Directory servers
• LDAP_ENCRYPTION: Encryption mode to use for LDAP connections. Only add this when you want to use LDAPS (Port 636) or STARTTLS (Port 389) for a secure connection to your server. Specify ssl for LDAPS, and tls for STARTTLS (optional)
• LDAP_ENCRYPTION_CA_FILE: Sets the path to CA file to validate server certificate (use a volume mount to provide this file to the container)
• LDAP_ENCRYPTION_VERIFY_MODE: Whether to verify the server certificate (“peer”, the default since release v2024.10.0) or not (“none”)

Example LDAP configuration, with the required DEFAULT_ORG_ROLE setting, but without other unrelated settings:

LDAP_HOST=example.com
LDAP_PORT=389
LDAP_BASE_DN=OU=Users,OU=ldaptest,DC=ldaptest,DC=pganalyze,DC=com
LDAP_LOOKUP_CN=Admin
LDAP_LOOKUP_PASSWORD=ReallyLongSecurePassword
LDAP_FIELD_UID=sAMAccountName
LDAP_ENCRYPTION=ssl
DEFAULT_ORG_ROLE=view_all

Note you can run an Enterprise self-check to verify the connection and lookup LDAP information, but some configuration errors are only visible once logging in.

Worker queue monitoring using Prometheus

The metrics HTTP endpoint /metrics is available for Prometheus scraping. Currently, it provides worker queue metrics using the sidekiq-prometheus-exporter gem.

The endpoint is protected with a bearer auth, the token is specified with the SIDEKIQ_PROMETHEUS_TOKEN environment variable. The endpoint is only available when the environment variable is set. If you have a Prometheus setup already, you can add the hostname and port of your web server as an additional target to the Prometheus config file to scrape.

Below is an example of a prometheus.yml file (with web server 0.0.0.0:5000):

scrape_configs:
  - job_name: "sidekiq-prometheus"
    scrape_interval: 60s
    scrape_timeout: 10s
    authorization:
      credentials: $SIDEKIQ_PROMETHEUS_TOKEN
    static_configs:
      - targets: [ '0.0.0.0:5000' ]