Cómo montar GitLab en tu Mac con Docker: guía completa paso a paso

Montar un entorno profesional de GitLab en tu propio Mac es más fácil de lo que parece si sigues una guía bien estructurada. En esta primera etapa vamos a preparar todo lo necesario para lanzar GitLab usando Docker y garantizar un entorno estable y organizado.

Requisitos previos

Antes de continuar, asegúrate de tener lo siguiente en tu equipo:

• macOS 12 o superior
• Docker Desktop para Mac instalado y funcionando
• Acceso a terminal (puedes usar la app Terminal o iTerm2)
• Conexión a Internet

Paso 1: Verifica si tienes Docker instalado

Abre tu terminal y ejecuta:

docker -v

Deberías ver algo como:

Docker version 24.0.6, build abc123

Si no tienes Docker, puedes instalarlo desde:

👉 https://www.docker.com/products/docker-desktop/

Paso 2: Crea una carpeta para tu entorno GitLab

Organizaremos todo el entorno en una carpeta específica para facilitar los backups y la estructura de proyectos.

mkdir -p ~/gitlab/docker
cd ~/gitlab/docker

Crea carpetas para futuros volúmenes:

mkdir -p config data logs

Paso 3: Crea el archivo docker-compose.yml

En la ruta ~/gitlab/docker, crea el siguiente archivo:

nano docker-compose.yml

Pega este contenido mínimo funcional:

version: '3.6'

services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    platform: linux/amd64
    hostname: gitlab.local
    restart: always
    ports:
      - "8080:80"
      - "8443:443"
      - "2222:22"
    volumes:
      - ./config:/etc/gitlab
      - ./logs:/var/log/gitlab
      - ./data:/var/opt/gitlab

Paso 4: Levanta el contenedor de GitLab

Desde la misma carpeta, ejecuta:

docker compose up -d

Este paso puede tardar varios minutos la primera vez (descarga + configuración inicial).

Paso 5: Accede a GitLab desde el navegador

Cuando finalice, abre tu navegador y entra a:

http://localhost:8080

Deberías ver la pantalla de creación de contraseña para el usuario root.

Paso 6: Configuración inicial de GitLab CE en macOS

Una vez que tienes GitLab funcionando en http://localhost:8080, es hora de hacer la configuración inicial.

En esta etapa configuraremos el usuario administrador, la estructura base de proyectos, los ajustes recomendados de seguridad y organización para que tu GitLab quede listo para desarrollos reales.

Crear la contraseña del usuario root

Al acceder por primera vez a http://localhost:8080, serás redirigido automáticamente a:

http://localhost:8080/users/sign_in

Si es tu primer acceso:

GitLab te mostrará un formulario para establecer la contraseña del usuario administrador (root). Introduce una contraseña segura y guárdala.

💡 Este usuario tiene control total sobre toda la instancia de GitLab.

Si ya habías accedido antes:

Te pedirá iniciar sesión con root y la contraseña establecida previamente.

Problemas comunes al montar GitLab en macOS

Durante la instalación de GitLab CE en macOS con Docker pueden surgir algunos problemas, especialmente si usas un Mac con chip Apple Silicon (M1, M2, M3). A continuación documentamos los errores más relevantes que resolvimos:

Error 1: La arquitectura de la imagen no coincide

Mensaje:

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

Solución: especifica manualmente la plataforma en el archivo docker-compose.yml:

platform: linux/amd64

Esto fuerza a Docker a emular la arquitectura x86 en tu Mac ARM.

Error 2: PostgreSQL did not respond before service checks were exhausted

Mensaje:

RuntimeError: PostgreSQL did not respond before service checks were exhausted

Causa: GitLab arranca antes de que PostgreSQL esté completamente listo (especialmente en sistemas lentos o con pocos recursos asignados).

Soluciones:

1. Aumenta los recursos de Docker Desktop:
   • Mínimo 4 GB de RAM
   • Al menos 2 CPUs
2. Borra el entorno y vuelve a desplegar limpio:

docker compose down -v
docker rmi -f gitlab/gitlab-ce
rm -rf config data logs
mkdir config data logs

3. Reinicia con docker compose up -d y ten paciencia. GitLab puede tardar varios minutos la primera vez.

Error 3: Docker Desktop no se abre en macOS

Síntoma: haces clic y no se inicia Docker Desktop.

Soluciones:

1. Forza el cierre desde terminal:

killall Docker
open -a Docker

Si sigue sin funcionar, elimina la caché:

rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

3. Reinicia el sistema