Ubuntu 22.04 安装 GitLab EE 完全指南：从零搭建 Homelab 代码仓库

A step-by-step guide to help you avoid various pitfalls in GitLab installation, including mirror source selection, Let's Encrypt certificate issues, and user permission best practices.

Preface

Setting up a reliable code hosting platform in a Homelab environment is a necessity for many developers. GitLab, as the most comprehensive DevOps platform, is naturally the first choice. But during the actual installation process, you will encounter various unexpected problems—slow mirror sources, Let's Encrypt certificate errors, and even not knowing which account to use to manage code after installation is complete.

This paper is based on Real firsthand experience of pitfalls encountered, Records a complete GitLab EE installation process; all commands have been verified and can be reused directly.

Environmental information:

• Operating system: Ubuntu 22.04 LTS (Jammy)

• Target version: GitLab EE (GitLab Enterprise Edition v19.1.1-ee International Edition)

• Deployment mode: standalone deployment

• Access address:https://git.homelab.org(Intranet Homelab)

💡 Why plan HTTPS and a custom domain from the start?

Define the external access address as https://git.homelab.org, is due to project or engineering needs. For example, when defining a repository for Golang's Go Module, it is necessary to specify a repository address, and through go get or go install all require HTTPS support, so that go module path This allows seamless integration with dependencies!

And in GitLab Enterprise Edition v19.1.1-ee, a self-signed certificate is automatically generated during installation!

第一步：系统准备

Update the system and install dependencies.

Before installing GitLab, first ensure the system is up to date and install the necessary dependency packages:

sudo apt update
sudo apt install -y curl openssh-server ca-certificates tzdata perl

Among these dependencies:

• curl: Used to download and install scripts

• openssh-server: SSH service, the cornerstone for Git to access repositories via the SSH protocol

• ca-certificates: SSL Certificate Verification

• tzdata Time zone data, affecting GitLab's log timestamps

Step 2: Add the GitLab software repository

Option 1: Official source (alternative)

curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

⚠️Attention: The official source server is overseas, so domestic download speeds may be only tens of KB/s. The installation package is about 1.1 GB and may take 30–60 minutes. If your patience is limited, go straight to Option 2.

Option 2: Tsinghua University mirror source (recommended)

Domestic users Strongly recommended Using the Tsinghua mirror, speeds can reach 10-20 MB/s:

# Clean up any potentially existing old sources.
sudo rm -f /etc/apt/sources.list.d/gitlab*.list

# Add the Tsinghua mirror source
echo "deb [arch=amd64] https://mirrors.tuna.tsinghua.edu.cn/gitlab-ee/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/gitlab-ee.list

# Add GPG key (used to verify package integrity)
curl -fsSL https://packages.gitlab.com/gitlab/gitlab-ee/gpgkey | sudo gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/gitlab-ee.gpg > /dev/null

# Update software sources
sudo apt update

💡Why use the Tsinghua mirror?: The GitLab installation package is about 1.1GB, and using a domestic mirror source can shorten the download time from 1 hour to 5–10 minutes.

Step 3: Install GitLab EE (Critical)

Correct installation command

sudo EXTERNAL_URL="https://git.homelab.org" apt install -y gitlab-ee

🔥 Common pitfalls: Let's Encrypt certificate errors

If you see an error like this:

Acme::Client::Error::RejectedIdentifier: Cannot issue for "git.homelab.org": IP address is in a reserved address block

reason: GitLab enables automatic Let's Encrypt certificate requests by default, but Let's Encrypt Certificates are not allowed to be issued for internal domain names (which resolve to internal IP addresses)..

Solution: During installation, explicitly disable Let's Encrypt and use the self-signed certificate we generated:

sudo EXTERNAL_URL="https://git.homelab.org" \
  GITLAB_OMNIBUS_CONFIG="letsencrypt['enable'] = false" \
  apt install -y gitlab-ee

If an error occurs halfway through the installation, you can manually modify the configuration file:

# Edit configuration file
sudo vim /etc/gitlab/gitlab.rb

# Modify the following configuration
external_url "https://git.homelab.org"
letsencrypt['enable'] = false

# Reconfigure after saving
sudo gitlab-ctl reconfigure

💡 Tip

Although the browser will display "Not Secure" (because the certificate is not trusted), but It does not affect HTTPS encrypted transmission at all., and it does not affect go get the use of tools such as … (requires configuring Git to skip SSL verification or import a self-signed certificate).

Configure Git to skip SSL verification (internal network development environments only)

If you don't want to deal with the trust issue of self-signed certificates, you can configure Git to globally skip SSL verification (Only recommended for use in an intranet Homelab.):

git config --global http.sslVerify false

For Go Modules, configure private repositories to skip verification:

go env -w GOPRIVATE="git.homelab.org"
go env -w GONOSUMDB="git.homelab.org"

Step 4: Post-installation configuration

Get initial password

After GitLab installation is complete, a random password is generated and automatically deleted after 24 hours:

sudo cat /etc/gitlab/initial_root_password

Output example:

Username: root
Password: ohJeIshzXE56HD5a+ubsEVyIdscYLxJIclhn1qUQg8g

Configure local hosts mapping

On the computer that accesses GitLab, configure the hosts file to point the domain name to the GitLab server:

# /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows)
192.168.0.234  git.homelab.org

📌 will 192.168.0.234 Replace it with the IP address of the server where you actually installed GitLab.

Log in to GitLab

Browser access:https://git.homelab.org

• Username:root

• Password: the initial password found above

Step 5: User Permission Best Practices (Must Read)

⚠️ Do not use root Do daily operations!

This is a Very important the security principles:

场景	Use account	Reason
System Configuration, User Management, Global Settings	root	Highest privileges, for management use only
Daily code commits, project creation, and repository management	Regular users (such as fishfinal)	Principle of least privilege, secure and controllable

Why?

• Security risk:root Having control over the entire instance means that once it is leaked, all projects are at risk.

• Audit chaos: Shared by multiple people root Unable to trace the operator

• Permission granularity:root Can see all private projects and cannot simulate the permission boundaries of a regular user.

Create a regular user

• Use root Login →Admin Area→Users→New user

• Enter username (e.g.fishfinal), email

• Select Regular(regular user), not Administrator

• Click Create user

Set user password

There are two ways to set a password for new users:

Method 1: Configure via Web UI

After creating a user, go to the user list → click Edit→ at Password Set the region password → Save. Users will be forced to change their password on first login.

Method 2: Configure via the Rails console

If Homelab has not configured an SMTP email service, you can also set the password via the command line:

sudo gitlab-rails console -e production

# Find user
user = User.find_by_username('fishfinal')

# 设置密码
user.password = 'your password'
user.password_confirmation = 'your password'
user.save!

# Exit
exit

Step 6: Configure SSH keys (passwordless push)

After logging in to GitLab as a regular user:

• Click the avatar in the upper right corner →Preferences → SSH Keys

• Generate an SSH key in the terminal (if you don't have one yet):

ssh-keygen -t ed25519 -C "[email protected]"
cat ~/.ssh/id_ed25519.pub

• Paste the public key content into GitLab's SSH Key input box, and click Add key

After that, you can clone the repository using the SSH protocol without entering your password each time:

git clone [email protected]:fishfinal/my-project.git

Step 7: Common Management Commands

After installation is complete, familiarizing yourself with these commands will help with daily maintenance:

# View all service statuses
sudo gitlab-ctl status

# Start/Stop/Restart
sudo gitlab-ctl start
sudo gitlab-ctl stop
sudo gitlab-ctl restart

# Reapply after modifying the configuration.
sudo gitlab-ctl reconfigure

# View real-time logs (for troubleshooting)
sudo gitlab-ctl tail

Configuration file location:/etc/gitlab/gitlab.rb

Summary and Recommendations

• Domestic users must use mirror sources.: Tsinghua mirrors can save a lot of time.

• Plan HTTPS and domain names in advance: Prepare for tools such as Go Module and Maven

• Use self-signed certificates for intranet deployment.: Also disable Let's Encrypt to avoid errors.

• Strictly distinguish root and regular users This is the safety bottom line.

• Configure SSH key: Significantly improve the daily use experience

FAQ Quick Reference

Question	Solution
The installation package download is too slow.	Switch to the Tsinghua mirror
Let's Encrypt error	Disable Let's Encrypt and use a self-signed certificate
Browser displays Not secure.	Import the self-signed certificate into the system trust store, or configure Git to skip SSL verification.
go get Private repository error	configuration GOPRIVATE and GONOSUMDB
Forget root password	sudo gitlab-rails console -e production Reset
Not receiving the password reset email	Edit the user in the Web UI to set a password, or set it via the command line.

Next step

After GitLab is installed, you can continue with configuration:

• CI/CD Runner Implement automated build and deployment

• SMTP email service: Enable GitLab to send notification emails

• Project Backup Strategy: Regular backup /var/opt/gitlab/ Table of Contents

• Go Module private repository: Configuration GOPROXY and GOPRIVATE Implement seamless dependency management