Install mongot¶

Before deploying Percona Search for MongoDB, ensure that you have:

Percona Server for MongoDB 8.3 or later, installed as an initiated replica set.
Administrative privileges to install and configure mongot.
The mongot binary installed on the host.
Write access to the search data and log directories for the user that runs mongot.
Network connectivity from the mongot host to the replica set.

Note

The examples in this section use a single-node test environment with mongod listening on port 27017 and mongot listening on port 27028. Replace the host names, ports, paths, and credentials with values that are applicable for your deployment.

Additional requirements depend on the installation method:

Tarballs - An initiated replica set with keyfile access control or sharded deployment. mongosh installed on the host.
Docker - Docker engine with Compose v2 installed on the host.

For more information, see Vector Search compatibility.

Procedure¶

TarballsDockerRPM packagesDEB packages

Install `mongot` from tarballs¶

Follow these steps to install mongot from a tarball:

Download the mongot tarball.

ARM64AMD64 (x86_64)

Download the ARM64 tarball .

Download the AMD64 tarball .
Extract the tarball.
ARM64AMD64 (x86_64)
tar -zxvf percona-search-mongodb-1.70.3-linux_aarch64.tar.gz
tar -zxvf percona-search-mongodb-1.70.3-linux_x86_64.tar.gz
The extracted archive contains the mongot binary, the sample configuration file, the mongot launcher script, and the Percona Search for MongoDB license files.

Configure mongod to communicate with mongot.

Configure the following mongod startup parameters.

Parameter	Description
`searchIndexManagementHostAndPort`	Specifies the host and port of the `mongot` service used for search index management operations.
`mongotHost`	Specifies the host and port of the `mongot` service used to process search queries. This value must match `searchIndexManagementHostAndPort`.
`skipAuthenticationToSearchIndexManagementServer`	Enables or disables authentication between `mongod` and `mongot` for search index management operations.
`useGrpcForSearch`	Enables or disables gRPC communication between `mongod` and `mongot`.

Example: mongod configuration

setParameter:
  searchIndexManagementHostAndPort: localhost:27028
  mongotHost: localhost:27028
  skipAuthenticationToSearchIndexManagementServer: false
  useGrpcForSearch: true

These are startup parameters. Restart mongod for the changes to take effect.

sudo systemctl restart mongod

Create a user for the mongot process.

mongot connects to your Percona Server for MongoDB deployment by using a user with the searchCoordinator role.
1. Connect to mongosh as an administrator.
```
mongosh --port 27017 -u <admin-username> -p <admin-password>
```
2. Switch to the admin database.
```
use admin
```
3. Create the mongot user.
  
  Replace:
  - <mongot-username> with the username for the mongot user.
  - <mongot-password> with the password that you save in the password file in the next step.
  Then run:
```
db.createUser({
  user: "<mongot-username>",
  pwd: "<mongot-password>",
  roles: ["searchCoordinator"]
})
```

Create the password file.

sudo mkdir -p /etc/mongot
echo -n "<mongot-password>" | sudo tee /etc/mongot/mongot.passwd > /dev/null
sudo chmod 600 /etc/mongot/mongot.passwd
sudo chown mongod:mongod /etc/mongot/mongot.passwd

Prepare the required directories.

sudo mkdir -p /var/lib/mongot /etc/mongot /opt/mongot
sudo chown -R mongod:mongod /var/lib/mongot /etc/mongot /opt/mongot
sudo chmod 750 /etc/mongot

Create the mongot configuration file.

The tarball includes a sample configuration file named config.default.yml. Modify it as needed for your deployment.

Example: config.default.yml

syncSource:
  replicaSet:
    hostAndPort: localhost:27017
    username: <mongot-username>
    passwordFile: /etc/mongot/mongot.passwd
    tls: false

storage:
  dataPath: /var/lib/mongot

server:
  grpc:
    address: localhost:27028
    tls:
      mode: disabled

metrics:
  enabled: true
  address: localhost:9946

healthCheck:
  address: localhost:8080

logging:
  verbosity: INFO

Note

The user running mongot must have write access to the directory specified by storage.dataPath.

For the complete list of configuration options, see the upstream mongot configuration options documentation.

Copy the extracted files to the installation directory.

sudo cp -a percona-search-mongodb/* /opt/mongot/
sudo chown -R mongod:mongod /opt/mongot

Create the systemd service.

Create the following file:

/etc/systemd/system/mongot.service

[Unit]
Description=MongoDB Search (mongot)
Documentation=https://www.mongodb.com/docs/manual/reference/configuration-options/#std-label-mongot-configuration-options
After=network.target

[Service]
User=mongod
Group=mongod
Type=simple
ExecStart=/opt/mongot/mongot --config /etc/mongot/config.yml
Restart=on-failure
RestartSec=5
LimitNOFILE=64000
TimeoutStartSec=30
TimeoutStopSec=30
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Set the required file permissions and SELinux contexts.

sudo chown mongod:mongod /etc/mongot/config.yml
sudo chmod 600 /etc/mongot/config.yml
sudo restorecon -Rv /opt/mongot

Enable and start mongot.

sudo systemctl daemon-reload
sudo systemctl enable mongot
sudo systemctl start mongot

Verify that mongot is running.

curl localhost:8080/health

Example output:

{"status":"SERVING"}

Install Vector Search with Docker¶

Important

mongot synchronizes data from mongod and requires a PSMDB replica set. Standalone deployments are not supported.

Follow these steps to install and configure mongot using Docker:

Pull the mongod Docker image.

docker pull percona/percona-server-mongodb:<TAG>

Pull the mongot Docker image.

docker pull percona/percona-server-mongodb-mongot:<TAG>

Verify the downloaded images.

docker image ls | grep percona-server-mongodb

Create a Docker network.

The mongod and mongot containers must run on the same Docker network so that they can communicate using their container names. Use the same <network-name> value when you start both containers.
```
docker network create <network-name>
```
Replace <network-name> with a name for the network, for example psmdb-search.
Create the password file for the mongot user.

mongot reads the password for its database user from a file. Create the file and restrict its permissions. The -n option prevents a trailing newline from being written to the file, which would otherwise become part of the password:
```
echo -n "<mongot-password>" > mongot-password.txt
chmod 400 mongot-password.txt
```
Replace <mongot-password> with a password of your choice. You use the same password when you create the mongot database user in step 9.

Create the mongod configuration file.

Save the following configuration as mongod.conf.

net:
  port: 27017
  bindIpAll: true

replication:
  replSetName: rs0

setParameter:
  searchIndexManagementHostAndPort: mongot:27028
  mongotHost: mongot:27028
  skipAuthenticationToSearchIndexManagementServer: false
  useGrpcForSearch: true
  searchTLSMode: disabled

The mongot:27028 address consists of the Docker container name and the gRPC port exposed by the mongot container. Specify the same value for both searchIndexManagementHostAndPort and mongotHost.

Start mongod.

Replace:
- <path-to-data-db> with the path to the MongoDB data directory.
- <path-to-mongod-conf> with the path to the mongod.conf file.
- <network-name> with the Docker network created in step 4.
```
docker run --rm \
  --name mongod \
  -v <path-to-mongod-conf>:/etc/mongod.conf:ro \
  -v <path-to-data-db>:/data/db \
  -p 27017:27017 \
  --network <network-name> \
  percona/percona-server-mongodb:<TAG> \
  --config /etc/mongod.conf
```
The container name mongod becomes the hostname used by mongot to connect to the database. If you change the container name, update the syncSource.replicaSet.hostAndPort value in the mongot configuration file.

To view the server logs:
```
docker logs -f mongod
```
Initiate the replica set.

Connect to the running container:
```
docker exec -it mongod mongosh --port 27017
```
Initialize the replica set:
```
rs.initiate()
```
Wait until the node becomes the primary replica set member before continuing.
Create the mongot user.

mongot requires a database user with the searchCoordinator role.

The searchCoordinator role grants readAnyDatabase privileges and write access to the internal __mdb_internal_search database, which mongot uses to store search index metadata.
1. Switch to the admin database.
```
use admin
```
2. Create the user.
  
  Replace:
  - <mongot-username> with the username for the mongot user.
  - <mongot-password> with the password stored in mongot-password.txt.
```
db.createUser({
  user: "<mongot-username>",
  pwd: "<mongot-password>",
  roles: ["searchCoordinator"]
})
```
Create the mongot configuration file.

Important

Set syncSource.replicaSet.scramAuth.username to the user created in the previous step, and syncSource.replicaSet.scramAuth.passwordFile to the password file created in step 5.

For more information about the available configuration options, see the upstream documentation for mongot configuration options .
Example: mongot.conf
```
syncSource:
  replicaSet:
    hostAndPort: "mongod:27017"
    scramAuth:
      username: "mongotUser"
      passwordFile: "/passwordFile"
      authSource: "admin"
      tls:
        enabled: false
  replicationReader:
    readPreference: "secondaryPreferred"

storage:
  dataPath: "/data/mongot"

server:
  grpc:
    address: "mongot:27028"
    tls:
      mode: "disabled"

metrics:
  enabled: true
  address: "mongot:9946"

healthCheck:
  address: "mongot:8080"

logging:
  verbosity: INFO
```
Save the configuration file as mongot.conf.

The mongod and mongot containers must run on the same Docker network.

Ensure that:
- scramAuth.username matches the user created in step 9.
- passwordFile points to the password file created in step 5.
The mongot container reads its configuration from /mongot-community/config.default.yml, which is mounted in the next step.

Start the mongot container.

Replace:

<path-to-data-mongot> with the directory used to store search index data.
<path-to-mongot-conf> with the path to the mongot.conf file.
<path-to-password-file> with the path to the password file.
<network-name> with the Docker network created in step 4.

docker run --rm \
  --name mongot \
  -v <path-to-data-mongot>:/data/mongot \
  -v <path-to-mongot-conf>:/mongot-community/config.default.yml:ro \
  -v <path-to-password-file>:/passwordFile:ro \
  --network <network-name> \
  percona/percona-server-mongodb-mongot:<TAG>

To view the mongot logs:

docker logs -f mongot

Verify the health of the mongot process.

Send a request to the readiness endpoint.
```
docker exec mongot -- curl localhost:8080/health
```
If mongot starts successfully, the endpoint returns:
```
SERVING
```

Install `mongot` on RHEL and derivatives¶

Follow these steps to install mongot using the Percona RPM repository:

Install the Percona repository.

sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm

Enable the Percona Search for MongoDB repository.
```
sudo percona-release enable ps4m release
```

Install mongot.

sudo yum install percona-search-mongodb

After installing the package, continue with step 3 in the Tarballs tab to configure mongod and mongot.

Install `mongot` on Debian and Ubuntu¶

Follow these steps to install mongot using the Percona APT repository:

Install the Percona repository.

wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb

sudo apt install ./percona-release_latest.$(lsb_release -sc)_all.deb

Enable the Percona Search for MongoDB repository.
```
sudo percona-release enable ps4m release
```

Install mongot.

sudo apt install percona-search-mongodb

After installing the package, continue with step 3 in the Tarballs tab to configure mongod and mongot.

Install mongot¶

Procedure¶

Install mongot from tarballs¶

Install Vector Search with Docker¶

Install mongot on RHEL and derivatives¶

Install mongot on Debian and Ubuntu¶

Install `mongot` from tarballs¶

Install `mongot` on RHEL and derivatives¶

Install `mongot` on Debian and Ubuntu¶