Prepare Your Development Environment

December 3, 2025 ยท View on GitHub

Note

This document outlines the development dependencies required to build the RP code.

Table Of Contents

Containerized RP Software Required

Tip

For a minimal development environment, the recommended approach is to use the containerized setup, which requires only the locally installed binaries listed below.

  • az
  • make
  • podman
  • openvpn

Note

Instructions for these binaries are provided below. Refer to the Podman section for setup details specific to your operating system (Linux or macOS with Podman Machine).

Important

With the local binaries installed you can then refer to the Getting Started section below to obtain the source code before deploying a development RP.

Instead of running make runlocal-rp, use make run-rp to run a containerized version of the application without requiring additional local binaries.

Local RP Dependencies

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

Important

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

  1. General dependencies

    sudo dnf install gpgme-devel libassuan-devel openssl

  2. Dependencies for Fedora 37+

    sudo dnf install lvm2 lvm2-devel golang-github-containerd-btrfs-devel

  3. Dependencies for pyenv

    sudo dnf install bzip2-devel ncurses-devel libffi-devel readline-devel sqlite-devel tk-devel xz-devel zlib-devel gcc make

Install Go

  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 podman

  2. Install Podman Docker

    sudo dnf install 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

Install GolangCI Lint

  1. Find latest version here

  2. Run the install

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

Install YAMLLint

sudo dnf install yamllint

Other 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

  1. Install the required dependencies

    sudo apt install libgpgme-dev libbtrfs-dev libdevmapper-dev

  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

Important

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

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. Install the required dependencies

    brew install coreutils findutils gnu-tar grep gettext gpgme diffutils

  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>

Getting Started

  1. Clone the repository

    git clone https://github.com/Azure/ARO-RP.git

  2. Go to project

    cd /path/to/ARO-RP

  3. Configure pyenv Python version

    pyenv local 3.10.0
pyenv rehash

python --version

  4. Make environment

    make pyenv

Tip

This will install the az client. However, if the install fails you can attempt a re-install with:

source pyenv/bin/activate
pip install azure-cli

  1. Login to Azure

    az login

  2. Configure local git

    # Set pre-commit hook
make init-contrib

# Set GitHub username globally
git config --global github.user "<USERNAME>"

# OR: Set GitHub username locally to repo
git config github.user "<USERNAME>"

Important

Running make init-contrib enforces a necessary branch naming convention for your commits.

The convention is: <USERNAME>/<JIRA_NUMBER> You can also append a description after the <JIRA_NUMBER> e.g: <USERNAME>/<JIRA_NUMBER>/my-description-here

Getting Started With Docker Compose

  1. Install Docker Compose

    1. Fedora/RHEL

      sudo dnf install docker-compose-plugin

    2. Debian

      sudo apt install docker-compose-plugin

    3. MacOS

      brew install docker-compose

Warning

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

  1. Check the env.example file and copy it to create your own

    cp env.example env

  2. Source the env file

    . ./env

  3. Run VPN, RP, and Portal services using Docker Compose

    docker compose up vpn rp portal

Makefile Help

Tip

The project includes a make help target that provides a comprehensive list of all available Makefile targets along with their descriptions. This is particularly useful for discovering available commands without needing to read through the entire Makefile.

To view all available targets, run:

make help

Adding New Makefile Targets

When adding new targets to the Makefile, ensure they follow the help-compatible format so they appear in the make help output. The help system uses a regex pattern to extract target names and descriptions.

Format: Add two hash marks (##) followed by a space and description after your target definition:

target-name: dependencies ## Brief description of what this target does
	@commands to execute

Example:

my-new-feature: install-tools ## Build and test my new feature
	go build ./pkg/myfeature
	go test ./pkg/myfeature/...

This target will then appear in the make help output as:

my-new-feature            Build and test my new feature

Important

The ## delimiter must be present for the target to be recognized by the help system. Targets without this delimiter will not appear in the help output.

Troubleshooting

IssueResolution
Error ./env:.:11: no such file or directory: secrets/env.Run SECRET_SA_ACCOUNT_NAME=rharosecretsdev make secrets to resolve.
az -v does not return aro as a dependency.Ensure the environment file parameters are correctly set, following the env.example file.
Git commit fails due to branch naming error: There is something wrong with your branch name...Ensure the branch name follows the required pattern:

^${USERNAME}\/(ARO-[0-9]{4,}[a-z0-9._-]*|hotfix-[a-z0-9._-]+|gh-issue-[0-9]+[a-z0-9._-]*)$

If the PR is not tied to a Jira ticket, GitHub issue, or hotfix, use --no-verify with git commit to bypass the check.