Self-Hosting GitLab on Proxmox VE

Why Self-Host GitLab?

GitLab CE (Community Edition) gives you a full DevOps platform — Git repositories, CI/CD pipelines, container registries, issue tracking, and wikis — entirely under your control. Self-hosting on Proxmox VE means your code never leaves your network, you get unlimited private repositories, and you control the upgrade schedule. For teams, freelancers, or homelab enthusiasts who want a GitHub-like experience without subscription costs, GitLab CE on Proxmox is the best path.

Resource Requirements

GitLab is a resource-hungry application. Under-provisioning will result in slow page loads and failed CI jobs. Here are realistic minimums:

• CPU: 4 cores minimum, 8 cores recommended for CI workloads
• RAM: 8 GB minimum (GitLab uses 4-6 GB at idle), 16 GB recommended
• Storage: 50 GB for the application, plus space for repositories and CI artifacts
• Network: Standard bridged networking is sufficient

VM vs LXC

A VM is the safer choice for GitLab. The Omnibus installer expects full control over the system (it bundles its own PostgreSQL, Redis, Nginx, and more), which can conflict with other services in a container. An LXC container works if you are experienced with container limitations, but a VM avoids potential issues with systemd, overlapping ports, and memory accounting.

Creating the VM and Installing GitLab

# Create the VM
qm create 160 \
  --name gitlab \
  --memory 8192 \
  --cores 4 \
  --cpu cputype=host \
  --scsihw virtio-scsi-single \
  --scsi0 local-lvm:80,iothread=1 \
  --net0 virtio,bridge=vmbr0 \
  --ostype l26

# Install Ubuntu 22.04, then inside the VM:
apt update && apt upgrade -y
apt install -y curl openssh-server ca-certificates perl postfix

Install GitLab CE using the official Omnibus package:

# Add the GitLab repository
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | bash

# Install GitLab CE — set your domain or IP
EXTERNAL_URL="https://gitlab.example.com" apt install -y gitlab-ce

# The installation takes 5-10 minutes
# When complete, retrieve the initial root password
cat /etc/gitlab/initial_root_password

Essential Configuration

After installation, edit the main configuration file to tune GitLab for your environment:

# /etc/gitlab/gitlab.rb — key settings

# External URL (must match how users access GitLab)
external_url 'https://gitlab.example.com'

# Reduce memory usage by disabling unneeded services
prometheus_monitoring['enable'] = false
grafana['enable'] = false
sentinel['enable'] = false

# Limit Puma workers to reduce memory footprint
puma['worker_processes'] = 2
puma['min_threads'] = 1
puma['max_threads'] = 4

# Limit Sidekiq concurrency
sidekiq['max_concurrency'] = 10

# Configure email notifications
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your-email@gmail.com"
gitlab_rails['smtp_password'] = "your-app-password"
gitlab_rails['smtp_domain'] = "gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

# Apply configuration changes
gitlab-ctl reconfigure

# Check service status
gitlab-ctl status

SSL with Let's Encrypt

If your GitLab instance is publicly accessible, the Omnibus package can handle SSL automatically:

# In /etc/gitlab/gitlab.rb
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = 3
letsencrypt['auto_renew_day_of_month'] = "*/7"

# Apply changes
gitlab-ctl reconfigure

Setting Up GitLab Runners

GitLab Runners execute your CI/CD pipelines. Running the Runner in a separate VM or container is recommended so that CI jobs do not compete with GitLab itself for resources:

# Create a lightweight VM or LXC for the runner
# Then install the GitLab Runner:
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | bash
apt install -y gitlab-runner

# Register the runner with your GitLab instance
gitlab-runner register \
  --url https://gitlab.example.com \
  --token YOUR_REGISTRATION_TOKEN \
  --executor docker \
  --docker-image ubuntu:22.04 \
  --description "proxmox-runner-01"

The Docker executor is the most flexible — each CI job runs in a fresh container, preventing state leakage between builds. Install Docker in the runner VM:

# Install Docker for the runner executor
apt install -y docker.io
usermod -aG docker gitlab-runner
systemctl enable docker

Backup Strategy

GitLab provides a built-in backup command that dumps repositories, database, uploads, and CI artifacts into a single tarball:

# Run a manual backup
gitlab-backup create

# Backups are stored in /var/opt/gitlab/backups/
ls -lh /var/opt/gitlab/backups/

# IMPORTANT: The backup does NOT include secrets
# You must also back up these files separately:
# /etc/gitlab/gitlab-secrets.json
# /etc/gitlab/gitlab.rb

Automate backups with a cron job and clean up old archives:

# /etc/cron.d/gitlab-backup
0 2 * * * root gitlab-backup create CRON=1 BACKUP=daily 2>&1 | logger -t gitlab-backup

# In /etc/gitlab/gitlab.rb — keep 7 days of backups
gitlab_rails['backup_keep_time'] = 604800

# Back up secrets separately
0 2 * * * root cp /etc/gitlab/gitlab-secrets.json /var/opt/gitlab/backups/gitlab-secrets-$(date +\%F).json
0 2 * * * root cp /etc/gitlab/gitlab.rb /var/opt/gitlab/backups/gitlab-rb-$(date +\%F).rb

In addition to application-level backups, take periodic Proxmox snapshots of the GitLab VM before major upgrades. This gives you a complete rollback point at the hypervisor level.

Monitoring GitLab Health

GitLab exposes health check endpoints that you can poll to verify the application is responsive:

# Liveness check
curl -s https://gitlab.example.com/-/liveness

# Readiness check (checks database, Redis, Gitaly)
curl -s https://gitlab.example.com/-/readiness

Since GitLab is a critical service that other development workflows depend on, knowing immediately when the VM is down matters. ProxmoxR can give you a quick glance at your GitLab VM's status and resource consumption from your phone — particularly useful after applying GitLab or Proxmox updates that require reboots.

Conclusion

Self-hosting GitLab on Proxmox gives you a complete DevOps platform with zero recurring costs. The VM approach provides the most reliable deployment, GitLab Runners in separate containers keep CI isolated, and the combination of GitLab backups plus Proxmox snapshots ensures your code and configuration are always recoverable. With proper resource allocation, even a modest homelab server can comfortably host GitLab for a small team.