2025년 12월 말, Mini PC의 활용에 대해 여러 사람들에게 들었다. 개발 작업에 Windows를 활용하고 있었지만, 오랫만에 Linux 시스템도 하나 설치하고 싶었다. 집에 Ubuntu 설치를 했고, 가장 처음 한 것은 서비스들을 돌려보고 싶어 가장 기본이 되는 Docker를 설치했다. 이 때, 여러 어려움이 있어, 경험을 정리해 본다. 어려움이라고 했지만, 돌아 보니 퀴즈 혹은 퍼즐을 풀어 보는 느낌이었다.

0. 기존 시도

일반적으로 인터넷 검색, LLM 문의를 통해서 접근하는 방법은 다음과 같다.

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

404 에러가 발생되고, docker의 심장이라고 할 수 있는 기능인 container 설치가 안된다. 반나절 정도 여러 시도 끝에 성공했다.

1. 현상: containerd.io 설치 불가 (404 Not Found)

Docker 공식 가이드를 따라 apt install을 시도했으나, 저장소 메타데이터에 등록된 containerd.io 최신 버전(2.x.x)이 실제 서버에 존재하지 않아 설치가 중단되는 현상이 발생했다.

• 원인: Ubuntu 24.04(Noble) 저장소의 일시적인 인덱스 동기화 오류.
• 해결: apt를 거치지 않고, 안정성이 검증된 .deb 패키지 파일을 직접 다운로드하여 수동 설치(dpkg)를 진행했다.

# 안정 버전 수동 다운로드 및 설치
wget https://download.docker.com/linux/ubuntu/dists/noble/pool/stable/amd64/containerd.io_1.7.25-1_amd64.deb
sudo dpkg -i containerd.io_1.7.25-1_amd64.deb

2. 의존성 해결 및 버전 고정 (apt-mark hold)

수동 설치한 containerd.io와 나머지 Docker 패키지 간의 버전 충돌(Dependency Hell)이 발생했다. apt가 자꾸 존재하지 않는 상위 버전으로 업데이트를 시도하며 설치를 거부하는 상황을 해결했다.

• 해결: 설치 가능한 docker-ce 버전을 확인하고, 다운로드를 허용하여 버전을 강제 일치시킨 뒤 업데이트를 잠갔습니다.

# 1. 버전 강제 지정 및 다운로드 허용 설치
sudo apt install -y --allow-downgrades \
  docker-ce=5:27.5.1-1~ubuntu.24.04~noble \
  docker-ce-cli=5:27.5.1-1~ubuntu.24.04~noble

# 2. 향후 자동 업데이트로 인한 꼬임 방지 (버전 고정)
sudo apt-mark hold docker-ce docker-ce-cli containerd.io

3. containerd 서비스 유닛 수동 등록

수동으로 설치한 패키지는 시스템 서비스(systemd)에 자동으로 등록되지 않는 경우가 있다. 이로 인해 Unit containerd.service not found 에러가 발생하며 Docker 엔진의 심장이 뛰지 않는 상태가 되었다.

• 해결: /lib/systemd/system/containerd.service 파일을 직접 생성하여 런타임 환경을 수동으로 구성했습니다.

# 서비스 파일 수동 생성 후 로드
sudo nano /lib/systemd/system/containerd.service  # 서비스 정의 내용 입력
sudo systemctl daemon-reload
sudo systemctl enable --now containerd

containerd.service의 내용은 다음과 같이 입력했다.

[Unit]
Description=containerd container runtime
Documentation=https://containerd.io
After=network.target local-fs.target

[Service]
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/usr/bin/containerd
Type=notify
Delegate=yes
KillMode=process
Restart=always
RestartSec=5
LimitNPROC=infinity
LimitCORE=infinity
LimitNOFILE=1048576
TasksMax=infinity
OOMScoreAdjust=-999

[Install]
WantedBy=multi-user.target

4. 최종 Docker 실행 및 검증

심장(containerd)이 뛰기 시작하자 몸체(docker-ce)도 정상적으로 작동하기 시작했다.

• 결과: 서비스 가동 및 권한 설정을 마치고, 드디어 Supabase를 올릴 준비가 끝났다.

# Docker 서비스 시작 및 확인
sudo systemctl start docker
sudo systemctl status docker  # Active: active (running) 확인!

# 작동 확인
docker ps

마무리 하며

예전에는 Googling, Stack overflow에서 이슈를 해결했다. LLM이 검색을 지원하기 시작하면서 여러 경로 해결 방안을 찾아 해설해 준다. 특히, Ubuntu의 기본적인 package 설정을 따라서 하게 되면, 서비스의 설정도 알아서 해준다. debian package를 직접 받아, 서비스의 환경 설정을 하고, 그 후에 dependency가 있는 기능들의 version을 매칭해서 동작을 확인하였다.

이런 예외 상황은 힘들지만, 해결할 수 있다는 것은 내가 시스템에 대해서 좀 더 이해하게 된다는 측면에서 흥미로운 퍼즐을 푸는 듯한 재미를 준다.