https://wiki.openstack.org/w/api.php?action=feedcontributions&user=Luis.sampaio&feedformat=atomOpenStack - User contributions [en]2024-03-28T11:44:57ZUser contributionsMediaWiki 1.28.2https://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181805StarlingX/DebianBuildEnvironment2022-08-19T19:59:19Z<p>Luis.sampaio: /* Every time you start/restart Pods */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<Firstname Lastname>"<br />
export USER_EMAIL="<your email>"<br />
<br />
# STX_BUILD_HOME should be set to a directory owned by your userid<br />
# the build home needs to have at least 200Gb of free space to build all packages and iso<br />
export STX_BUILD_HOME="/home/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
Create the $STX_BUILD_HOME directory, you may need sudo privileges if using /build<br />
<br />
e.g: <br />
sudo mkdir -p /build/${USER}<br />
sudo chown ${USER}: /build/${USER}<br />
<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
git config --global user.name "Firstname Lastname"<br />
git config --global user.email "Your email"<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181804StarlingX/DebianBuildEnvironment2022-08-19T19:11:57Z<p>Luis.sampaio: </p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<Firstname Lastname>"<br />
export USER_EMAIL="<your email>"<br />
<br />
# STX_BUILD_HOME should be set to a directory owned by your userid<br />
# the build home needs to have at least 200Gb of free space to build all packages and iso<br />
export STX_BUILD_HOME="/home/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
Create the $STX_BUILD_HOME directory, you may need sudo privileges if using /build<br />
<br />
e.g: <br />
sudo mkdir -p /build/${USER}<br />
sudo chown ${USER}: /build/${USER}<br />
<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181803StarlingX/DebianBuildEnvironment2022-08-19T16:57:53Z<p>Luis.sampaio: /* Export environment variables */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<Firstname Lastname>"<br />
export USER_EMAIL="<your email>"<br />
<br />
# "/build" is used as example, any directory owned by your user should work<br />
# the build home needs to have at least 200Gb of free space to build all packages and iso<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
Create the $STX_BUILD_HOME directory, you may need sudo privileges if using /build<br />
<br />
e.g: <br />
sudo mkdir -p /build/${USER}<br />
sudo chown ${USER}: /build/${USER}<br />
<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181802StarlingX/DebianBuildEnvironment2022-08-19T16:57:11Z<p>Luis.sampaio: </p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<Firstname Lastname>"<br />
export USER_EMAIL="<your email>"<br />
<br />
# "/build" is used as example, any directory owned by your user should work<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
Create the $STX_BUILD_HOME directory, you may need sudo privileges if using /build<br />
<br />
e.g: <br />
sudo mkdir -p /build/${USER}<br />
sudo chown ${USER}: /build/${USER}<br />
<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181801StarlingX/DebianBuildEnvironment2022-08-19T16:24:54Z<p>Luis.sampaio: </p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<Firstname Lastname>"<br />
export USER_EMAIL="<your email>"<br />
<br />
# "/build" is used as example, any directory owned by your user should work<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
Create the $STX_BUILD_HOME directory, you may need sudo privileges if using /build<br />
<br />
e.g: <br />
sudo mkdir -p /build/${USER}<br />
sudo chown ${USER}: /build/${USER}<br />
<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181747StarlingX/DebianBuildEnvironment2022-08-10T19:09:55Z<p>Luis.sampaio: /* Start/Create build containers */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
stx control stop<br />
cd repo/stx-tools<br />
./stx-init-env --rebuild<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181746StarlingX/DebianBuildEnvironment2022-08-10T19:07:12Z<p>Luis.sampaio: /* Build packages */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
The 'build-pkgs' has two phases based on the Debian package's build:<br />
<br />
1) Check the digest of package's source meta data, for example:<br />
<br />
if package 'dhcp' in cache:<br />
if sha256 digest of the folder (/path/to/stx/integ/base/dhcp/debian) have not changed:<br />
if the dsc file of package dhcp exists:<br />
reuse the existing dsc file<br />
return<br />
create dsc file for package 'dhcp' and add the checksum to cache <br />
<br />
2) Build avoidance is enabled by default for this phase, the build option '-c' will turn 'build avoidance' off.<br />
<br />
if build avoidance is enabled:<br />
check whether there is build stamp for this package:<br />
if Yes, skip the build and return<br />
Send the build request for the package to pkgbuilder container<br />
<br />
To Build packages:<br />
<br />
# Build all packages<br />
# this should rebuild all packages (std and rt)<br />
build-pkgs --all<br />
# If you want to clean and build all:<br />
build-pkgs --clean --all<br />
<br />
But be careful, '--clean --all' not only clean the whole build directory "/localdisk/loadbuild/<user>/<project>/{std,rt}" but also clean the local repository "deb-local-build".<br />
This means all the starlingX packages will be built from scratch and this will take time. <br />
If you just want to resume the previous build, please run without '-c':<br />
# build-pkg --all<br />
<br />
<br />
# Build packages in parallel<br />
build-pkgs --all --parallel <number of parallel tasks, the default number is 10, the maximum number of parallel tasks is 30><br />
<br />
# To define the interval to poll the packages build status during parallel build:<br />
--poll_interval <the default interval is 10 seconds><br />
<br />
# To limit the number of make jobs for a package:<br />
--max_make_jobs <the default number of jobs is equal to the environment variable 'STX_BUILD_CPUS' or 'MAX_CPUS' inside the container><br />
<br />
<br />
# Build single package<br />
build-pkgs -p <package name><br />
<br />
# Build single package cleaning previous build<br />
build-pkgs -c -p <package name><br />
<br />
# Once the packages are ready you can build the iso<br />
build-image<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181745StarlingX/DebianBuildEnvironment2022-08-10T19:05:33Z<p>Luis.sampaio: /* Refresh the source tree */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181744StarlingX/DebianBuildEnvironment2022-08-10T19:04:55Z<p>Luis.sampaio: /* Initialize the source tree */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Refresh the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories, if required you can sync the repos from inside the builder:<br />
<br />
cd $MY_REPO_ROOT_DIR<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
ls $MY_REPO<br />
ls $MY_REPO/stx<br />
ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
the download directory is: $STX_MIRROR<br />
<br />
downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
* debian_pkg_dirs<br />
* debian_pkg_dirs_rt<br />
* debian_pkg_dirs_installer<br />
<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
You can also run below command to download both sources and binaries:<br />
<br />
downloader -b -s<br />
# To check all options:<br />
downloader --help<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181743StarlingX/DebianBuildEnvironment2022-08-10T18:59:47Z<p>Luis.sampaio: /* Build packages/ISO creation */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx shell<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181742StarlingX/DebianBuildEnvironment2022-08-10T18:59:25Z<p>Luis.sampaio: Undo revision 181741 by Luis.sampaio (talk)</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181741StarlingX/DebianBuildEnvironment2022-08-10T18:58:45Z<p>Luis.sampaio: /* Build packages/ISO creation */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181740StarlingX/DebianBuildEnvironment2022-08-10T18:56:37Z<p>Luis.sampaio: /* StarlingX Build Tools */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are five containers required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
* stx-docker: Docker in Docker (build docker images)<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181739StarlingX/DebianBuildEnvironment2022-08-10T18:56:01Z<p>Luis.sampaio: /* Entering & controlling Pods */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are four containers (stx-builder|stx-pkgbuilder|stx-repomgr| stx-lat-tool) required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 5 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx shell<br />
<br />
you can enter other containers as follows<br />
<br />
stx shell --container [builder|pkgbuilder|lat|repomgr|docker]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181738StarlingX/DebianBuildEnvironment2022-08-10T18:54:46Z<p>Luis.sampaio: /* Configure build environment */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are four containers (stx-builder|stx-pkgbuilder|stx-repomgr| stx-lat-tool) required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 4 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx control enter<br />
<br />
you can enter other containers as follows<br />
<br />
stx control enter --dockername [builder|pkgbuilder|lat|repomgr]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=181737StarlingX/DebianBuildEnvironment2022-08-10T18:54:08Z<p>Luis.sampaio: /* Configure build environment */</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are four containers (stx-builder|stx-pkgbuilder|stx-repomgr| stx-lat-tool) required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Install repo ===<br />
<br />
https://gerrit.googlesource.com/git-repo/<br />
<br />
=== Export environment variables ===<br />
<br />
export PROJECT="stx-env"<br />
export USER_NAME="<your username>"<br />
export USER_EMAIL="<your email>"<br />
<br />
export STX_BUILD_HOME="/build/${USER}/${PROJECT}"<br />
export REPO_ROOT="${STX_BUILD_HOME}"/repo<br />
export REPO_ROOT_SUBDIR="localdisk/designer/${USER}/${PROJECT}"<br />
<br />
# MINIKUBE<br />
export STX_PLATFORM="minikube"<br />
export MINIKUBENAME="minikube-${USER}"<br />
# or if you prefer to have multiple minikubes for each environment you can add the $PROJECT to the MINIKUBENAME:<br />
# export MINIKUBENAME="minikube-${USER}-${PROJECT}"<br />
<br />
#############################################<br />
# Manifest/Repo Options:<br />
#############################################<br />
# STX MASTER<br />
export MANIFEST_URL="https://opendev.org/starlingx/manifest.git"<br />
export MANIFEST_BRANCH="master"<br />
export MANIFEST="default.xml"<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Create directories ===<br />
mkdir -p $STX_BUILD_HOME<br />
cd $STX_BUILD_HOME<br />
<br />
=== Initialize repo ===<br />
# create REPO_ROOT_SUBDIR and symlink<br />
# symlink is a helper as minikube mounts the stx_build_home as its workspace<br />
# so it works as a shortcut to access the repos<br />
mkdir -p $REPO_ROOT_SUBDIR<br />
ln -s $REPO_ROOT_SUBDIR $REPO_ROOT<br />
<br />
cd $REPO_ROOT<br />
# download and sync the repos<br />
repo init -u ${MANIFEST_URL} -b ${MANIFEST_BRANCH} -m ${MANIFEST}<br />
repo sync<br />
<br />
=== Init and setup STX ===<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining $MINIKUBE_HOME in the environment before sourcing import-stx.<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# Init stx tool<br />
cd stx-tools<br />
source import-stx<br />
<br />
# Update stx config<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser ${USER}<br />
stx config --add project.gitemail ${USER_EMAIL}<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name ${PROJECT}<br />
<br />
stx config --show<br />
# Show usage information<br />
stx config --help<br />
<br />
<br />
=== Start/Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd repo/stx-tools<br />
./stx-init-env<br />
# Monitor the status until they are running:<br />
stx control status<br />
# You should see 5 containers on Running state<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 4 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx control enter<br />
<br />
you can enter other containers as follows<br />
<br />
stx control enter --dockername [builder|pkgbuilder|lat|repomgr]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -b -B rt<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -s -b -B std<br />
<br />
And for rt:<br />
<br />
$ downloader -s -b -B rt<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c] [-d DISTRO] [-B BUILD_TYPES] [-l LAYERS]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
-d DISTRO, --distro DISTRO<br />
name of the distro to build ['centos', 'debian']<br />
-B BUILD_TYPES, --build-types BUILD_TYPES<br />
comma separated list of all build-types to build ['rt', 'std']<br />
-l LAYERS, --layers LAYERS<br />
comma separated list of all layers to build ['compiler', 'distro', 'flock', 'containers']<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p setuptools # for reference, if syncing before 28 March: build-pkgs -p python3-setuptools<br />
# keeping this note so people using old-env still have a way to build, will remove soon.<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a -b std<br />
<br />
And for rt:<br />
<br />
build-pkgs -a -b rt<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=180832StarlingX/DebianBuildEnvironment2022-03-25T21:08:04Z<p>Luis.sampaio: Updating build home and env variable instructions</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are four containers (stx-builder|stx-pkgbuilder|stx-repomgr| stx-lat-tool) required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Clone build tools and set up workspace ===<br />
<br />
Clone build tools:<br />
<br />
export TOOL_HOME=~/DebianBuild<br />
mkdir -p $TOOL_HOME<br />
cd $TOOL_HOME<br />
git clone https://opendev.org/starlingx/tools<br />
<br />
Create a workspace directory; it will be mapped into build container.<br />
<br />
export WORKSPACE_HOME=~/DebianBuildWorkspace<br />
mkdir -p $WORKSPACE_HOME<br />
# export your Project name, e.g:<br />
export PROJECT=stx-debian<br />
# Create the STX_BUILD_HOME/$PROJECT and adjust any user permission required<br />
# You can use any directory as STX_BUILD_HOME, e.g:<br />
export STX_BUILD_HOME=/localdisk/designer/$(id -nu)/$PROJECT<br />
mkdir -p $STX_BUILD_HOME<br />
ln -sf $WORKSPACE_HOME $STX_BUILD_HOME<br />
<br />
For more details about the STX environment variables [https://opendev.org/starlingx/tools/src/branch/master/import-stx.README click here].<br />
<br />
=== Source the environment ===<br />
<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining ``MINIKUBE_HOME`` in the environment before sourcing ``import-stx``:<br />
<br />
# Necessary if your $HOME is on NFS<br />
export MINIKUBE_HOME=/localdisk/designer/$(id -nu)<br />
# Source the environment<br />
cd $TOOL_HOME/tools<br />
source import-stx<br />
<br />
=== Configure build containers ===<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# source the environment<br />
cd $TOOL_HOME/tools<br />
source ./import-stx<br />
<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser "First Last" <br />
stx config --add project.gitemail "your@email.address"<br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name $PROJECT <br />
stx config --add project.proxy false<br />
<br />
# Show all the settings<br />
stx config --show<br />
<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env --rebuild<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 4 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx control enter<br />
<br />
you can enter other containers as follows<br />
<br />
stx control enter --dockername [builder|pkgbuilder|lat|repomgr]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -b -s<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
'''WARNING''' When doing a clean build, you '''must build''' python3-setuptools and dh-python '''before others'''. We add back a feature that was removed in the tools, and needs some redesign in other areas. Without this bootstrap will fail.<br />
<br />
build-pkgs -p python3-setuptools<br />
build-pkgs -p dh-python<br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaiohttps://wiki.openstack.org/w/index.php?title=StarlingX/DebianBuildEnvironment&diff=180608StarlingX/DebianBuildEnvironment2022-02-16T19:00:56Z<p>Luis.sampaio: Adding changes after build tools update - commit: 52ef35d1bff8b67186aef89db8e8b231c1550fad</p>
<hr />
<div>== StarlingX Build Tools ==<br />
<br />
The Debian build is completed using a set of containers designed to run in a Kubernetes environment. To facilitate this we are currently<br />
making use of Minikube and Helm, later on we will provide versions of the Helm Charts to allow for running builds directly on Kubernetes or<br />
StarlingX.<br />
<br />
There are four containers (stx-builder|stx-pkgbuilder|stx-repomgr| stx-lat-tool) required to complete a build:<br />
<br />
* stx-builder: main developer build container.<br />
* stx-pkgbuilder: Debian package builder (uses sbuild).<br />
* stx-repomgr: Debian local repository archive (uses aptly)<br />
* stx-lat-tool: Debian image builder<br />
<br />
At a high level the StarlingX ISO image creation flow involves the following general steps (assuming you have already configured Docker on your system).<br />
<br />
# Install Minikube and Helm.<br />
# Build or download the StarlingX k8s development environment.<br />
# Enter the stx-builder pod/container to triger the building task.<br />
# Build packages/ISO creation.<br />
<br />
<br />
'''NOTE''': the build system requires a Linux system with Docker and python 3.x installed. Building on Windows is not supported -- please use a Virtual Machine if necessary. The steps on this page have been tested on CentOS 7 and Ubuntu Focal.<br />
<br />
== Configure build environment ==<br />
<br />
We need to create and start the build containers, which requires some additional configuration described below.<br />
<br />
=== Install Minikube and Helm ===<br />
<br />
Install Minikube to support the local k8s framework for building. Install Helm tools to manage the Helm Charts required to<br />
start/stop/upgrade the pods or the deployments for the StarlingX Building system. Before installing these components please make sure<br />
that Docker is available in your environment.<br />
<br />
Install minikube (https://minikube.sigs.k8s.io/docs/start/):<br />
<br />
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
'''Note''': as of this writing minikube v 1.22.0 is current.<br />
<br />
'''Note''': minikube requires at least 2 CPU cores.<br />
<br />
Alternatively, we can also use a third-party Minikube binary:<br />
<br />
curl -LO http://kubernetes.oss-cn-hangzhou.aliyuncs.com/minikube/releases/v1.20.0/minikube-linux-amd64<br />
sudo install minikube-linux-amd64 /usr/local/bin/minikube<br />
<br />
Install Helm -- you can select the version listed here or the latest released version:<br />
<br />
curl -LO https://get.helm.sh/helm-v3.6.2-linux-amd64.tar.gz<br />
tar xvf helm-v3.6.2-linux-amd64.tar.gz<br />
sudo mv linux-amd64/helm /usr/local/bin/<br />
<br />
Add your user account to docker group:<br />
<br />
sudo usermod -aG docker $(id -un) && newgrp docker<br />
<br />
=== Clone build tools and set up workspace ===<br />
<br />
Clone build tools:<br />
<br />
export TOOL_HOME=~/DebianBuild<br />
mkdir -p $TOOL_HOME<br />
cd $TOOL_HOME<br />
git clone https://opendev.org/starlingx/tools<br />
<br />
Create a workspace directory; it will be mapped into build container.<br />
<br />
export WORKSPACE_HOME=~/DebianBuildWorkspace<br />
mkdir -p $WORKSPACE_HOME<br />
export PROJECT=stx-debian<br />
export STX_BUILD_HOME=/localdisk/designer/$(id -nu)/$PROJECT<br />
# Create the STX_BUILD_HOME and adjust any user permission required<br />
mkdir -p $STX_BUILD_HOME<br />
ln -sf $WORKSPACE_HOME $STX_BUILD_HOME<br />
<br />
<br />
=== Source the environment ===<br />
<br />
The build tools comes with a script, import-stx, which sets up your PATH and other environment as necessary. This script must be sourced before attempting to use any tools:<br />
<br />
There's a number of environment variables you can set prior to sourcing this file, please feel free to review the script and import-stx.README for a full list.<br />
<br />
'''WARNING''': minikube can't work if your $HOME directory points to an NFS location, we need to point it to some other local file system by defining ``MINIKUBE_HOME`` in the environment before sourcing ``import-stx``:<br />
<br />
# Necessary if your $HOME is on NFS<br />
export MINIKUBE_HOME=/localdisk/designer/$(id -nu)<br />
# Source the environment<br />
cd $TOOL_HOME/tools<br />
source import-stx<br />
<br />
=== Configure build containers ===<br />
<br />
The build expects a configuration file, ``stx.conf`` ([https://opendev.org/starlingx/tools/src/branch/master/stx.conf.sample example]) to exist at the root of the build tools working directory. It is a key/value file containing various build options. The ``stx config`` command may be used to add/modify entries in the file.<br />
<br />
# source the environment<br />
cd $TOOL_HOME/tools<br />
source ./import-stx<br />
<br />
# Align the builder container to use your user/UID<br />
stx config --add builder.myuname $(id -un)<br />
stx config --add builder.uid $(id -u)<br />
<br />
# Embedded in ~/localrc of the build container<br />
stx config --add project.gituser "First Last" <br />
stx config --add project.gitemail <your email address><br />
<br />
# This will be included in the name of your build container and the basename for $MY_REPO_ROOT_DIR <br />
stx config --add project.name $PROJECT <br />
stx config --add project.proxy false<br />
<br />
# Show all the settings<br />
stx config --show<br />
<br />
# Show usage information<br />
stx config --help<br />
<br />
=== Create build containers ===<br />
<br />
The ``stx-init-env`` script will download or re-create build (docker) containers, and start them:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env<br />
<br />
The script pulls build containers from DockerHub by default, where a new version is built once per day (ie default container images may be slightly out of date when you pull them). You can force a local re-build as follows:<br />
<br />
cd $TOOL_HOME/tools<br />
bash stx-init-env --rebuild<br />
<br />
Once docker images are available locally, you can start & stop them using the ``stx`` tool:<br />
<br />
stx control start # start builder PODs if not running<br />
stx control status # display POD status<br />
stx control stop # stop PODs<br />
<br />
'''WARNING''': any changes to ``stx.conf`` or (``stx config add`` etc) requires that the PODs are re-started. f you want to make changes to the environment in the build container, use ‘stx control stop’, then ‘stx config’ to adjust the variables, and re-start the containers.<br />
<br />
stx control stop<br />
stx config add <...><br />
stx control start<br />
<br />
== Entering & controlling Pods ==<br />
<br />
Once the containers are running, one can enter them (think ``docker exec <...> /bin/bash). While there are 4 containers, most build tasks are driven from the "builder" container, which is the default when using the ``stx`` tool:<br />
<br />
# enter the "builder" container<br />
stx control enter<br />
<br />
you can enter other containers as follows<br />
<br />
stx control enter --dockername [builder|pkgbuilder|lat|repomgr]<br />
<br />
Use ``exit`` command to exit from the node to host environment.<br />
<br />
You can use the ``stx control`` command to start/stop & monitor builder POD status:<br />
<br />
# control the Pods<br />
stx control start<br />
stx control stop<br />
stx control status<br />
<br />
# more info<br />
stx control --help<br />
<br />
The ``status`` command will include Helm status, including deployments and the pods. You can use that information to manually enter or troubleshoot POds using munikube or kubectl.<br />
<br />
=== Every time you start/restart Pods ===<br />
<br />
Execute these mandatory steps inside the builder:<br />
<br />
sudo apt-get update<br />
sudo apt-get install less<br />
git config --global user.name "First Last"<br />
git config --global user.email your@email.com<br />
<br />
'''NOTE''': you may see the following errors from apt. You can ignore this and continue.<br />
<br />
E: Failed to fetch http://stx-stx-repomgr:80/deb-local-source/dists/bullseye/main/source/Sources 404 Not Found [IP: 10.102.135.193 80]<br />
E: Some index files failed to download. They have been ignored, or old ones used instead.<br />
<br />
== Build packages/ISO creation ==<br />
<br />
The six builder is the container where you will perform most of the actions, such as launching the task of building packages and images.<br />
<br />
stx control enter<br />
<br />
<br />
== Initialize the source tree ==<br />
<br />
The StarlingX source tree consists of multiple git repositories. The tool ‘repo’ is used to sync these repositories locally, below config<br />
Is minimally required to config to make ‘repo’ work:<br />
<br />
BUILD_BRANCH=master<br />
MANIFEST="default.xml"<br />
cd $MY_REPO_ROOT_DIR<br />
repo init -u https://opendev.org/starlingx/manifest -b $BUILD_BRANCH -m ${MANIFEST}<br />
repo sync<br />
<br />
After the ‘repo sync’ is done, check the below directory:<br />
<br />
$ ls $MY_REPO<br />
$ ls $MY_REPO/stx<br />
$ ls $MY_REPO_ROOT_DIR/stx-tools<br />
<br />
<br />
Before running 'build-pkgs':<br />
<br />
Run below command to download the sources of all buildable packages by scanning the repo root $MY_REPO/stx<br />
<br />
the download directory is: $STX_MIRROR/sources<br />
<br />
$ downloader -s<br />
<br />
All the below lists with build types will be scanned in the repo root $MY_REPO/stx:<br />
<br />
debian_pkg_dirs<br />
<br />
debian_pkg_dirs_rt<br />
<br />
debian_pkg_dirs_installer<br />
<br />
=== Verify that the local repos are created ===<br />
<br />
repo_manage.py list<br />
INFO:repo_manage:No remote repo<br />
INFO:repo_manage:3 local repos:<br />
INFO:repo_manage:deb-local-build : bullseye : main<br />
INFO:repo_manage:deb-local-binary : bullseye : main<br />
INFO:repo_manage:deb-local-source : bullseye : main<br />
<br />
'''NOTE''': All 3 repos should be seen only after build-pkgs [-p <package>] is done at a later time.<br />
<br />
=== Download 3rd-party tar & deb files ===<br />
<br />
Run below command to download the debian binary packages (distribution: bullseye) into directory $STX_MIRROR/binaries:<br />
<br />
$ downloader -b<br />
<br />
All the below lists of binary packages will be downloaded:<br />
<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/common/base-bullseye.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-std.lst<br />
$MY_REPO_ROOT_DIR/stx-tools/debian-mirror-tools/config/debian/<layer>/os-rt.lst<br />
<br />
<br />
Also run below command to download both sources and binaries:<br />
<br />
$ downloader -b -s<br />
<br />
<br />
$ downloader --help<br />
usage: downloader [-h] [-b] [-s] [-c]<br />
downloader helper<br />
optional arguments:<br />
-h, --help show this help message and exit<br />
-b, --download_binary<br />
download binary debs<br />
-s, --download_source<br />
download stx source<br />
-c, --clean_mirror clean the whole mirror and download again, be careful to use<br />
<br />
Currently, the apt sources used to download packages are in the '/etc/apt/sources.list' file in the builder container.<br />
<br />
== Build packages == <br />
<br />
To bulld an individual package:<br />
<br />
build-pkgs -p <name of package><br />
<br />
To build all of the packages available<br />
<br />
build-pkgs -a<br />
<br />
'''NOTE''': your build may fail due to circular dependencies. You can try building 2 or 3 times as a workaround.<br />
<br />
== Build ISO ==<br />
<br />
Once you have built all of the packages you can build the iso by running the following command:<br />
<br />
build-image<br />
ls -al /localdisk/deploy/*.iso<br />
<br />
== Log files ==<br />
<br />
While inside the build container, log files may be found here:<br />
<br />
* /localdisk/builder.log /localdisk/pkgbuilder.log - top-level build controller log files<br />
* ${MY_WORKSPACE}/<std or rt>/<package name>/*.build' - individual package build logs</div>Luis.sampaio