Execution via Docker

PgSmart Docker images (Client and Agent) offer a simple and quick way to start a PostgreSYS environment without the need to install packages.

There are two options to start the environment via Docker:

1. Docker Compose (Recommended)

   • What it does: Docker Compose starts the containers in an integrated way and automatically registers the PgSmart Agent.
   • Ideal for: Quick tests and development environments.

2. Separate Containers

   • What it does: You start the containers separately and then register the PgSmart Agent manually.
   • Ideal for: Production environments or more complex network scenarios.

Both options require you to first download the images from the Tecnisys repository.

Load Docker Images

This is the prerequisite for either of the two installation methods via Docker.

1. Run login on the repository (use your email and password registered on the Tecnisys website):

Terminal input

docker login -u <seu email> repo.tecnisys.com.br

1. Download the latest version (latest) of the PgSmart Docker images.

• PgSmart Client image (CLI + Web)

  Terminal input

  docker pull repo.tecnisys.com.br/pgsys/pgsmart-client:latest

• PgSmart Agent image

  Terminal input

  docker pull repo.tecnisys.com.br/pgsmart-agent:latest

Deployment with Docker Compose

This is the recommended option for a quick test environment. With a single command, Docker Compose will:

• Start the PgSmart Agent container;
• Start the PgSmart Client container (Web and CLI);
• Configure an internal network service so both can communicate;
• Register the Agent in the Client; and
• Install PostgreSYS services in the Agent container.

Create Docker Compose

To better organize the files, create a dedicated directory for PgSmart Docker Compose. Access the created directory and use a text editor to create the .env file with the credentials to access the PostgreSYS repository:

.env

PGSYS_USERNAME=your_tecnisys_access_email
PGSYS_PASSWORD=your_tecnisys_access_password

Next, create the compose.yml file with the following content:

compose.yml

networks:
  local-net:
    driver: bridge

services:

  agent:
    image: repo.tecnisys.com.br/pgsys/pgsmart-agent:latest
    container_name: pgsmart-agent
    privileged: true
    cap_add:
      - ALL
    networks:
      - local-net
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:rw
    tmpfs:
      - /run
      - /tmp
    stop_signal: SIGRTMIN+3
    ports:
      # Exposed ports for accessing components installed in the container (adjust to avoid host port conflicts)
      - "4432:4432" # PgSmart Agent
      - "5432:5432" # PostgreSQL Instance
      - "6432:6432" # PgBouncer
      - "8008:8008" # Patroni
      - "2379:2379" # etcd
      - "7001:7000" # HAProxy
      - "9090:9090" # Prometheus
      - "3000:3000" # Grafana
      - "4433:4433" # PostgreSYS PostgreSQL
      - "9093:9093" # Alertmanager
      - "9095:9095" # Karma
    post_start:
      - command: /opt/create-pgsys-repo.sh ${PGSYS_USERNAME} ${PGSYS_PASSWORD}
        user: root
      - command: /opt/configure-postgresql-instance.sh 17 postgres /data /wal 5432 UTF8 C # PostgreSQL instance configuration
        user: root

  client:
    image: repo.tecnisys.com.br/pgsys/pgsmart-client:latest
    container_name: pgsmart-client
    networks:
      - local-net
    ports:
      - "4435:4435"
    depends_on:
      - agent
    environment:
        # OPTIONAL: By default, the PostgreSYS environment will be initialized with the credentials provided in the .env file.
      - PGSYS_USERNAME=${PGSYS_USERNAME}
      - PGSYS_PASSWORD=${PGSYS_PASSWORD}
    post_start:
        # Pre register agent
      - command: /opt/register-agent.sh pgsmart-agent 9dbaff1aafb9e7ed609cf015
        user: pgsmart
        # IMPORTANT: If you only want an initial/clean environment (without pre-install services), REMOVE the commands below
        # Pre-install Pool Service
      - command: script -c "pgsmart install --quiet --agent pgsmart-agent --pgversion 17 --service pool" /dev/null
        user: pgsmart
        # Pre-install Backup Service
      - command: script -c "pgsmart install --quiet --agent pgsmart-agent --pgversion 17 --service backup" /dev/null
        user: pgsmart
        # Pre-install HA Service
      - command: script -c "pgsmart install --quiet --agent pgsmart-agent --pgversion 17 --service ha --ha-components dcs agent proxy" /dev/null
        user: pgsmart
        # Pre-install Observability Service
      - command: script -c "pgsmart install --quiet --agent pgsmart-agent --pgversion 17 --service obs --obs-inet 127.0.0.1" /dev/null
        user: pgsmart

Start PostgreSYS Environment

Prerequisites

• You must have Docker Compose version 2.30 or higher installed on your system to ensure compatibility with all features used.
• Define the PGSYS_USERNAME and PGSYS_PASSWORD environment variables in the .env file, or in the compose.yml file, or pass them as parameters in the docker-compose up -d command.

Before running Docker Compose, verify that the names and tags (for example, latest) of the PgSmart images defined in the compose.yml file match the images downloaded to your local Docker repository.

In the directory of the compose.yml file, run the command below to start your PostgreSYS environment:

Terminal input

docker-compose up -d

• The docker-compose up command starts the environment.
• The -d runs the containers in detached mode (in the background).

Done! Now just wait for the PgSmart containers to initialize.

As a next step, access PgSmart Web in your browser:

https://<ip or hostname of the PgSmart Client container host>:4435

To log in to PgSmart Web, use the default credentials:

• User: pgsmart
• Password: pgsmart

Deployment with Docker

If you chose to start the containers manually, without using Docker Compose, follow the instructions below.

This process consists of 3 steps:

1. Run the PgSmart Agent container on port 4432.
2. Run the PgSmart Client container on port 4435.
3. Manually register the Agent through PgSmart Web.

Run the PgSmart Agent Container

Start by running the PgSmart Agent container:

Terminal input

docker run --rm -d --privileged --cap-add=ALL -v /sys/fs/cgroup:/sys/fs/cgroup:rw --tmpfs /run,/tmp -p 4432:4432 repo.tecnisys.com.br/pgsmart-agent:latest

Parameters:

• --rm: Removes the container as soon as its execution is completed (optional).
• -d: Detaches the execution from the current shell session (optional).
• --privileged: Runs the container with elevated privileges.
• --cap-add=ALL: Assigns all necessary permissions for the container to run.
• -p 4432:4432: Maps host port 4432 to port 4432 of the PgSmart Agent.
• -v /sys/fs/cgroup:/sys/fs/cgroup:rw: Assigns the cgroup volume for container execution.
• --tmpfs /run,/tmp: Assigns tmpfs directories for container execution.

note

The PgSmart Agent container needs to be run with elevated privileges because it internally executes systemd.

At this point, the PgSmart Agent will be running and listening for connections on port 4432 of the host.

Run the PgSmart Client Container

Now start the PgSmart Client container (CLI + Web):

Terminal input

docker run -p 4435:4435 -d https://repo.tecnisys.com.br/pgsmart-client:latest

After the container initialization, PgSmart Web will be available for browser access on port 4435 of the host.

Default PgSmart Web credentials:

• User pgsmart
• Password pgsmart

Register the Agent

With the PgSmart Agent and Client containers running, you need to register the Agent manually:

1. Access PgSmart Web in your browser:

   https://<ip or hostname of the host running the PgSmart Client container>:4435

   For example:

   https://192.168.1.100:4435

2. Log in with the default credentials mentioned above.

3. Register the Agent:

   1. Go to Home → Manage Environments → Agents.

   2. Click Register.

   3. Enter an Alias (nickname) for the Agent.

   4. Enter the Hostname or IP address of the host where the Agent container is running.

   5. Enter the Agent Port (default 4432).

   6. Enter the Metrics Exposure Port (default 9100).

   7. Enter the Agent default Connection Key for Docker installs: 9dbaff1aafb9e7ed609cf015.

   8. Click Save.

note

The pgsmart-agent image has PgSmart Agent pre-installed and configured with the default connection key. After the container initialization, this key can be changed.

Done! The containers are now running and the Agent is registered in PgSmart Web.

Use PgSmart Web to manage the Agent and install the desired services/components, such as PostgreSQL and PgBouncer.

tip

If you prefer using PgSmart CLI instead of PgSmart Web, access the bash of the PgSmart Client container and run the pgsmart command:

Terminal input

docker exec -it <container_id> bash

Where <container_id> is the ID or name of the running container, returned by the docker ps command.