docker.recipes

GitLab CI/CD Complete Stack

advanced

Self-hosted GitLab with integrated CI/CD runners, container registry, and monitoring

Overview

GitLab is a complete DevOps platform that originated in 2011 as a self-hosted Git repository manager and evolved into a comprehensive solution covering the entire software development lifecycle. Unlike distributed DevOps toolchains requiring integration between multiple vendors, GitLab provides source code management, CI/CD pipelines, container registry, issue tracking, security scanning, and monitoring in a unified platform. This makes it particularly valuable for organizations seeking to reduce tool sprawl and streamline their development workflow. This stack combines GitLab's core platform with dedicated GitLab Runners for CI/CD execution, MinIO for S3-compatible artifact storage, and built-in Prometheus and Grafana integration for comprehensive monitoring. The multiple runner configuration provides concurrent job execution and fault tolerance, while MinIO handles large artifact storage requirements that would otherwise burden GitLab's main storage. This architecture creates a production-grade CI/CD environment capable of handling enterprise workloads with proper resource allocation and monitoring visibility. Development teams, DevOps engineers, and organizations transitioning from hosted solutions like GitHub Actions or Jenkins will find this stack provides enterprise-level capabilities with complete data sovereignty. The integrated monitoring through Prometheus and Grafana offers insights into both GitLab performance and CI/CD pipeline metrics, making it ideal for teams that need visibility into their development infrastructure performance and want to optimize build times and resource utilization.

Key Features

  • Complete DevOps platform with integrated Git repositories, issue tracking, merge requests, and wiki documentation
  • Built-in CI/CD pipelines with YAML configuration supporting complex workflows, parallel jobs, and deployment strategies
  • Integrated Docker container registry for storing and managing application images with vulnerability scanning
  • Multiple GitLab Runner instances providing concurrent job execution and high availability for CI/CD workloads
  • MinIO S3-compatible storage backend for GitLab artifacts, uploads, and Git LFS objects
  • Built-in Prometheus monitoring with GitLab-specific metrics and performance insights
  • Integrated Grafana dashboards for visualizing GitLab performance, runner utilization, and pipeline metrics
  • Auto DevOps capabilities with automatic CI/CD pipeline generation based on detected project types

Common Use Cases

  • 1Enterprise software development teams needing complete DevOps platform with on-premises data control
  • 2Organizations migrating from Jenkins or GitHub Actions seeking integrated CI/CD with better pipeline visualization
  • 3Development teams requiring private container registry alongside their source code and CI/CD infrastructure
  • 4Companies building microservices architectures needing coordinated multi-project CI/CD with shared runners
  • 5DevOps teams implementing GitOps workflows with integrated monitoring and alerting capabilities
  • 6Educational institutions teaching DevOps practices with a complete, self-contained development platform
  • 7Startups and small companies wanting enterprise-grade DevOps tools without SaaS subscription costs

Prerequisites

  • Minimum 8GB RAM recommended for GitLab, with additional 2GB for runners and monitoring components
  • Docker and Docker Compose installed with at least 50GB available disk space for repositories and artifacts
  • Ports 80, 443, 22, 5050, 9000, and 9001 available for GitLab, registry, and MinIO access
  • Understanding of Git workflows, CI/CD concepts, and Docker containerization principles
  • Basic knowledge of YAML for GitLab CI pipeline configuration and Docker Compose management
  • Familiarity with Prometheus metrics and Grafana dashboard concepts for monitoring setup

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  gitlab: 
3    image: gitlab/gitlab-ee:latest
4    container_name: gitlab
5    restart: unless-stopped
6    hostname: gitlab.local
7    ports: 
8      - "${HTTP_PORT:-80}:80"
9      - "${HTTPS_PORT:-443}:443"
10      - "${SSH_PORT:-22}:22"
11    volumes: 
12      - gitlab_config:/etc/gitlab
13      - gitlab_logs:/var/log/gitlab
14      - gitlab_data:/var/opt/gitlab
15    environment: 
16      GITLAB_OMNIBUS_CONFIG: |
17        external_url 'http: //${GITLAB_HOST:-localhost}'
18        gitlab_rails['gitlab_shell_ssh_port'] = ${SSH_PORT: -22}
19        registry_external_url 'http: //${REGISTRY_HOST:-registry.localhost}:5050'
20        prometheus_monitoring['enable'] = true
21        grafana['enable'] = true
22    shm_size: '256m'
23
24  gitlab-runner: 
25    image: gitlab/gitlab-runner:latest
26    container_name: gitlab-runner
27    restart: unless-stopped
28    volumes: 
29      - ./runner-config:/etc/gitlab-runner
30      - /var/run/docker.sock:/var/run/docker.sock
31    depends_on: 
32      - gitlab
33
34  gitlab-runner-2: 
35    image: gitlab/gitlab-runner:latest
36    container_name: gitlab-runner-2
37    restart: unless-stopped
38    volumes: 
39      - ./runner-config-2:/etc/gitlab-runner
40      - /var/run/docker.sock:/var/run/docker.sock
41    depends_on: 
42      - gitlab
43
44  minio: 
45    image: minio/minio:latest
46    container_name: gitlab-minio
47    restart: unless-stopped
48    ports: 
49      - "${MINIO_PORT:-9000}:9000"
50      - "${MINIO_CONSOLE:-9001}:9001"
51    environment: 
52      - MINIO_ROOT_USER=${MINIO_USER:-minioadmin}
53      - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD:-minioadmin}
54    volumes: 
55      - minio_data:/data
56    command: server /data --console-address ":9001"
57
58volumes: 
59  gitlab_config: 
60  gitlab_logs: 
61  gitlab_data: 
62  minio_data:

.env Template

.env
1# GitLab Complete Stack
2HTTP_PORT=80
3HTTPS_PORT=443
4SSH_PORT=22
5MINIO_PORT=9000
6MINIO_CONSOLE=9001
7
8# GitLab
9GITLAB_HOST=gitlab.localhost
10REGISTRY_HOST=registry.localhost
11
12# MinIO for artifacts storage
13MINIO_USER=minioadmin
14MINIO_PASSWORD=minioadmin

Usage Notes

  1. 1GitLab at http://localhost (first boot takes 5-10 minutes)
  2. 2Initial root password in: docker exec gitlab cat /etc/gitlab/initial_root_password
  3. 3Register runners: docker exec gitlab-runner gitlab-runner register
  4. 4Container registry at port 5050
  5. 5MinIO provides S3-compatible artifact storage
  6. 6Configure GitLab to use MinIO for artifacts, uploads, LFS

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

gitlab
gitlab:
  image: gitlab/gitlab-ee:latest
  container_name: gitlab
  restart: unless-stopped
  hostname: gitlab.local
  ports:
    - ${HTTP_PORT:-80}:80
    - ${HTTPS_PORT:-443}:443
    - ${SSH_PORT:-22}:22
  volumes:
    - gitlab_config:/etc/gitlab
    - gitlab_logs:/var/log/gitlab
    - gitlab_data:/var/opt/gitlab
  environment:
    GITLAB_OMNIBUS_CONFIG: |
      external_url 'http://${GITLAB_HOST:-localhost}'
      gitlab_rails['gitlab_shell_ssh_port'] = ${SSH_PORT:-22}
      registry_external_url 'http://${REGISTRY_HOST:-registry.localhost}:5050'
      prometheus_monitoring['enable'] = true
      grafana['enable'] = true
  shm_size: 256m
gitlab-runner
gitlab-runner:
  image: gitlab/gitlab-runner:latest
  container_name: gitlab-runner
  restart: unless-stopped
  volumes:
    - ./runner-config:/etc/gitlab-runner
    - /var/run/docker.sock:/var/run/docker.sock
  depends_on:
    - gitlab
gitlab-runner-2
gitlab-runner-2:
  image: gitlab/gitlab-runner:latest
  container_name: gitlab-runner-2
  restart: unless-stopped
  volumes:
    - ./runner-config-2:/etc/gitlab-runner
    - /var/run/docker.sock:/var/run/docker.sock
  depends_on:
    - gitlab
minio
minio:
  image: minio/minio:latest
  container_name: gitlab-minio
  restart: unless-stopped
  ports:
    - ${MINIO_PORT:-9000}:9000
    - ${MINIO_CONSOLE:-9001}:9001
  environment:
    - MINIO_ROOT_USER=${MINIO_USER:-minioadmin}
    - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD:-minioadmin}
  volumes:
    - minio_data:/data
  command: server /data --console-address ":9001"

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  gitlab:
5    image: gitlab/gitlab-ee:latest
6    container_name: gitlab
7    restart: unless-stopped
8    hostname: gitlab.local
9    ports:
10      - "${HTTP_PORT:-80}:80"
11      - "${HTTPS_PORT:-443}:443"
12      - "${SSH_PORT:-22}:22"
13    volumes:
14      - gitlab_config:/etc/gitlab
15      - gitlab_logs:/var/log/gitlab
16      - gitlab_data:/var/opt/gitlab
17    environment:
18      GITLAB_OMNIBUS_CONFIG: |
19        external_url 'http://${GITLAB_HOST:-localhost}'
20        gitlab_rails['gitlab_shell_ssh_port'] = ${SSH_PORT:-22}
21        registry_external_url 'http://${REGISTRY_HOST:-registry.localhost}:5050'
22        prometheus_monitoring['enable'] = true
23        grafana['enable'] = true
24    shm_size: '256m'
25
26  gitlab-runner:
27    image: gitlab/gitlab-runner:latest
28    container_name: gitlab-runner
29    restart: unless-stopped
30    volumes:
31      - ./runner-config:/etc/gitlab-runner
32      - /var/run/docker.sock:/var/run/docker.sock
33    depends_on:
34      - gitlab
35
36  gitlab-runner-2:
37    image: gitlab/gitlab-runner:latest
38    container_name: gitlab-runner-2
39    restart: unless-stopped
40    volumes:
41      - ./runner-config-2:/etc/gitlab-runner
42      - /var/run/docker.sock:/var/run/docker.sock
43    depends_on:
44      - gitlab
45
46  minio:
47    image: minio/minio:latest
48    container_name: gitlab-minio
49    restart: unless-stopped
50    ports:
51      - "${MINIO_PORT:-9000}:9000"
52      - "${MINIO_CONSOLE:-9001}:9001"
53    environment:
54      - MINIO_ROOT_USER=${MINIO_USER:-minioadmin}
55      - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD:-minioadmin}
56    volumes:
57      - minio_data:/data
58    command: server /data --console-address ":9001"
59
60volumes:
61  gitlab_config:
62  gitlab_logs:
63  gitlab_data:
64  minio_data:
65EOF
66
67# 2. Create the .env file
68cat > .env << 'EOF'
69# GitLab Complete Stack
70HTTP_PORT=80
71HTTPS_PORT=443
72SSH_PORT=22
73MINIO_PORT=9000
74MINIO_CONSOLE=9001
75
76# GitLab
77GITLAB_HOST=gitlab.localhost
78REGISTRY_HOST=registry.localhost
79
80# MinIO for artifacts storage
81MINIO_USER=minioadmin
82MINIO_PASSWORD=minioadmin
83EOF
84
85# 3. Start the services
86docker compose up -d
87
88# 4. View logs
89docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/gitlab-cicd-complete/run | bash

Troubleshooting

  • GitLab 502 error on startup: Wait 10-15 minutes for complete initialization, check docker logs gitlab for 'GitLab Workhorse started' message
  • Runners failing to connect: Verify runner registration token from GitLab admin area and ensure Docker socket permissions allow runner containers to spawn jobs
  • Container registry push failures: Check that external registry URL matches your domain configuration and port 5050 is accessible from client machines
  • MinIO connection errors in GitLab: Verify MINIO_ROOT_USER and MINIO_ROOT_PASSWORD match GitLab's object storage configuration in omnibus settings
  • High memory usage and OOM kills: Increase shared memory size beyond 256m and allocate at least 8GB system RAM for GitLab container
  • Prometheus metrics not appearing: Ensure prometheus_monitoring['enable'] = true in GitLab configuration and restart container to apply omnibus changes

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

gitlabgitlab-runnerregistryprometheusgrafana

Tags

#gitlab#ci-cd#git#registry#runners#devops

Category

DevOps & CI/CD

Related Recipes

Ad Space