# GitLab CE Complete Stack

> Self-hosted GitLab Community Edition with integrated CI/CD and container registry.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: gitlab-ce, gitlab-runner, redis, postgresql
- Tags: gitlab, git, ci-cd, registry, devops
- Source: https://docker.recipes/devops/gitlab-ce-complete

## Overview

GitLab Community Edition is a comprehensive DevOps platform that combines source code management, continuous integration/continuous deployment (CI/CD), container registry, and project management in a single application. Originally launched in 2011 as an open-source alternative to proprietary Git hosting solutions, GitLab CE has evolved into a complete software development lifecycle platform that rivals enterprise solutions while remaining free and self-hosted. Unlike cloud-based alternatives, GitLab CE gives organizations complete control over their code, data, and development processes.

This stack combines GitLab CE with PostgreSQL for robust data storage, Redis for high-performance caching and session management, and GitLab Runner for executing CI/CD pipelines. PostgreSQL handles GitLab's complex relational data including user accounts, project metadata, merge requests, and issue tracking, while Redis accelerates the platform by caching frequently accessed data and managing real-time features like notifications and live updates. GitLab Runner provides the compute engine for automated testing, building, and deployment workflows, creating a complete DevOps automation environment.

This configuration is ideal for development teams, startups, and organizations seeking enterprise-grade DevOps capabilities without vendor lock-in or subscription costs. Teams migrating from GitHub Enterprise, Bitbucket Server, or Jenkins-based workflows will find GitLab CE provides integrated functionality that eliminates the need for multiple disparate tools. The stack is particularly valuable for security-conscious organizations requiring on-premises code hosting and for teams implementing GitOps practices with built-in container registry and Kubernetes integration.

## Features

- Complete Git repository hosting with advanced branch protection and merge request workflows
- Integrated CI/CD pipelines with Docker-based runners and parallel job execution
- Built-in container registry supporting Docker images with vulnerability scanning
- Comprehensive project management including issues, milestones, epics, and Kanban boards
- Auto DevOps capabilities with automatic testing, security scanning, and deployment
- Wiki and documentation system with Markdown support and version control
- Advanced user management with LDAP/SAML integration and role-based permissions
- Built-in monitoring and analytics with deployment frequency and lead time metrics

## Use cases

- Enterprise teams transitioning from GitHub Enterprise or Bitbucket Server to self-hosted Git
- Development organizations implementing comprehensive DevSecOps with integrated security scanning
- Startups requiring complete DevOps platform without per-user licensing costs
- Educational institutions teaching software development with full project lifecycle tools
- Open source projects needing advanced CI/CD capabilities beyond basic Git hosting
- Companies in regulated industries requiring on-premises code and artifact storage
- Teams practicing GitOps with Kubernetes deployments and infrastructure as code

## Prerequisites

- Minimum 8GB RAM recommended (GitLab CE requires 4GB+ alone)
- At least 20GB available disk space for GitLab data, logs, and container registry
- Docker and Docker Compose installed with sufficient permissions
- Ports 80, 443, 2224, and 5050 available for web interface, SSH, and registry access
- Basic understanding of Git workflows and CI/CD concepts
- SMTP server credentials if email notifications are required

## docker-compose.yml

```yaml
services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    hostname: gitlab.local
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url '${GITLAB_EXTERNAL_URL}'
        gitlab_rails['gitlab_shell_ssh_port'] = 2224
        registry_external_url '${REGISTRY_EXTERNAL_URL}'
        gitlab_rails['smtp_enable'] = true
        gitlab_rails['smtp_address'] = "${SMTP_HOST}"
        gitlab_rails['smtp_port'] = ${SMTP_PORT}
        gitlab_rails['smtp_user_name'] = "${SMTP_USER}"
        gitlab_rails['smtp_password'] = "${SMTP_PASSWORD}"
        gitlab_rails['smtp_domain'] = "${SMTP_DOMAIN}"
        gitlab_rails['smtp_authentication'] = "login"
        gitlab_rails['smtp_enable_starttls_auto'] = true
        prometheus_monitoring['enable'] = false
        puma['worker_processes'] = 2
        sidekiq['max_concurrency'] = 10
    ports:
      - "80:80"
      - "443:443"
      - "2224:22"
      - "5050:5050"
    volumes:
      - gitlab-config:/etc/gitlab
      - gitlab-logs:/var/log/gitlab
      - gitlab-data:/var/opt/gitlab
    shm_size: '256m'
    networks:
      - gitlab-network
    restart: unless-stopped

  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    volumes:
      - gitlab-runner-config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - gitlab
    networks:
      - gitlab-network
    restart: unless-stopped

volumes:
  gitlab-config:
  gitlab-logs:
  gitlab-data:
  gitlab-runner-config:

networks:
  gitlab-network:
    driver: bridge
```

## .env

```bash
# GitLab CE Complete
GITLAB_EXTERNAL_URL=http://gitlab.local
REGISTRY_EXTERNAL_URL=http://registry.gitlab.local:5050

# SMTP Settings
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=gitlab@example.com
SMTP_PASSWORD=smtp_password
SMTP_DOMAIN=example.com
```

## Usage notes

- GitLab at http://localhost
- Initial root password in /etc/gitlab/initial_root_password
- Register runner: gitlab-runner register
- Container registry at :5050
- Requires 4GB+ RAM minimum

## Troubleshooting

- GitLab container exits with 'not enough shared memory': Increase shm_size to 512m or higher in docker-compose.yml
- 502 Bad Gateway on initial startup: Wait 5-10 minutes for GitLab's internal services to fully initialize before accessing web interface
- GitLab Runner registration fails with SSL errors: Use gitlab.local hostname or configure proper SSL certificates in GitLab configuration
- Container registry push fails with authentication errors: Ensure registry_external_url matches your domain and GitLab is fully started
- High memory usage causing system slowdown: Reduce puma worker_processes and sidekiq max_concurrency in GitLab configuration
- SSH clone fails on port 2224: Verify SSH key is added to GitLab profile and git remote URL uses correct port

