Run docker in docker and gitlab runner on host but execute all pipelines inside the docker in docker container

compose.yaml

services:
  docker:
    image: docker:dind
    container_name: docker
    privileged: true
    volumes:
      - docker_certs:/certs/client
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "docker ps || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

  gitlab-runner:
    image: gitlab/gitlab-runner
    container_name: gitlab-runner
    depends_on:
      - docker
    volumes:
      # either provide existing config or create a new one 
      # - gitlab-runner-config:/etc/gitlab-runner
      - /srv/gitlab-runner/config:/etc/gitlab-runner
      - docker_certs:/certs/client
    environment:
      DOCKER_HOST: "tcp://docker:2376"
      DOCKER_TLS_VERIFY: "true"
      DOCKER_CERT_PATH: "/certs/client"
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "gitlab-runner --version || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

volumes:
  docker_certs:

# register a new executor and create a config
# docker compose exec -it gitab-runner gitlab-runner register
# or
# docker compose run -it gitab-runner register

graph.txt

This Compose file executes the all tasks not on the hosts docker engine but
uses the docker in docker, separating docker environments on shared hosts.

                 ┌─────────────────────────────────┐
                 │         Docker Host             │
                 │ (where docker-compose runs)     │
                 └─────────────┬───────────────────┘
                               │
                               │  (docker-compose up)
                               ▼
    ┌─────────────────────────────────────────┐
    │ Service: "docker" (docker:dind)         │
    │-----------------------------------------│
    │  - privileged: true                     │
    │  - listens on tcp://0.0.0.0:2376        │
    │  - DOCKER_TLS_CERTDIR=/certs            │
    │  - Mounts named volume: /certs          │
    │-----------------------------------------│
    │  ┌───────────────────────────────────┐  │
    │  │   Ephemeral Container (Java)      │  │
    │  │  launched by GitLab Runner for    │<──────┐
    │  │  pipeline build/test steps.       │  │    │
    │  └───────────────────────────────────┘  │    │
    └─────────────────────────┬───────────────┘    │
                              │                    │
    (internal Docker network) │                    │ (runs container inside DinD) 
                              │                    │
                              ▼                    │
    ┌─────────────────────────────────────────┐    │
    │  Service: "gitlab-runner"               │    │
    │   (gitlab/gitlab-runner)                │    │
    │-----------------------------------------│    │
    │  - depends_on: ["docker"]               │    │
    │  - environment:                         │    │
    │       DOCKER_HOST=tcp://docker:2376     │    │
    │       DOCKER_TLS_VERIFY=true            │←───┘
    │       DOCKER_CERT_PATH=/certs/client    │
    │  - Mounts /srv/gitlab-runner/config →   │
    │                       /etc/gitlab-runner│
    │  - Mounts named volume: /certs          │
    │-----------------------------------------│
    │    (Triggers ephemeral containers via   │
    │     Docker-in-Docker for CI/CD jobs)    │
    └─────────────────────────────────────────┘



The general setup looks like this.

                  ┌─────────────────────────────────┐
                  │      Docker Host (Linux)        │
                  │  (running Docker daemon)        │
                  └─────────────────────────────────┘
                             ↑
                             │  /var/run/docker.sock
                             │  (host Docker socket)
                             │
                             │    (docker run ... )
                             │
                             ▼
          ┌─────────────────────────────────────────┐
          │   Container: gitlab-runner              │
          │     (gitlab/gitlab-runner)              │
          │-----------------------------------------│
          │  - Volume mount:                        │
          │     /var/run/docker.sock:/var/run/docker.sock
          │  - Uses host Docker daemon socket       │
          │  - Orchestrates pipeline steps          │
          │-----------------------------------------│
          │   (When building a Java app, spins up   │
          │    ephemeral containers via the host's  │
          │    Docker daemon)                       │
          └─────────────────────────┬───────────────┘
                                    │
                                    │   (Host Docker Daemon creates ephemeral containers)
                                    │
                                    ▼
                   ┌───────────────────────────────────┐
                   │  Ephemeral Container (Java)       │
                   │  launched by GitLab Runner        │
                   │  for build/test steps             │
                   └───────────────────────────────────┘