Customize your AlloyDB Omni installation

This page shows you how to download, install, and connect to AlloyDB Omni. To get started quickly with AlloyDB Omni using the default configuration, see Install AlloyDB Omni on Debian or Ubuntu.

In this document, you also learn how to do the following:

Create a new disk partition to optimize data storage.
Configure your server.
Ensure compatibility with Debian, Ubuntu, and RHEL.

Before you begin

System requirements

Debian

A virtual or physical machine running a Debian-based OS, such as Debian or Ubuntu.
A minimum of 2 CPUs, with x86/AMD64 architecture.
A minimum of 2 GB of RAM. For optimal performance, we recommend allocating 8 GB of RAM for each CPU.
At least 20 GB of available storage.
Unrestricted root access within the OS.
Docker version 20.10 or higher.
Linux kernel version 4.18 or higher. We recommend kernel version 5.3 or higher for best performance.
Linux cgroup v2 enabled.
By default, cgroup v2 is enabled on most modern Linux systems. To check whether cgroup v2 is enabled, run stat -fc %T /sys/fs/cgroup/ in a shell. If cgroup v2 is enabled, the command output shows cgroup2fs.
If you want to integrate with Vertex AI, then you need the Google Cloud CLI available in your environment.
To install AlloyDB Omni on a cloud platform, we recommend using the following instance types:
- On Google Cloud, we recommend n2-highmem instances.
- On Amazon Web Services, we recommend R6i instances.
- On Microsoft Azure, we recommend Ebsv5 instances.
We recommend that you use a dedicated SSD storage device for storing your data. If you use a physical device for this purpose, we recommend attaching it directly to the host machine.

RHEL

A virtual or physical machine running a Red Hat Enterprise Linux (RHEL) version 8 or later. To let the automatic memory management features of AlloyDB Omni work, use RHEL version 9 or later.
A minimum of 2 CPUs, with x86/AMD64 architecture.
A minimum of 2 GB of RAM. For optimal performance, we recommend allocating 8 GB of RAM for each CPU.
At least 20 GB of available storage.
Unrestricted root access within the OS.
Docker version 20.10 or higher.
Linux kernel version 4.18 or higher. We recommend kernel version 5.3 or higher for best performance.
Linux cgroup v2 enabled.
By default, cgroup v2 is enabled on most modern Linux systems. To check whether cgroup v2 is enabled, run stat -fc %T /sys/fs/cgroup/ in a shell. If cgroup v2 is enabled, the command output shows cgroup2fs.
If you want to integrate with Vertex AI, then you need the Google Cloud CLI available in your environment.
To install AlloyDB Omni on a cloud platform, we recommend using the following instance types:
- On Google Cloud, we recommend n2-highmem instances.
- On Amazon Web Services, we recommend R6i instances.
- On Microsoft Azure, we recommend Ebsv5 instances.
We recommend that you use a dedicated SSD storage device for storing your data. If you use a physical device for this purpose, we recommend attaching it directly to the host machine.

Download and install AlloyDB Omni

Install the AlloyDB Omni CLI.
Use the AlloyDB Omni CLI to confirm that your Linux machine is ready to install AlloyDB Omni:
```
sudo alloydb system-check
```
If needed, modify your system until the output of the system-check command returns a successful check.
Optional: To create a new disk partition for AlloyDB Omni to use for data storage, we recommend that you use an ext4 file system for optimal performance.
1. To create an ext4 file system, use the following command:
```
mkfs.ext4 -m 1 -F "$disk_path"
```
2. To mount your disk, use the following command:
```
mount --make-shared -o noatime,discard,errors=panic "$disk_path" "$disk_mountpoint"
```
Install the server software using one of the following options:

Note: To install AlloyDB Omni with machine learning (ML) functions enabled, including the ability to query large language models (LLMs), see Install AlloyDB Omni with AlloyDB AI.
- To configure the server as a primary instance, run the following command:
```
sudo alloydb database-server install --data-dir=$(realpath DATA_DIR)
```
  Replace DATA_DIR with the directory on your local file system where you want AlloyDB Omni to store its data, metadata, and configuration files. AlloyDB Omni tries to create this directory if it doesn't already exist. If you don't specify this value, then AlloyDB Omni defaults to /var/alloydb/main/.
  
  To have AlloyDB Omni listen for connections on a TCP port other than the default 5432, include the --pg-port flag:
```
sudo alloydb database-server install \
    --data-dir=$(realpath DATA_DIR) \
    --pg-port=PORT
```
  Replace PORT with the TCP port that you want AlloyDB Omni to accept connections on.
- To configure the server as a read replica, include the --replica-source-ip and --replica-source-port flags:
```
sudo alloydb database-server install \
    --data-dir=$(realpath DATA_DIR) \
    --replica-source-ip=SOURCE_IP \
    --replica-source-port=SOURCE_PORT
```
  Replace the following:
  - DATA_DIR: the directory on your local file system where you want AlloyDB Omni to store its data, metadata, and configuration files. AlloyDB Omni tries to create this directory if it doesn't already exist. If you don't specify this value, then AlloyDB Omni defaults to /var/alloydb/main/.
  - SOURCE_IP: the IP address of the primary AlloyDB Omni instance to replicate from.
  - SOURCE_PORT: the TCP port of the primary AlloyDB Omni instance to replicate from. If you don't provide this value, then AlloyDB Omni applies a default value of 5432.
  For more information on AlloyDB Omni read replicas, see Create a read-only replica.
If your system runs Red Hat Enterprise Linux, then update the /usr/lib/tuned/virtual-guest/tuned.conf file with the following:
```
vm.swappiness=1
```

Connect to and use the database server

Connect to AlloyDB Omni using psql:

sudo docker exec -it pg-service psql -h localhost -U postgres

The terminal window displays psql login text that ends with a postgres=# prompt.

Preview a simplified AlloyDB Omni installation method

To install, configure, and run the Preview of a simplified AlloyDB Omni installation method, follow the instructions for the official PostgreSQL Docker image, with one modification: substitute google/alloydbomni for postgres as the name of the Docker image to use.

For example, to use this preview to install AlloyDB Omni and make its database available on a TCP port of your host machine, run the docker run command as follows:

docker run --name CONTAINER_NAME \
    -e POSTGRES_PASSWORD=NEW_PASSWORD \
    -p HOST_PORT:5432 -d google/alloydbomni

Replace the following:

CONTAINER_NAME: The name to assign this new AlloyDB Omni container in your host machine's container registry—for example, my-omni-1.
NEW_PASSWORD: The password assigned the new container's postgres user after its creation.
HOST_PORT: The TCP post on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.

After you have installed the container, you can control it using the Docker command-line interface. For example, to restart the database server, run the following commands:

docker container stop CONTAINER_NAME
docker container start CONTAINER_NAME

To enable AlloyDB AI integration with the simplified AlloyDB Omni installation method, see Preview a simplified installation method for AlloyDB Omni AI.

For an overview of the simplified AlloyDB Omni installation method, see Preview a simplified AlloyDB Omni installation method in "AlloyDB Omni overview".