How to install GitLab CE on AlmaLinux 9

You will install GitLab Community Edition on AlmaLinux 9 using the official Omnibus package. This method is recommended for production environments because it bundles all necessary components including the web server, application server, and database. The steps below target AlmaLinux 9 and ensure that GitLab runs as a reliable service.

Prerequisites

• Operating System: AlmaLinux 9 (latest minor release)
• RAM: Minimum 4GB available memory (8GB recommended for production)
• Storage: At least 20GB free disk space
• Network: Access to external repositories for package updates
• Privileges: Root access or sudo privileges

Step 1: Update the system and install dependencies

Before installing GitLab, ensure your system packages are current and install the required dependencies like curl, vim, and wget. These tools are necessary for the installation scripts and configuration management.

dnf update -y
dnf install -y curl vim wget git

You will see a progress bar during the update process. Once the output shows "Complete!", the system is ready for the next step.

Step 2: Download the GitLab Omnibus package

Download the latest stable version of the GitLab Omnibus package from the official repository. The package is a single tarball that contains the entire GitLab stack. Use the curl command to fetch the latest version available.

curl -L https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | bash

The script will automatically detect your OS version and install the necessary dependencies. You will see a message indicating that the package is being downloaded and installed.

GitLab Omnibus package is being downloaded...
GitLab Omnibus package is being installed...

Step 3: Configure the GitLab service

Configure GitLab to run as a service. Edit the configuration file to set the external URL and other settings. The default configuration file is located at /etc/gitlab/gitlab.rb. Open the file with vim and update the external_url variable.

vim /etc/gitlab/gitlab.rb

Add or modify the following lines in the file to set your domain name and enable HTTPS:

external_url 'https://your-domain.com'
nginx['listen_port'] 80
nginx['listen_port_ssl'] 443
nginx['ssl_certificate'] '/etc/gitlab/ssl/your-domain.crt'
nginx['ssl_certificate_key'] '/etc/gitlab/ssl/your-domain.key'

Save the file and exit the editor. Then reconfigure GitLab to apply the changes.

gitlab-ctl reconfigure

The command will take several minutes to complete. You will see progress messages as GitLab restarts the web server and application services.

Step 4: Start and enable the GitLab service

Start the GitLab service and enable it to start on boot. This ensures that GitLab runs automatically when the server reboots. Use the systemctl command to manage the service state.

systemctl start gitlab
systemctl enable gitlab

Check the status of the service to ensure it is running correctly. You should see "active (running)" in the output.

systemctl status gitlab

If the service is active, you will see "Active: active (running)" and the main process ID.

Verify the installation

Access the GitLab web interface using your domain name or IP address. The default login URL is http://your-server-ip or https://your-domain.com. You will see the GitLab login page with the default branding. If you configured SSL certificates, the connection will be secure.

Run the following command to check if the service is listening on port 80 and 443:

netstat -tlnp | grep gitlab

You should see output indicating that ports 80 and 443 are listening for connections.

Troubleshooting

Error: "GitLab failed to start"
Check the logs for errors. Run gitlab-ctl tail to see real-time logs. Common causes include missing SSL certificates or incorrect external_url settings. Fix the configuration in /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure.

Error: "Port 80 or 443 is already in use"
Ensure no other service is using port 80 or 443. Use netstat -tlnp to check for conflicts. Stop the conflicting service or change the GitLab port in the configuration.

Error: "SSL certificate validation failed"
Verify that the SSL certificate and key files exist at the paths specified in /etc/gitlab/gitlab.rb. Ensure the certificate is valid and not expired. Restart the service after updating the certificate paths.

Error: "Database connection failed"
Check the database service status with systemctl status postgresql or systemctl status mysql. Ensure the database user has the correct permissions. Review the logs in /var/log/gitlab/gitlab-rails/log/production.log.

Error: "Permission denied when writing to /var/log/gitlab"
Ensure the git user owns the log directory. Run chown -R git:git /var/log/gitlab to fix ownership issues.

Error: "Memory allocation failed"
Increase the swap space on the server. Add a swap file with dd if=/dev/zero of=/swapfile bs=1G count=2 and set it up with mkswap /swapfile and swapon /swapfile.

Error: "Nginx configuration failed"
Check the Nginx logs at /var/log/nginx/error.log for syntax errors. Review the configuration file at /etc/gitlab/nginx/gitlab.conf for typos or missing directives.