Build an omnibus-gitlab
package locally
Prepare a build environment
Docker images with the necessary build tools for building omnibus-gitlab
packages
are in the GitLab Omnibus Builder
project’s Container Registry.
-
Containers need access to 4GB of memory to complete builds. Consult the documentation for your container runtime. Docker for Mac and Docker for Windows are known to set this value to 2GB for default installations.
-
Pull the Docker image for the OS you want to build a package for. The current version of the image used officially by
omnibus-gitlab
is referred to in the CI configurationBUILDER_IMAGE_REVISION
environment variable.docker pull registry.gitlab.com/gitlab-org/gitlab-omnibus-builder/debian_10:${BUILDER_IMAGE_REVISION}
-
Clone the Omnibus GitLab source and change to the cloned directory:
git clone https://gitlab.com/gitlab-org/omnibus-gitlab.git ~/omnibus-gitlab cd ~/omnibus-gitlab
-
Start the container and enter its shell, while mounting the
omnibus-gitlab
directory in the container:docker run -v ~/omnibus-gitlab:/omnibus-gitlab -it registry.gitlab.com/gitlab-org/gitlab-omnibus-builder/debian_10:${BUILDER_IMAGE_REVISION} bash
-
By default,
omnibus-gitlab
chooses public GitLab repositories to fetch sources of various GitLab components. Set the environment variableALTERNATIVE_SOURCES
tofalse
to build fromdev.gitlab.org
.export ALTERNATIVE_SOURCES=false
Component source information is in the
.custom_sources.yml
file. -
By default,
omnibus-gitlab
codebase is optimized to be used in a CI environment. One such optimization is reusing the pre-compiled Rails assets that is built by the GitLab CI pipeline. To know how to leverage this in your builds, check Fetch upstream assets section. Or, you can choose to compile the assets during the package build by setting theCOMPILE_ASSETS
environment variable.export COMPILE_ASSETS=true
-
By default, XZ compression is used to produce the final DEB package, which reduces the package size by nearly 30% in comparison to Gzip, with little to no increase in build time. However, the system’s package manager must also support the format. If your system’s package manager does not support XZ packages, set the
COMPRESS_XZ
environment variable tofalse
:export COMPRESS_XZ=false
This is feature is disabled by default on RPM platforms due to an as-yet-unexplained increase in packaging time. It can be enabled by setting theCOMPRESS_XZ
environment variable totrue
. -
Install the libraries and other dependencies:
cd /omnibus-gitlab bundle install bundle binstubs --all
Fetch upstream assets
Pipelines on GitLab and GitLab-FOSS projects create a Docker image with pre-compiled assets and publish the image to the container registry. While building packages, to save time you can reuse these images instead of compiling the assets again:
-
Fetch the assets Docker image that corresponds to the ref of GitLab or GitLab-FOSS you are building. For example, to pull the asset image corresponding to latest master ref, run the following:
docker pull registry.gitlab.com/gitlab-org/gitlab/gitlab-assets-ee:master
-
Create a container using that image:
docker create --name gitlab_asset_cache registry.gitlab.com/gitlab-org/gitlab/gitlab-assets-ee:master
-
Copy the asset directory from the container to the host:
docker cp gitlab_asset_cache:/assets ~/gitlab-assets
-
While starting the build environment container, mount the asset directory in it:
docker run -v ~/omnibus-gitlab:/omnibus-gitlab -v ~/gitlab-assets:/gitlab-assets -it registry.gitlab.com/gitlab-org/gitlab-omnibus-builder/debian_10:${BUILDER_IMAGE_REVISION} bash
-
Instead of setting
COMPILE_ASSETS
to true, set the path where assets can be found:export ASSET_PATH=/gitlab-assets
Build the package
After you have prepared the build environment and have made necessary changes, you can build packages using the provided Rake tasks:
-
For builds to work, Git working directory should be clean. So, commit your changes to a new branch.
-
Run the Rake task to build the package:
bundle exec rake build:project
The packages are built and made available in the ~/omnibus-gitlab/pkg
directory.
Build an EE package
By default, omnibus-gitlab
builds a CE package. If you want to build an EE
package, set the ee
environment variable before running the Rake task:
export ee=true
Clean files created during build
You can clean up all temporary files generated during the build process using
omnibus
’s clean
command:
bin/omnibus clean gitlab
Adding the --purge
purge option removes all files generated during the
build including the project install directory (/opt/gitlab
) and
the package cache directory (/var/cache/omnibus/pkg
):
bin/omnibus clean --purge gitlab
Get help on Omnibus
For help with the Omnibus command-line interface, run the
help
command:
bin/omnibus help