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.

  1. Install Docker.

    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.

  2. 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 configuration BUILDER_IMAGE_REVISION environment variable. 

    docker pull registry.gitlab.com/gitlab-org/gitlab-omnibus-builder/debian_10:${BUILDER_IMAGE_REVISION}

  3. 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

  4. 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

  5. By default, omnibus-gitlab chooses public GitLab repositories to fetch sources of various GitLab components. Set the environment variable ALTERNATIVE_SOURCES to false to build from dev.gitlab.org. 

    export ALTERNATIVE_SOURCES=false

    Component source information is in the .custom_sources.yml file.

  6. 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 the COMPILE_ASSETS environment variable. 

    export COMPILE_ASSETS=true

  7. 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 and a slight increase in installation (decompression) 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 to false: 

    export COMPRESS_XZ=false

  8. 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:

  1. 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

  2. Create a container using that image: 

    docker create --name gitlab_asset_cache registry.gitlab.com/gitlab-org/gitlab/gitlab-assets-ee:master

  3. Copy the asset directory from the container to the host: 

    docker cp gitlab_asset_cache:/assets ~/gitlab-assets

  4. 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

  5. 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:

  1. For builds to work, Git working directory should be clean. So, commit your changes to a new branch.

  2. 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