Local RP Dependency Setup

June 11, 2026 ยท View on GitHub

Note

To run an RP instance as a Go process using go run locally, additional tools are required and are outlined below.

Install Package Dependencies

Fedora/RHEL Dependencies

Important

For other OS specific requirements, refer to the Miscellaneous OS Requirements section.

  1. General dependencies 
    sudo dnf install -y \
    gpgme-devel \
    libassuan-devel \
    openssl \
    nodejs
  2. Dependencies for Fedora 37+ 
    sudo dnf install -y \
    lvm2 \
    lvm2-devel \
    golang-github-containerd-btrfs-devel
  3. Dependencies for pyenv 
    sudo dnf install -y \
    bzip2-devel \
    ncurses-devel \
    libffi-devel \
    readline-devel \
    sqlite-devel \
    tk-devel \
    xz-devel \
    zlib-devel \
    gcc \
    make

Fedora/RHEL Optional Dependencies

  1. Install Docker Compose
    1. Fedora/RHEL 
      sudo dnf install -y \
    docker-compose-plugin
    2. See Install Go via gvm gvm

Debian Dependencies

  1. Install the required dependencies 
    sudo apt install -y \
    libgpgme-dev \
    libbtrfs-dev \
    libdevmapper-dev \
    nodejs \
    npm

Debian Optional Dependencies

  1. Install docker-compose-plugin 
    sudo apt install -y
    docker-compose-plugin

MacOS Dependencies

  1. Install the required dependencies 
    brew install coreutils \
    findutils \
    gnu-tar \
    grep \
    gettext \
    gpgme diffutils \
    node

Optional MacOS Dependencies

Warning

Pay attention to the notes after the brew installer runs as there will be instructions to follow to complete setup on MacOS.

  1. Install docker-compose 
    brew install docker-compose

Install Go

Install Go Manually

Tip

Go versions installation and management can be simplified with gvm. See Install Go With gvm

  1. Download Go matching the version in go.mod.

  2. Extract the archive

    cd $HOME/Downloads
sudo tar -C /usr/local -xzf go1.22.12.linux-amd64.tar.gz

  3. Add Go to PATH in your shell's RC file

    export PATH="${PATH}:/usr/local/go/bin"

  4. Configure GOPATH as an environment variable in your shell, as it is required by some dependencies for make generate. To use the default path, add the following to your shell's RC file

    export GOPATH=$(go env GOPATH)

Install Python (pyenv)

Important

Python versions earlier than 3.6 or later than 3.10 are currently not supported.

  1. Install pyenv 
    curl https://pyenv.run | bash
  2. Append the following to your shell's RC file 
    export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
  3. Install required Python version using pyenv 
    pyenv install 3.10.0

Install AZ Client

Note

Due to the az client requiring a specific Python version, you will find the instructions to install the az client in the Getting Started section. This will use pyenv to ensure the correct Python version limited to the local ARO-RP environment.

ARO-RP comes with make pyenv, this will set up the environment and install the az client after setting the local Python version via pyenv.

Install OpenVPN

  1. Find the client you require here
  2. Or: on RHEL/Fedora run the following 
    sudo dnf install openvpn

Note

You can also use the built in Network Manager to add .ovpn configuration files.

Install Podman and Podman Docker

Note

Podman is used for building container images and running the installer.

  1. Install Podman 
    sudo dnf install -y \
    podman \
    podman-docker

Configure Podman

Important

Podman needs to be running in daemon mode when running the RP locally.

  1. On Linux, you can enable socket activation to start Podman in daemon mode 
    systemctl --user enable podman.socket

Warning

If you are using podman-machine, you will need to export the socket:

export ARO_PODMAN_SOCKET=unix://$HOME/.local/share/containers/podman/machine/qemu/podman.sock

You will also need to ensure that podman-machine has enough resources:

podman machine stop
podman machine rm
podman machine init --cpus 4 --memory 5000
podman machine start
  1. Disable Docker compatibility mode for az acr login support 
    sudo touch /etc/containers/nodocker

Configure Podman on macOS (Apple Silicon)

Important

On Apple Silicon Macs (M1/M2/M3/M4), the aro-installer container image is only built for amd64. You must configure Podman with Rosetta emulation to run amd64 containers.

  1. Install Podman

    brew install podman

  2. Initialize the Podman machine with Rosetta support and sufficient resources

    podman machine init --cpus 4 --memory 5000 --rootful --rosetta
podman machine start

    Note

    If you already have a Podman machine without Rosetta, recreate it:

    podman machine stop
podman machine rm
podman machine init --cpus 4 --memory 5000 --rootful --rosetta
podman machine start

  3. Set the Podman socket environment variable

    The socket path varies by system. Find yours with:

    podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}'

    Then add to your shell RC file or env file:

    export ARO_PODMAN_SOCKET="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"

  4. Verify the setup

    # Confirm Rosetta is enabled
podman machine inspect | grep -i rosetta

# Test pulling an amd64 image
podman pull --platform linux/amd64 alpine
podman run --rm alpine uname -m  # Should output: x86_64

Install GolangCI Lint

  1. Find latest version here
  2. Run the install 
    # https://github.com/golangci/golangci-lint/releases
GOLINT_VERSION="<REPLACE WITH LATEST>"

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin "$GOLINT_VERSION"

Install YAMLLint

sudo dnf install -y \
    yamllint

Miscellaneous OS Requirements

RHEL

  1. Register the system with subscription-manager register
  2. Enable the CodeReady Linux Builder repository to install *-devel packages
  3. Enable the EPEL repository for packages not in the base repositories (such as OpenVPN)

Debian

Important

Your actual pkgconfig path may differ; please adjust it accordingly.

  1. Ensure you have installed all Debian dependencies
  2. Make sure that PKG_CONFIG_PATH contains the pkgconfig files of the above packages. For example: 
    export PKG_CONFIG_PATH:/usr/lib/x86_64-linux-gnu/pkgconfig

MacOS

Note

Developers using macOS are encouraged to contribute to this repository. To ensure compatibility, macOS users should install GNU utilities on their systems.

The goal is to minimize shell scripting and other platform-specific variations within the repository. Installing GNU utilities on macOS helps reduce discrepancies in command-line flags, usage and more, ensuring a consistent development experience across environments.

  1. Ensure you have installed all MacOS dependencies

  2. Link gettext to make commands available system-wide

    brew link gettext

  3. Update your PATH in your shell's RC file to prepend your PATH with GBU Utils paths

    export PATH=$(find $(brew --prefix)/opt -type d -follow -name gnubin -print | paste -s -d ':' -):\$PATH

  4. Add the following to your shell's RC file

    export LDFLAGS="-L$(brew --prefix)/lib"
export CFLAGS="-I$(brew --prefix)/include"
export CGO_LDFLAGS=$LDFLAGS
export CGO_CFLAGS=$CFLAGS

  5. Login to ACR

    Tip

    The following steps may be applicable where you symlink docker to podman location.

    ### CHECK SYMLINK ###
ls -la $(whereis -q docker)

# Example Output: /Users/<USER>/.local/bin/docker -> /opt/homebrew/bin/podman

### LOGIN TO ACR ###
az acr login --name <TARGET_ACR>

Containerized RP Software Required

Tip

For a minimal development environment, the recommended approach is to use the containerized setup. This runs the RP inside a container with your local workspace mounted, facilitating debugging and quick code changes.

See Containerized Development Environment for a complete setup guide.

The containerized development environment requires only these locally installed tools:

  1. az
  2. make
  3. podman
  4. openvpn (Optional for Hive cluster deployments)

Note

Instructions for installing these tools are provided in the sections below. Refer to the Podman section for setup details specific to your operating system.