GitLab is a powerful, open-source DevOps platform that combines source code management, CI/CD pipelines, issue tracking, and more into a single application. Self-hosting GitLab provides unparalleled control over your data, customization options, and the ability to tailor the platform to meet your development needs. In this guide, we’ll cover everything from installation and configuration to leveraging GitLab’s unique features, ensuring you’re fully equipped to deploy, secure, and manage your instance.
Installing GitLab
📦 Docker/Docker Compose Setup
Using Docker Compose is one of the easiest and most efficient ways to deploy GitLab. Below is a docker-compose.yml file tailored for GitLab, including essential configurations for volumes, ports, and environment variables.
version: '3.6'
services:
gitlab:
image: gitlab/gitlab-ee:latest
container_name: gitlab
hostname: 'gitlab.local'
restart: always
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://gitlab.local'
gitlab_rails['gitlab_shell_ssh_port'] = 2222
ports:
- "80:80"
- "443:443"
- "2222:22" # SSH for Git
volumes:
- ./config:/etc/gitlab
- ./logs:/var/log/gitlab
- ./data:/var/opt/gitlab
Run the following commands to deploy GitLab:
mkdir gitlab && cd gitlab
curl -o docker-compose.yml https://raw.githubusercontent.com/your-repo/gitlab-docker-compose.yml
docker-compose up -d
This will spin up a GitLab container listening on HTTP, HTTPS, and SSH. Adjust the external_url in the configuration as needed.
🚀 Manual Installation on a Linux Server
For a direct installation on a Linux server, use the following commands. This example uses Ubuntu:
sudo apt-get update && sudo apt-get install -y curl openssh-server ca-certificates tzdata perl
## Add GitLab's official repository and install
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
sudo EXTERNAL_URL="http://gitlab.local" apt-get install gitlab-ee
After installation, access GitLab by navigating to http://<your-server-ip> in your browser.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve GitLab via Nginx, create the following configuration file:
server {
listen 80;
server_name gitlab.local;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Save the file as /etc/nginx/sites-available/gitlab and enable it:
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your GitLab installation with Let’s Encrypt:
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d gitlab.local
Test the SSL configuration and set up automated certificate renewal:
sudo certbot renew --dry-run
🛠️ Testing and Reloading Nginx
Check your Nginx configuration for syntax errors and reload it:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging GitLab
🗃️ Enabling Debug Logs
To enable debug-level logging in GitLab, modify the gitlab.rb configuration file:
sudo nano /etc/gitlab/gitlab.rb
Add or update the following lines:
gitlab_rails['log_level'] = 'debug'
Apply the changes:
sudo gitlab-ctl reconfigure
📄 Viewing Logs
Access GitLab logs via Docker:
docker logs gitlab
For manual installations, check the log files:
sudo tail -f /var/log/gitlab/gitlab-rails/production.log
🛠️ Troubleshooting Common Issues
Use the following command to analyze and identify issues:
sudo gitlab-ctl status
sudo gitlab-ctl tail
📤 Exporting Logs
To export logs to an ELK Stack, use Filebeat or Logstash. Install and configure Filebeat as an example:
sudo apt-get install filebeat
sudo nano /etc/filebeat/filebeat.yml
Update the configuration to point to your ELK server.
Backup and Restore
🗂️ File-Based Backups
Create a backup of GitLab’s configuration and data:
sudo gitlab-rake gitlab:backup:create
Backups will be saved in /var/opt/gitlab/backups.
🔄 Database Backups
To back up only the PostgreSQL database:
sudo gitlab-psql -d gitlabhq_production -c "COPY (SELECT * FROM users) TO STDOUT WITH CSV HEADER" > users_backup.csv
Restore the database from a backup:
sudo gitlab-psql gitlabhq_production < /path/to/backup.sql
📅 Automated Backup Scripts
Set up a cron job to automate periodic backups:
echo "0 2 * * * /usr/bin/gitlab-rake gitlab:backup:create" | sudo tee -a /etc/crontab
Updating and Upgrading GitLab
⬆️ Updating Docker Images
Pull the latest GitLab image and redeploy:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For a manually installed GitLab instance:
sudo apt-get update
sudo apt-get install gitlab-ee
🔍 Checking for Updates
Check whether updates are available:
sudo gitlab-ctl upgrade-check
Leveraging GitLab’s Unique Features
🔧 Enabling APIs
Activate GitLab’s REST and GraphQL APIs by ensuring they’re enabled in gitlab.rb:
sudo nano /etc/gitlab/gitlab.rb
Add the following:
gitlab_rails['api_max_requests'] = 1000
Test the API with curl:
curl --header "PRIVATE-TOKEN: <your-access-token>" http://gitlab.local/api/v4/projects
🌟 Advanced Configurations
Enable CI/CD pipelines:
sudo nano /etc/gitlab/gitlab.rb
Add:
ci_external_url 'http://gitlab.local'
Reconfigure GitLab:
sudo gitlab-ctl reconfigure
Wrapping Up
Self-hosting GitLab gives you complete control over your development workflow, data, and infrastructure. In this guide, we covered everything from setting up GitLab using Docker or manual installation, securing it with Nginx and SSL, debugging logs, automating backups, and utilizing GitLab’s powerful features like APIs and CI/CD pipelines. Start implementing these steps today to deploy a secure, robust, and feature-rich GitLab instance tailored to your needs.
