[리눅스 한 학기 살기 #5] 라즈베리파이 5(ARM64)에 Docker Engine 설치하기
TL;DR (세 줄 요약)
- 라즈베리파이 5의 CPU는 ARM64(aarch64) 방식입니다. x86 컴퓨터용 설치 안내나 패키지를 그대로 쓰면 설치가 실패하거나 동작하지 않습니다.
- Docker 공식 저장소를 추가할 때 GPG 키를
/etc/apt/keyrings에 따로 저장하고,signed-by로 그 키만 믿도록 지정하며,arch값으로 arm64용 패키지만 받도록 정합니다.- 설치한 뒤에는
sudo docker run hello-world를 실행해서 데몬 실행, 이미지 내려받기, 컨테이너 실행이 모두 되는지 한 번에 확인합니다.
이 글은 "리눅스 한 학기 살기" 과제의 5주 차 기록입니다. 라즈베리파이 5에 설치한 Ubuntu 24.04에 Docker Engine을 설치하는 과정을 순서대로 설명합니다.
Docker는 프로그램과 그 프로그램이 실행되는 데 필요한 파일을 하나로 묶어서, 다른 프로그램과 분리된 공간에서 실행해 주는 도구입니다. 이 분리된 실행 공간을 컨테이너라고 부르고, 컨테이너를 만드는 데 쓰는 묶음 파일을 이미지라고 부릅니다.
1. 설치 전에 무엇을 확인하나요?

lsb_release -a # Ubuntu 24.04, codename noble 확인
uname -m # aarch64 또는 arm64
dpkg --print-architecture # arm64
lsb_release -a: Ubuntu 버전과 코드네임을 보여 줍니다. Ubuntu 24.04의 코드네임은 noble입니다.uname -m: CPU 아키텍처를 보여 줍니다. aarch64 또는 arm64가 나와야 합니다. 아키텍처는 CPU가 명령을 이해하는 방식이고, 일반 PC는 대부분 x86 방식입니다.dpkg --print-architecture: 패키지 관리자가 인식하는 아키텍처를 보여 줍니다. arm64가 나와야 합니다.
이 세 값이 맞지 않으면 이후 단계가 모두 어긋납니다.
Ubuntu가 제공하는 docker.io 패키지도 있습니다. 하지만 버전이 오래되어 최신 기능과 보안 패치가 늦게 들어옵니다. 그래서 이 글에서는 Docker가 직접 운영하는 저장소를 씁니다. 저장소는 패키지를 내려받는 서버입니다.
2. 기존에 설치된 패키지는 어떻게 정리하나요?
sudo apt update
sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc
sudo apt autoremove
공식 저장소의 Docker와 충돌할 수 있는 패키지를 먼저 지웁니다. apt remove는 설정과 데이터(/var/lib/docker)를 남깁니다. 완전히 새로 시작하려면 이 디렉터리를 직접 지워야 합니다. 이 디렉터리를 지우면 기존 이미지와 볼륨이 모두 사라지므로, 필요한 것이 없는지 먼저 확인합니다. 볼륨은 컨테이너의 데이터를 보관하는 저장 공간입니다.
3. GPG 키와 저장소는 어떻게 추가하나요?
GPG 키는 패키지가 정말 Docker에서 만든 것인지 서명으로 확인하는 데 쓰는 키입니다.
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
명령어와 옵션의 뜻은 다음과 같습니다.
ca-certificates: HTTPS로 저장소에 접속할 때 서버 인증서를 검증하는 데 필요합니다.curl: GPG 키 파일을 내려받습니다.gnupg: 내려받은 키를 apt가 읽는 형식으로 바꿉니다(--dearmor).signed-by: 이 저장소의 패키지는 지정한 키의 서명이 있어야 설치됩니다. 다른 저장소의 키와 섞이지 않습니다.arch=$(dpkg --print-architecture): 이 컴퓨터의 아키텍처인 arm64용 패키지만 받도록 정합니다.$(. /etc/os-release && echo $VERSION_CODENAME): 코드네임 noble을 자동으로 채웁니다.
마지막의 sudo apt update는 새로 추가한 저장소의 패키지 목록을 받아옵니다.
4. Docker는 어떻게 설치하고 확인하나요?
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl status docker
sudo docker run hello-world
| 패키지 | 역할 |
docker-ce | 컨테이너, 이미지, 네트워크, 볼륨을 관리하는 데몬(dockerd)입니다. 데몬은 화면 없이 뒤에서 계속 실행되는 프로그램입니다. |
docker-ce-cli | 터미널에서 입력하는 docker 명령어입니다. |
containerd.io | 컨테이너를 실제로 실행하는 런타임입니다. |
docker-buildx-plugin | 여러 아키텍처용 이미지를 빌드하는 기능입니다. |
docker-compose-plugin | docker compose 명령어입니다. |
sudo systemctl status docker로 데몬이 실행 중인지 확인하고, sudo docker run hello-world를 실행합니다. hello-world가 실행되면 다음 세 가지가 모두 정상이라는 뜻입니다.
docker명령어가 데몬과 통신합니다.- Docker Hub에서 arm64용 이미지를 내려받습니다. Docker Hub는 이미지를 올리고 내려받는 공개 저장소입니다.
- 내려받은 이미지로 컨테이너를 실행합니다.
5. sudo 없이 docker 명령어를 쓰려면 어떻게 하나요?
sudo groupadd docker # 이미 있으면 그대로 둔다
sudo usermod -aG docker $USER
newgrp docker # 또는 로그아웃 후 다시 로그인
docker run hello-world
groupadd docker: docker 그룹을 만듭니다. 이미 있으면 그대로 둡니다.usermod -aG docker $USER: 현재 사용자를 docker 그룹에 추가합니다.newgrp docker: 바뀐 그룹을 지금 셸에 적용합니다. 로그아웃한 뒤 다시 로그인해도 됩니다.
이 방법에는 위험이 있습니다. docker 그룹에 들어가면 /var/run/docker.sock이라는 소켓 파일에 접근할 수 있습니다. 이 소켓에 접근할 수 있는 사용자는 호스트(컨테이너를 실행하는 컴퓨터)의 파일 시스템을 연결한 컨테이너를 실행할 수 있습니다. 결과적으로 관리자(root)에 가까운 권한을 갖게 됩니다. 혼자 쓰는 기기에서는 편의를 위해 많이 쓰지만, 여러 사람이 쓰는 서버라면 rootless 모드를 검토합니다. rootless 모드는 Docker 데몬을 관리자 권한 없이 실행하는 방식입니다.
# rootless 모드 (참고)
dockerd-rootless-setuptool.sh install
자주 묻는 질문 (FAQ)
Q1. sudo apt install docker.io와 무엇이 다른가요?
docker.io는 Ubuntu가 빌드해서 배포하는 패키지이고 버전이 늦습니다. 공식 저장소의 docker-ce는 Docker 팀이 최신 안정 버전과 보안 패치를 직접 배포합니다. compose 플러그인과 buildx도 함께 받을 수 있습니다.
Q2. newgrp 후에도 permission denied가 납니다.
usermod는 /etc/group 파일만 바꾸고, 이미 실행 중인 셸에는 적용되지 않습니다. 로그아웃한 뒤 다시 로그인하거나, SSH 접속을 끊고 새로 접속해야 합니다. id 명령어로 docker 그룹이 실제로 붙었는지 확인합니다.
Q3. ARM64에서 이미지가 없다고 나옵니다.
그 이미지에 arm64용 빌드가 없을 수 있습니다. docker manifest inspect 이미지명으로 지원하는 아키텍처를 확인합니다. 없으면 arm64를 지원하는 다른 이미지를 쓰거나 직접 빌드해야 합니다.
참고 자료
같은 주제의 다른 글: [리눅스 한 학기 살기 #3] Ubuntu 24.04 원격 데스크톱: grdctl로 RDP 접속, [리눅스 한 학기 살기 #4] 라즈베리파이 VPN: Tailscale과 WireGuard 비교, [리눅스 한 학기 살기 #6] Docker로 Jenkins 실행하기: CI/CD 개념과 초기 설정, [리눅스 한 학기 살기 #7] Vim 입문: 모드, 저장과 종료, 이동, 매크로, [리눅스 한 학기 살기 #8] ca-certificates란? 사내 CA 인증서 추가 방법