Distribution-Specific Installation

This chapter provides installation instructions for different operating systems and distributions.

Dependencies

pgagroal requires the following dependencies:

• a C compiler like gcc 8+ (C17) or clang 8+
• cmake
• GNU make or BSD make
• libev
• OpenSSL
• rst2man
• libatomic
• Doxygen
• pdflatex
• zlib
• zstd
• lz4
• bzip2
• binutils
• on Linux platforms, there is also the need for
  • systemd

Rocky Linux / RHEL

All the dependencies can be installed via dnf(8) as follows:

dnf install git gcc cmake make    \
            libev libev-devel     \
            openssl openssl-devel \
            systemd systemd-devel \
            python3-docutils      \
            libatomic             \
            zlib zlib-devel       \
            libzstd libzstd-devel \
            lz4 lz4-devel         \
            bzip2 bzip2-devel     \
            binutils              \
            clang clang-analyzer clang-tools-extra

Please note that, on Rocky Linux, in order to install the python3-docutils package (that provides rst2man executable), you need to enable the crb repository:

dnf config-manager --set-enabled crb

FreeBSD

All the dependencies can be installed via pkg(8) as follows:

pkg install cmake          	\
            libev libevent 	\
            py311-docutils 	\
            lzlib           \
            liblz4          \
            lbizp2          \
            texlive-formats \
            binutils

Fedora

For Fedora systems, use:

dnf install git gcc cmake make liburing liburing-devel openssl openssl-devel systemd systemd-devel python3-docutils libatomic zlib zlib-devel libzstd libzstd-devel lz4 lz4-devel bzip2 bzip2-devel libasan libasan-static binutils clang clang-analyzer clang-tools-extra

Ubuntu / Debian

For Ubuntu and Debian systems:

apt-get update
apt-get install build-essential cmake libev-dev libssl-dev libsystemd-dev python3-docutils libatomic1 zlib1g-dev libzstd-dev liblz4-dev libbz2-dev binutils

macOS

For macOS using Homebrew:

brew install cmake libev openssl@3 docutils zlib zstd lz4 bzip2

Note: On macOS, you may need to set additional environment variables for OpenSSL:

export OPENSSL_ROOT_DIR=$(brew --prefix openssl@3)
export PKG_CONFIG_PATH="$OPENSSL_ROOT_DIR/lib/pkgconfig:$PKG_CONFIG_PATH"

Building from Source

After installing dependencies, build pgagroal:

git clone https://github.com/pgagroal/pgagroal.git
cd pgagroal
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install

Platform-Specific Notes

Linux

• Ensure liburing is available for optimal I/O performance
• Configure systemd service files for production deployments
• Consider using huge pages for better memory performance

FreeBSD

• Use the ports system for more control over build options
• Configure appropriate kernel parameters for network performance
• Consider using jails for isolation

macOS

• Some features may have limited support compared to Linux
• Use Homebrew for dependency management
• Consider using Docker for consistent environments

Troubleshooting

Common Issues

Missing liburing on older systems:

# Install liburing from source if not available in package manager
git clone https://github.com/axboe/liburing.git
cd liburing
make
sudo make install

OpenSSL version conflicts:

# Specify OpenSSL path explicitly
cmake -DOPENSSL_ROOT_DIR=/usr/local/ssl ..

Permission issues:

# Ensure proper permissions for installation
sudo chown -R $(whoami) /usr/local/

Build Flags

For debug builds:

cmake -DCMAKE_BUILD_TYPE=Debug ..

For release builds with optimizations:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS="-O3 -march=native" ..