Chapter 3. Quick Start

1. Ensure that prerequisites are met.

2. Configure the manager.

3. Configure an agent.

Prerequisites

1. Prepare the server where PPEM will be installed according to hardware and software requirements.

2. Install the Postgres Pro DBMS instance on the server.

   For more information about installation, refer to the official Postgres Pro documentation.

3. Start a new session under the superuser:

   $ sudo -s
   

Configuring the Manager

1. Install the repository:

   # wget -O pgpro-repo-add.sh https://repo.postgrespro.ru/ppem/ppem/keys/pgpro-repo-add.sh
   # sh pgpro-repo-add.sh
   

2. Install the manager:

   # apt install ppem ppem-gui
   

   The ppem-manager.yml manager configuration file will be downloaded to your local device.

   The path to the configuration file is /etc/ppem-manager.yml.

3. Create the DBMS user on behalf of whom the manager will connect to the repository database:

   # sudo -u postgres createuser --pwprompt ppem
   

   When executing this command, specify the DBMS user password.

4. Create the repository database:

   # sudo -u postgres createdb -O ppem ppem
   

5. Ensure that the DBMS user can connect to the database:

   # psql -h localhost -U ppem -d ppem
   

   In case of connection issues, ensure that the HBA rule allowing the DBMS user to connect to the database, as well as the authorization method, are specified in the pg_hba.conf configuration file.

   For more information, refer to the official Postgres Pro documentation on the pg_hba.conf configuration file.

6. In the /etc/ppem-manager.yml manager configuration file:

   • Specify the name of the host to connect to using the repo.host parameter:

     repo:
       host: "localhost"
     

   • Specify the repository database name using the repo.name parameter:

     repo:
       name: "ppem"
     

   • Specify the DBMS username and password using repo.user and repo.password parameters:

     repo:
       user: "ppem"
       password: "DBMS_user_password"
     

   Note

   It is possible to use a single URL instead of the above parameters for connecting the manager to the repository database. The URL must be specified using the repo.url parameter:

   repo:
     url: "postgres://ppem:DBMS_user_password@localhost/ppem"
   

   For more information about the URL format, refer to the official Postgres Pro documentation on connection strings.

7. Start the manager service and add it to the server startup:

   # systemctl start ppem
   # systemctl enable ppem
   

Configuring an Agent

1. Install the agent:

   # apt install ppem-agent
   

   The ppem-agent.yml agent configuration file will be downloaded to your local device.

2. Create the DBMS user on behalf of whom the agent will connect to the repository database:

   # sudo -u postgres createuser -s --pwprompt ppem_agent
   

   When executing this command, specify the DBMS user password.

3. Ensure that the DBMS user can connect to the repository database:

   # psql -h localhost -U ppem_agent -d ppem
   

   In case of connection issues, ensure that the HBA rule allowing the DBMS user to connect to the database, as well as the authorization method, are specified in the pg_hba.conf configuration file.

   For more information, refer to the official Postgres Pro documentation on the pg_hba.conf configuration file.

4. Get an API key for configuring the agent:

   1. Log in to the web application.

   2. Copy the API key from the displayed agent installation instruction and save this key.

5. In the ppem-agent.yml agent configuration file, specify agent parameters:

   agent:
     name: "agent_name"
     manager:
       url: "URL_for_connecting_to_manager"
       api_key: "API_key_for_connecting_to_manager"
     instance:
       connection_defaults:
         user: "DBMS_username"
         password: "DBMS_user_password"
   http:
     server:
       address: "network_address_for_incoming_connections"
       port: "port_for_incoming_connections"
   

   Where:

   • agent.name: The unique agent name.

   • agent.manager.url: The URL for connecting the agent to the manager in the scheme://manager_network_address/path_to_API_version format.

   • agent.manager.api_key: The previously obtained API key for connecting the agent to the manager.

   • agent.instance.connection_defaults.user and agent.instance.connection_defaults.password: The DBMS username and password.

   • http.server.address and http.server.port: The network address and port number for incoming network connections.

     To enable listening of all network addresses and ports, do not specify any values for these parameters.

6. Start the agent service and add it to the server startup:

   # systemctl start ppem-agent
   # systemctl enable ppem-agent