Skip to content

Commit a4334d2

Browse files
sameluchmbykhovtsev-ms
sameluch
authored and
mbykhovtsev-ms
committed
add install-prereqs-and-configure option, update docs (microsoft#14096)
1 parent c4d6b31 commit a4334d2

File tree

6 files changed

+342
-37
lines changed

6 files changed

+342
-37
lines changed

‎toolkit/docs/building/prerequisites-mariner.md‎

Lines changed: 77 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,88 @@
11

2-
# Build Requirements on `Azure Linux`
2+
# Build Requirements for Azure Linux Toolkit
33

4-
## Requirements were validated on `Azure Linux`
4+
This page outlines the requirements for building with the Azure Linux toolkit on different versions of Azure Linux/Mariner.
55

6-
This page lists host machine requirements for building with the Azure Linux toolkit. They cover building the toolchain, packages, and images on an Azure Linux host.
6+
## System-Specific Requirements
7+
8+
### Golang Package Requirements
9+
10+
Different versions of Azure Linux have been validated with the following Golang packages:
11+
12+
- **Azure Linux 2.0 (CBL-Mariner)**: Validated with `msft-golang-1.24.1`
13+
- **Azure Linux 3.0**: Validated with `golang-1.24.3`
14+
15+
## Installation Methods
16+
17+
### Method 1: Using Make Targets (Recommended)
18+
19+
The make targets automatically detect your OS version and install the appropriate packages:
720

821
```bash
9-
# Install required dependencies.
10-
sudo ./toolkit/docs/building/prerequisites-mariner.sh
22+
# For interactive development environments (local machines)
23+
# Installs prerequisites but doesn't modify system configuration
24+
# Note: On Azure Linux 2.0, this will remove golang if installed in favor of msft-golang due to the golang version requirement
25+
sudo make -C toolkit install-prereqs
26+
27+
# Manually configure Docker if needed
28+
sudo systemctl enable --now docker.service
29+
sudo usermod -aG docker $USER
30+
# Note: You will need to log out and log back in for user changes to take effect
31+
32+
# the above step can alternatively be done using the following command if preferred:
33+
# sudo ./toolkit/docs/building/prerequisites-mariner.sh --no-install-prereqs --configure-docker
34+
35+
--------------
36+
37+
# For automated environments (CI/CD pipelines) or complete setup
38+
# Installs prerequisites AND configures Docker and user settings
39+
sudo make -C toolkit install-prereqs-and-configure
40+
```
41+
42+
**Recommendation**:
43+
- Use `install-prereqs` on your local development machine
44+
- Use `install-prereqs-and-configure` in CI/CD pipelines or when you need a complete environment setup
1145

12-
# Also supported is:
13-
# make -C toolkit install-prereqs
46+
### Method 2: Direct Script Execution
1447

15-
# Enable Docker daemon at boot
48+
If you prefer running the script directly, use the appropriate options for your OS version:
49+
50+
#### For Azure Linux 2.0 (CBL-Mariner):
51+
```bash
52+
# Install prerequisites with msft-golang
53+
# Note: This will remove golang if installed in favor of msft-golang due to the golang version requirement
54+
sudo ./toolkit/docs/building/prerequisites-mariner.sh --use-msft-golang
55+
56+
# Manually configure Docker if needed
1657
sudo systemctl enable --now docker.service
58+
sudo usermod -aG docker $USER
59+
# Note: You will need to log out and log back in for user changes to take effect
1760

18-
# Add current user to docker group
61+
# the above step can alternatively be done using the following command if preferred:
62+
# sudo ./toolkit/docs/building/prerequisites-mariner.sh --no-install-prereqs --configure-docker
63+
```
64+
65+
#### For Azure Linux 3.0:
66+
```bash
67+
# Install prerequisites with standard golang
68+
sudo ./toolkit/docs/building/prerequisites-mariner.sh
69+
70+
# Manually configure Docker if needed
71+
sudo systemctl enable --now docker.service
1972
sudo usermod -aG docker $USER
73+
# Note: You will need to log out and log back in for user changes to take effect
74+
75+
# the above step can alternatively be done using the following command if preferred:
76+
# sudo ./toolkit/docs/building/prerequisites-mariner.sh --no-install-prereqs --configure-docker
2077
```
78+
79+
## Script Options
80+
81+
The `prerequisites-mariner.sh` script supports the following options:
82+
83+
- `--configure-docker`: Enables Docker service at boot and adds your user to the docker group
84+
- `--no-install-prereqs`: Skips installation of prerequisite packages
85+
- `--use-msft-golang`: Uses `msft-golang-1.24.1` instead of `golang-1.24.3` (required for Azure Linux 2.0)
86+
- `--help`: Displays usage information
87+
88+
> **Note**: If you use `--configure-docker`, you will need to log out and log back in for the user changes to take effect.

‎toolkit/docs/building/prerequisites-mariner.sh‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,71 @@
44

55
set -e
66

7-
tdnf -y install \
7+
# Define usage function
8+
usage() {
9+
echo "Usage: $0 [OPTIONS]"
10+
echo "Install prerequisites for Azure Linux toolkit"
11+
echo ""
12+
echo "Options:"
13+
echo " --configure-docker Enable Docker service and add current user to docker group"
14+
echo " --no-install-prereqs Skip installation of prerequisite packages"
15+
echo " --use-msft-golang Use msft-golang-1.24.1 instead of golang-1.24.3"
16+
echo " --help Display this help message"
17+
exit 1
18+
}
19+
20+
# Initialize option flags
21+
CONFIGURE_DOCKER=false
22+
INSTALL_PREREQS=true
23+
USE_MSFT_GOLANG=false
24+
25+
# Parse command line arguments
26+
while [ $# -gt 0 ]; do
27+
case "$1" in
28+
--configure-docker)
29+
CONFIGURE_DOCKER=true
30+
;;
31+
--no-install-prereqs)
32+
INSTALL_PREREQS=false
33+
;;
34+
--use-msft-golang)
35+
USE_MSFT_GOLANG=true
36+
;;
37+
--help)
38+
usage
39+
;;
40+
*)
41+
echo "Unknown option: $1"
42+
usage
43+
;;
44+
esac
45+
shift
46+
done
47+
48+
# Install prerequisites if not disabled
49+
# golang version pinned for stability to avoid breaking changes. As of 11-Jun-2025 we are using the following golang versions:
50+
# - msft-golang-1.24.1 for Mariner 2.0
51+
# - golang-1.24.3 for Mariner 3.0
52+
# When making a breaking change to the toolkit which requires a newer golang version, update this version.
53+
if [ "$INSTALL_PREREQS" = true ]; then
54+
echo "Installing required packages..."
55+
56+
# Determine which golang package to use based on the option
57+
if [ "$USE_MSFT_GOLANG" = true ]; then
58+
# golang will conflict with msft-golang, so we need to remove it if it exists
59+
if rpm -q golang >/dev/null 2>&1; then
60+
echo "Installed golang conflicts with required msft-golang. Removing existing golang package..."
61+
tdnf -y remove golang
62+
fi
63+
64+
GOLANG_PKG="msft-golang-1.24.1"
65+
echo "Using Microsoft Go version: $GOLANG_PKG"
66+
else
67+
GOLANG_PKG="golang-1.24.3"
68+
echo "Using standard Go version: $GOLANG_PKG"
69+
fi
70+
71+
tdnf -y install \
872
acl \
973
binutils \
1074
cdrkit \
@@ -15,7 +79,7 @@ tdnf -y install \
1579
genisoimage \
1680
git \
1781
glibc-devel \
18-
golang \
82+
$GOLANG_PKG \
1983
jq \
2084
kernel-headers \
2185
make \
@@ -33,6 +97,20 @@ tdnf -y install \
3397
wget \
3498
xfsprogs \
3599
zstd
100+
else
101+
echo "Skipping installation of prerequisite packages..."
102+
fi
103+
104+
# Configure Docker if requested
105+
if [ "$CONFIGURE_DOCKER" = true ]; then
106+
echo "Enabling Docker service..."
107+
systemctl enable --now docker.service
108+
109+
echo "Adding current user to 'docker' group..."
110+
usermod -aG docker $USER
111+
112+
echo "*** NOTE: You will need to log out and log back in for user changes to take effect. ***"
113+
fi
36114

37115
script_file=$(readlink -f "$0")
38116
# md file is the same name as the script file, but with a .md extension
@@ -41,5 +119,8 @@ md_file="${script_file%.*}.md"
41119
echo ""
42120
echo "Install complete..."
43121
echo ""
44-
echo "**** Refer to ${md_file} for additional steps to complete the setup. ****"
122+
if [ "$CONFIGURE_DOCKER" = false ]; then
123+
echo "**** Additional optional steps are available. Run with --help for more information. ****"
124+
echo "**** Refer to ${md_file} for more details. ****"
125+
fi
45126
echo ""

‎toolkit/docs/building/prerequisites-ubuntu.md‎

Lines changed: 67 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,80 @@
11

2-
# Build Requirements on `Ubuntu`
2+
# Build Requirements for Azure Linux Toolkit on Ubuntu
33

4-
## Requirements were validated on `Ubuntu 22.04`
4+
This page outlines the requirements for building with the Azure Linux toolkit on Ubuntu.
55

6-
This page lists host machine requirements for building with the Azure Linux toolkit. They cover building the toolchain, packages, and images on an Ubuntu 22.04 host.
6+
## System-Specific Requirements
7+
8+
### Golang Package Requirements
9+
10+
The Azure Linux toolkit on Ubuntu has been validated with the following:
11+
12+
- **Ubuntu 22.04**: Validated with `golang-1.23.1` (available as `golang-1.23-go` package)
13+
14+
## Installation Methods
15+
16+
### Method 1: Using Make Targets (Recommended)
17+
18+
The make targets automatically install the appropriate packages:
719

820
```bash
9-
# Install required dependencies.
10-
sudo ./toolkit/docs/building/prerequisites-ubuntu.sh
21+
# For interactive development environments (local machines)
22+
# Installs prerequisites but doesn't modify system configuration
23+
sudo make -C toolkit install-prereqs
1124

12-
# Also supported is:
13-
# make -C toolkit install-prereqs
25+
# Manually create Go symlinks for proper PATH integration
26+
sudo ln -sf /usr/lib/go-1.23/bin/go /usr/bin/go
27+
sudo ln -sf /usr/lib/go-1.23/bin/gofmt /usr/bin/gofmt
1428

15-
# Fix go 1.21 link
16-
sudo ln -vsf /usr/lib/go-1.21/bin/go /usr/bin/go
17-
sudo ln -vsf /usr/lib/go-1.21/bin/gofmt /usr/bin/gofmt
29+
# Manually configure Docker if needed
30+
curl -fsSL https://get.docker.com -o get-docker.sh
31+
sudo sh get-docker.sh
32+
sudo usermod -aG docker $USER
33+
# Note: You will need to log out and log back in for user changes to take effect
1834

19-
# Install and configure Docker.
35+
# the above 2 steps can alternatively be done using the following command if preferred:
36+
# sudo ./toolkit/docs/building/prerequisites-ubuntu.sh --no-install-prereqs --fix-go-links --configure-docker
37+
38+
----------------------
39+
40+
# For automated environments (CI/CD pipelines) or complete setup
41+
# Installs prerequisites AND configures Docker and Go links
42+
sudo make -C toolkit install-prereqs-and-configure
43+
```
44+
45+
**Recommendation**:
46+
- Use `install-prereqs` on your local development machine
47+
- Use `install-prereqs-and-configure` in CI/CD pipelines or when you need a complete environment setup
48+
49+
### Method 2: Direct Script Execution
50+
51+
If you prefer running the script directly, you have several options:
52+
53+
```bash
54+
# Basic installation with Go
55+
sudo ./toolkit/docs/building/prerequisites-ubuntu.sh
56+
57+
# Manually create Go symlinks for proper PATH integration
58+
sudo ln -sf /usr/lib/go-1.23/bin/go /usr/bin/go
59+
sudo ln -sf /usr/lib/go-1.23/bin/gofmt /usr/bin/gofmt
60+
61+
# Manually configure Docker if needed
2062
curl -fsSL https://get.docker.com -o get-docker.sh
2163
sudo sh get-docker.sh
2264
sudo usermod -aG docker $USER
65+
# Note: You will need to log out and log back in for user changes to take effect
66+
67+
# the above 2 steps can alternatively be done using the following command if preferred:
68+
# sudo ./toolkit/docs/building/prerequisites-ubuntu.sh --no-install-prereqs --fix-go-links --configure-docker
2369
```
2470

25-
**You will need to log out and log back in** for user changes to take effect.
71+
## Script Options
72+
73+
The `prerequisites-ubuntu.sh` script supports the following options:
74+
75+
- `--fix-go-links`: Creates symbolic links for Go binaries to make them available in your PATH
76+
- `--configure-docker`: Installs Docker and adds your user to the docker group
77+
- `--no-install-prereqs`: Skips installation of prerequisite packages
78+
- `--help`: Displays usage information
79+
80+
> **Note**: If you use `--configure-docker`, you will need to log out and log back in for the user changes to take effect.

0 commit comments

Comments
 (0)