📦 코드를 올리면 자동으로 빌드된다: Docker + GitLab CI/CD 환경 구축기

“코드를 push하면 알아서 테스트하고 배포까지 해줬으면 좋겠다.”

이 바람을 현실로 만들어주는 것이 CI/CD 파이프라인입니다. 이번 과제에서는 Docker로 GitLab 서버를 직접 띄우고, GitLab Runner를 연결해 코드를 push하는 순간 자동으로 파이프라인이 실행되는 환경을 처음부터 구축해봤습니다.

---

📋 전체 구성 개요

구성 요소	역할
Docker + Docker Compose	컨테이너 기반 실행 환경
GitLab	코드 저장소 + CI/CD 오케스트레이터
GitLab Runner	실제 파이프라인 작업을 실행하는 에이전트
.gitlab-ci.yml	파이프라인 정의 파일

전체 흐름을 한 줄로 요약하면:

코드 Push → GitLab 감지 → Runner에게 작업 할당 → 컨테이너 안에서 빌드/테스트 실행 → 결과 보고

---

1. Docker & Docker Compose 설치 🐳

GPG 키 등록 및 공식 저장소 추가

Docker를 apt로 설치하려면 먼저 공식 저장소를 등록해야 합니다. GPG 키는 다운로드하는 패키지가 Docker에서 공식 배포한 것인지 검증하는 역할을 합니다. 변조된 패키지를 막는 일종의 디지털 서명 확인입니다.

시스템 아키텍처(dpkg --print-architecture)와 OS 버전(/etc/os-release)을 자동으로 감지해 환경에 맞는 저장소를 추가합니다.

GPG 키 등록 화면

저장소 추가 화면

Docker 엔진 + Compose 플러그인 설치

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

각 패키지의 역할:

• docker-ce: Docker 엔진 본체
• docker-ce-cli: 터미널에서 docker 명령어를 사용하기 위한 CLI 도구
• containerd.io: 컨테이너 실행을 담당하는 런타임
• docker-compose-plugin: docker compose 명령을 사용하기 위한 플러그인

WSL 환경에서 Docker 데몬을 시작하고, 현재 사용자를 docker 그룹에 추가해 sudo 없이 Docker 명령을 사용할 수 있도록 권한을 설정합니다.

Docker 데몬 시작 및 그룹 추가

설치 버전 확인

docker version 및 docker compose version 출력

Docker Engine:  28.1.1
Docker Compose: v2.35.1

---

2. GitLab 서버 구성 🦊

데이터 디렉터리 준비

컨테이너가 삭제되어도 데이터가 남도록 볼륨 마운트를 위한 디렉터리를 미리 만들어둡니다.

sudo mkdir -p /data/gitlab/{data,logs,config}

디렉터리 생성 및 권한 설정

docker-compose.yaml 작성

GitLab Enterprise Edition 16.1.0 이미지를 기반으로 서비스를 정의합니다.

services:
  gitlab:
    image: gitlab/gitlab-ee:16.1.0-ee.0
    container_name: gitlab
    restart: always
    ports:
      - "80:80"      # HTTP
      - "443:443"    # HTTPS
      - "8022:22"    # SSH (호스트 8022 → 컨테이너 22)
    volumes:
      - /data/gitlab/config:/etc/gitlab
      - /data/gitlab/logs:/var/log/gitlab
      - /data/gitlab/data:/var/opt/gitlab

docker-compose.yaml 작성 화면

포트를 3개로 분리한 이유:

• 80/443: 웹 브라우저에서 GitLab UI 접속
• 8022: SSH로 git clone/push 시 사용 (호스트의 22번은 이미 시스템 SSH가 사용 중)

GitLab 컨테이너 실행 및 초기 비밀번호 확인

docker compose up -d

컨테이너가 healthy 상태가 될 때까지 기다린 후 초기 root 비밀번호를 확인합니다. GitLab은 처음 실행 시 자동으로 임시 비밀번호를 생성해 파일로 저장합니다.

docker exec gitlab cat /etc/gitlab/initial_root_password

컨테이너 실행 및 healthy 상태 확인

---

3. GitLab Runner 설치 및 등록 🏃

Runner란?

GitLab 서버는 “이런 작업을 해야 해”라고 지시만 합니다. 실제로 코드를 받아서 빌드하고 테스트하는 실행자가 바로 GitLab Runner입니다. Runner를 별도 컨테이너로 띄워 GitLab 서버와 연결합니다.

Runner 디렉터리 및 docker-compose.yml 작성

sudo mkdir -p /data/gitlab-runner/config

Runner 컨테이너는 Docker-in-Docker(DinD) 방식으로 동작합니다. 호스트의 Docker 소켓(/var/run/docker.sock)을 공유해 Runner가 컨테이너 안에서도 Docker를 실행할 수 있도록 합니다.

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:v16.0.2
    container_name: gitlab-runner
    restart: always
    volumes:
      - /data/gitlab-runner/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock  # DinD 핵심

Runner 등록

GitLab 웹 UI에서 Admin Area → CI/CD → Runners 메뉴로 이동해 새로운 Instance Runner를 생성합니다.

• Tags: docker-test
• “Run untagged jobs” 체크 → 태그 없는 작업도 실행 허용

생성된 Registration Token을 복사해 Runner 등록 명령어를 실행합니다.

docker exec -it gitlab-runner gitlab-runner register \
  --url http://localhost \
  --executor docker \
  --docker-image alpine:latest

• --executor docker: 각 파이프라인 작업을 별도 컨테이너에서 실행
• --docker-image alpine:latest: 기본 빌드 이미지로 경량 Alpine Linux 사용

---

4. CI/CD 파이프라인 설정 🔁

프로젝트 Clone

VS Code를 WSL 모드로 실행하고, GitLab에서 만든 프로젝트를 로컬로 Clone합니다.

.gitlab-ci.yml 작성

프로젝트 루트에 .gitlab-ci.yml 파일을 생성합니다. 이 파일이 CI/CD 파이프라인의 설계도입니다. push할 때마다 GitLab이 이 파일을 읽어 Runner에게 작업을 지시합니다.

stages:
  - test

run-test:
  stage: test
  image: alpine:latest
  script:
    - echo "Hello from CI/CD Pipeline!"
    - echo "Build started at $(date)"
    - echo "All tests passed!"

Commit & Push

git add .gitlab-ci.yml
git commit -m "Add CI/CD pipeline"
git push origin main

---

5. 실행 결과 및 트러블슈팅 🔧

YAML 문법 오류 수정

초기 파이프라인이 실패했습니다. script 항목을 단일 문자열로 작성했더니 YAML 파서가 오류를 발생시켰습니다. 배열 형식으로 수정해 해결했습니다.

# ❌ 오류: 단일 문자열
script: echo "Hello"

# ✅ 수정: 배열 형식
script:
  - echo "Hello"

---

🏁 결론 및 배운 점

이번 과제를 통해 DevOps 환경의 전체 그림을 직접 구축해봤습니다.

단계	결과
Docker + Compose 설치	✅ 완료
GitLab 서버 구동	✅ 완료
GitLab Runner 등록	✅ Online 상태 확인
.gitlab-ci.yml 작성 및 Push	✅ 완료
파이프라인 실행 성공	✅ 완료

YAML 문법의 중요성: 들여쓰기 하나, 따옴표 하나가 전체 파이프라인을 멈춥니다. 선언형 설정 파일에서 문법의 정확성이 얼마나 중요한지 직접 느꼈습니다.

컨테이너 기반 인프라의 장점: GitLab 서버, Runner, 빌드 환경 모두를 컨테이너로 관리하니 설치/삭제/버전 변경이 매우 간편했습니다. docker compose up -d 한 줄로 복잡한 서버가 뜨는 경험은 꽤 인상적이었습니다.

DinD(Docker-in-Docker)의 개념: Runner가 컨테이너 안에서 또 다른 컨테이너를 생성해 빌드를 실행하는 구조를 이해했습니다. 호스트 Docker 소켓을 공유하는 방식이 보안과 성능 측면에서 어떤 트레이드오프를 갖는지도 추가로 공부하게 됐습니다.