오늘의 이야기

설치 예시

라즈베리 파이에 Docker 설치 및 서비스 구동 가이드

라즈베리 파이(Raspberry Pi)를 홈 서버로 활용할 때 가장 유용한 도구 중 하나가 바로 Docker입니다. 복잡한 환경 설정 없이 컨테이너 형태로 다양한 서비스를 쉽게 띄울 수 있기 때문입니다.

이번 글에서는 라즈베리 파이에 Docker를 설치하는 전체 과정부터, 특정 서비스를 백그라운드에서 구동하는 방법, 그리고 흔히 마주치는 컨테이너 이름 충돌(Conflict) 오류를 해결하는 방법까지 정리해 보았습니다.

1. 라즈베리 파이에 Docker 설치하기

라즈베리 파이 OS에서 가장 쉽고 확실하게 Docker를 설치하는 방법은 공식 자동 설치 스크립트를 사용하는 것입니다.

① 시스템 업데이트

설치를 시작하기 전, 시스템 패키지들을 최신 상태로 업데이트합니다.

sudo apt-get update
sudo apt-get upgrade -y

② Docker 설치 스크립트 실행

아래 명령어를 통해 공식 스크립트를 다운로드하고 실행합니다. 라즈베리 파이의 아키텍처(ARM)에 맞는 버전을 알아서 찾아 설치해 줍니다.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

③ 사용자 권한 설정 (핵심!)

기본적으로 Docker 명령어는 root 권한이 필요하여 매번 sudo를 입력해야 합니다. 이를 방지하기 위해 현재 사용자를 docker 그룹에 추가합니다.

sudo usermod -aG docker $USER

💡 참고: 권한을 적용하려면 라즈베리 파이를 재부팅하거나 newgrp docker 명령어를 입력하세요. SSH 접속이라면 연결을 끊었다가 다시 접속하면 됩니다.

④ 설치 확인

정상적으로 설치되었는지 버전과 테스트 컨테이너로 확인합니다.

docker --version
docker run hello-world

2. 백그라운드에서 Docker 컨테이너 실행하기

Docker 설치가 완료되었다면 원하는 서비스를 컨테이너로 실행할 수 있습니다. 이번 예시에서는 diegosouzapw/omniroute:latest 이미지를 기반으로 서비스를 구동해보겠습니다.

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

• -d: 백그라운드에서 실행(Detached mode)하여 터미널을 꺼도 서비스가 유지되게 합니다.


• --name omniroute: 구별하기 쉽도록 컨테이너의 이름을 'omniroute'로 지정합니다.


• -p 20128:20128: 접속을 위해 라즈베리 파이의 20128 포트를 컨테이너의 20128 포트와 연결합니다.

명령어 실행 후 긴 영문/숫자 조합(컨테이너 ID)이 출력되면 성공입니다. docker ps 명령어를 입력해 STATUS가 Up인지 확인하고, 동일한 네트워크(Wi-Fi 등)에 있는 PC나 스마트폰 브라우저에서 http://[라즈베리파이_IP주소]:20128로 접속하면 웹 대시보드 화면을 볼 수 있습니다.

3. 흔한 오류 해결: "The container name is already in use"

컨테이너를 실행하다 보면 아래와 같은 오류 메시지를 만날 때가 있습니다.

docker: Error response from daemon: Conflict. The container name "/omniroute" is already in use by container "...". You have to remove (or rename) that container to be able to reuse that name.

이것은 지정한 이름(이 경우 'omniroute')을 가진 컨테이너가 이미 만들어져 존재하기 때문에 발생하는 이름 충돌(Conflict) 오류입니다. 컨테이너가 종료된 상태로 남아있거나 이전에 동일한 명령어를 이미 실행했을 경우 발생합니다. 상황에 따라 아래의 두 가지 방법으로 해결할 수 있습니다.

방법 A: 기존 컨테이너를 완전히 삭제하고 새로 실행 (추천)

가장 깔끔하게 처음부터 설정을 적용하여 다시 띄우고 싶을 때 사용하는 방법입니다.

# 1. 기존 컨테이너 강제 삭제
docker rm -f omniroute

# 2. 기존 명령어 다시 실행
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

방법 B: 기존에 생성된 컨테이너를 다시 시작하기

새로 컨테이너를 지우고 만들 필요 없이, 단순히 멈춰 있는 기존 컨테이너를 켜기만 할 때 사용합니다.

docker start omniroute

위 방법 중 하나를 적용한 후 다시 터미널에 docker ps를 쳐서 목록에 컨테이너가 잘 나타난다면 완벽하게 해결된 것입니다!