Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">18.1.0</button>

- [18.3.0](https://docs.cloud.google.com/alloydb/omni/containers/18.3.0/docs/install-web-ui.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/install-web-ui.md.txt)

<br />

This page shows how to install the AlloyDB Omni web user interface so
that you can monitor the health and configuration of your
self-managed database clusters. The web UI provides the
following features:

| Feature | Description | Containers (standalone) | Kubernetes | RPM (Linux) | RPM orchestrator |
| Cluster selection | A connectivity screen that lets you establish, register, and save connection credentials for access to target clusters. | Supported | Supported | Supported | Supported |
| Cluster overview | Observation dashboard displaying all active cluster instances and telemetry graphs. | Partial support. Telemetry graphs aren't supported. | Supported | Supported | Supported |
| Databases | Overview page displaying catalog tables and database sizes on the cluster. | Supported | Supported | Supported | Supported |
| [Columnar engine](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/columnar-engine/overview.md.txt) | Configuration settings and scan execution statistics for analytical queries. | Supported | Supported | Supported | Supported |
| Database flags | Observation board displaying active flags and configurations that deviate from default settings. | Supported | Supported | Supported | Supported |
| Query insights | Telemetry and query performance dashboards displaying structural histograms and slow query lists. | Supported | Supported | Supported | Supported |
| System insights | Telemetry charts displaying CPU consumption, memory footprints, and disk I/O. | Not supported | Supported | Supported | Supported |
|---|---|---|---|---|---|

## Before you begin

Before you install the web UI, complete the following prerequisites:

1. Obtain the images for your deployment and download and install
   AlloyDB Omni so that you can use the web UI:

   [Install AlloyDB Omni using containers](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/deploy-vm.md.txt).

2. Configure the database user.

   The web UI relies on a limited user account, which has
   the `pg_monitor` role for accessing the database. Configure this user on each
   cluster by running the following commands in a `psql` session:

   ```sql
   CREATE ROLE alloydbui WITH LOGIN PASSWORD 'PASSWORD';
   GRANT pg_monitor TO alloydbui WITH INHERIT TRUE;
   ```

   Replace `PASSWORD` with a password for the `alloydbui`
   database role.

   > [!NOTE]
   > **Note:** The `alloydbui` user requires specific permissions to populate certain sections in the user interface. For example, the `alloydbui` user needs at least one permission on tables to view data in the Columnar Store section, `SELECT` permission on tables for the Vector Columns section, and `SELECT` permission on `pg_stat_ann_indexes` for vector indexes. Consider your security requirements when you grant these permissions.

3. Configure Prometheus.

   To view chart data on the **Overview** and **System Insights** pages,
   including CPU usage, install and configure Prometheus.

   Note: A containerized monitoring agent isn't available when you deploy
   AlloyDB Omni as a standalone container. Prometheus chart
   metrics on the **Overview** and **System Insights** pages aren't supported
   when you connect to standalone container deployments.

### Optional steps

To enable additional web UI features, complete the following optional configurations:

- Query insights setup

  To use the query insights feature, enable the `pg_stat_statements` extension.
  In a `psql` session, run the following commands to configure the libraries:

  ```sql
  ALTER SYSTEM SET shared_preload_libraries=google_columnar_engine,google_job_scheduler,google_storage,google_db_advisor,pg_stat_statements;
  ALTER SYSTEM SET pg_stat_statements.max = 10000;
  ALTER SYSTEM SET pg_stat_statements.track_utility = on;
  ALTER SYSTEM SET track_io_timing = on;
  ```

  Then, run the following command in each database individually to create
  the extension:

  ```sql
  CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
  ```

  Restart the database for these changes to take effect. If you plan to enable
  the columnar engine, wait to restart until that setup is complete.
- Columnar engine setup

  To access columnar engine data in the web UI, configure the engine as described
  in [Columnar engine overview](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/columnar-engine/overview.md.txt).

  > [!NOTE]
  > **Note:** To view data in the **Columnar Queries** page in the web UI, you must install and configure the `pg_stat_statements` extension as described in the **Query insights setup** section.

- AlloyDB AI setup

  To use AlloyDB AI features in the web UI, grant the
  following permissions:
  - To populate vector indexes, grant the `alloydbui` user the `SELECT` permission on `pg_stat_ann_indexes`.
  - To display vector columns, grant the `alloydbui` user the `SELECT` permission on a table.

For more information, see [Build generative AI applications using AlloyDB AI](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/overview-ai).

## Install the web UI

You can install and run the web UI on any node. The
web UI doesn't require a dedicated node. The full installation
requires approximately 250 MB of disk space. After you obtain the images for
your deployment and download AlloyDB Omni, you can install and
run the web UI.

### Install using Docker or Podman image

When you run AlloyDB Omni using containers, pull
the Docker or Podman image:

### Docker

```bash
docker pull ALLOYDB_OMNI_UI_IMAGE_TAG
```

### Podman

```bash
podman pull ALLOYDB_OMNI_UI_IMAGE_TAG
```

Replace `ALLOYDB_OMNI_UI_IMAGE_TAG` with the tag for the
web UI container image.

## Start the web UI

The web UI uses a Java Keystore to protect the 256-bit
AES key that is used to encrypt connection data. When you start the web UI, specify an
environment variable containing the password.

> [!NOTE]
> **Note:** The web UI serves HTTP traffic on port `9080` by default and doesn't provide built-in TLS (HTTPS) termination. To secure traffic to the web UI using HTTPS, host the web UI behind a reverse proxy configured with your TLS certificates.

### Start the web UI on containers

Run the following command to start the web UI container. Include
the `--add-host=host.docker.internal:host-gateway` flag if you connect to an
AlloyDB Omni installation on the same host machine:

### Docker

```bash
docker run --name alloydb-omni-ui \
  --add-host=host.docker.internal:host-gateway \
  -e ALLOYDB_OMNI_UI_KEYSTORE="PASSWORD" \
  -p 9080:9080 \
  ALLOYDB_OMNI_UI_IMAGE_TAG
```

### Podman

```bash
podman run --name alloydb-omni-ui \
  --add-host=host.docker.internal:host-gateway \
  -e ALLOYDB_OMNI_UI_KEYSTORE="PASSWORD" \
  -p 9080:9080 \
  ALLOYDB_OMNI_UI_IMAGE_TAG
```

Replace the following:

- `PASSWORD`: the keystore password for
  `ALLOYDB_OMNI_UI_KEYSTORE`.

- `ALLOYDB_OMNI_UI_IMAGE_TAG`: the tag for the
  web UI container image.

## Open the web UI

To view the web UI, open a browser at `http://HOST:9080`.

Replace `HOST` with the hostname or IP address of the node
where the web UI is installed.

- If you configured a custom base path using the optional
  `ALLOYDB_OMNI_BASE_PATH` environment variable, such as when hosting behind
  an existing reverse proxy, then you must append the path to the URL:
  `http://HOST:9080/BASE_PATH`.

  Replace `BASE_PATH` with your custom base path.
- You can configure the base path without a leading slash---for
  example, `ALLOYDB_OMNI_BASE_PATH=BASE_PATH`.
  All of the following are valid alternatives:

  - `/test/`
  - `test/`
  - `test`
  - `/test`

## Limitations

The web UI has the following limitations:

- Overview charts and system insights aren't available when connecting to
  AlloyDB Omni standalone container deployments because a containerized
  monitoring agent isn't available for standalone container deployments. All other
  non-chart features and metrics remain fully functional.

- To view columnar engine data for a given table, the `alloydbui` user needs at least one
  permission on that table---for example, `SELECT`.

- To view vector index data, the `alloydbui` user needs the `SELECT`
  permission on `pg_stat_ann_indexes`.

- To view vector column data for a given table, the `alloydbui` user needs the
  `SELECT` permission on that table.

## Best practices and caveats

Follow these best practices and caveats when you install and configure the
web UI:

- **Keystore password protection** : The web UI generates a Java Keystore to protect the 256-bit AES database encryption key. Use a strong passphrase for `ALLOYDB_OMNI_UI_KEYSTORE`. Decryption errors occur if you transfer your configuration files and connect with a mismatching keystore password.
- **Prometheus metrics scraping** : Configure the scrapers to poll target instances at standard ranges (15s to 30s) to query statistics without overloading database nodes.

  ## What's next

  - [Connect to the web UI](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/connect-web-ui.md.txt).