Docker Compose Ubuntu 설치 스크립트

Docker Compose Ubuntu 설치 스크립트

실습은 Docker Compose v2.1.1 바이너리를 /usr/local/bin/docker-compose에 직접 내려받는 방식이었다. 이 방식은 당시에는 단순했지만, 현재 Ubuntu 서버에서는 Docker 공식 apt 저장소에서 docker-compose-plugin을 설치하고 docker compose 명령으로 사용하는 구성이 운영에 더 적합하다.

핵심 차이는 명령 이름이다. 예전 standalone Compose는 docker-compose up -d처럼 하이픈이 들어간 단일 바이너리를 사용했고, Compose V2 plugin은 Docker CLI의 하위 명령으로 동작해서 docker compose up -d를 사용한다. 새 서버라면 plugin 방식을 기본값으로 두는 것이 업데이트, 패키지 관리, Docker Engine과의 호환성 면에서 좋다.

적용 대상

• Ubuntu 20.04, 22.04, 24.04 계열 서버
• Docker Engine은 이미 설치되어 있고 Compose plugin만 추가하려는 서버
• Docker Engine과 Compose plugin을 함께 설치해야 하는 신규 서버

설치 전 확인

먼저 OS 코드네임, 아키텍처, Docker 설치 여부를 확인한다. apt 저장소는 Ubuntu 코드네임을 기준으로 잡히므로 VERSION_CODENAME 값이 비어 있으면 그대로 진행하지 않는다.

. /etc/os-release
echo "ID=${ID}"
echo "VERSION_CODENAME=${VERSION_CODENAME}"
dpkg --print-architecture

docker --version || true
docker compose version || true

Compose plugin만 설치하는 스크립트

Docker Engine이 이미 설치되어 있는 서버라면 Compose plugin 패키지만 설치해도 된다. 아래 스크립트는 Docker 공식 Ubuntu 저장소를 등록한 뒤 docker-compose-plugin만 설치한다.

#!/usr/bin/env bash
set -euo pipefail

if [ "$(id -u)" -ne 0 ]; then
 echo "root 권한으로 실행하세요: sudo $0" >&2
 exit 1
fi
. /etc/os-release
if [ "${ID:-}" != "ubuntu" ] || [ -z "${VERSION_CODENAME:-}" ]; then
 echo "지원 대상은 Ubuntu이며 VERSION_CODENAME 값이 필요합니다." >&2
 exit 1
fi

apt-get update
apt-get install -y ca-certificates curl gnupg

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

cat >/etc/apt/sources.list.d/docker.list <<EOF
deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable
EOF

apt-get update
apt-get install -y docker-compose-plugin

docker compose version

Docker Engine까지 같이 설치하는 스크립트

신규 서버라면 Engine, CLI, containerd, Buildx, Compose plugin을 한 번에 맞추는 편이 낫다. 아래 스크립트는 Docker 공식 저장소 기준으로 현재 배포판에 맞는 패키지를 설치한다.

#!/usr/bin/env bash
set -euo pipefail

if [ "$(id -u)" -ne 0 ]; then
 echo "root 권한으로 실행하세요: sudo $0" >&2
 exit 1
fi
. /etc/os-release
if [ "${ID:-}" != "ubuntu" ] || [ -z "${VERSION_CODENAME:-}" ]; then
 echo "지원 대상은 Ubuntu이며 VERSION_CODENAME 값이 필요합니다." >&2
 exit 1
fi

apt-get update
apt-get install -y ca-certificates curl gnupg

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

cat >/etc/apt/sources.list.d/docker.list <<EOF
deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable
EOF

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

systemctl enable --now docker
docker --version
docker compose version

일반 사용자 권한 설정

매번 sudo docker...를 입력하기 싫다면 사용자를 docker 그룹에 넣을 수 있다. 단, docker 그룹은 사실상 root 수준의 권한을 갖는다. 개인 랩 서버에서는 편하지만, 공용 서버에서는 운영 정책을 먼저 정해야 한다.

sudo usermod -aG docker "$USER"
newgrp docker

docker ps
docker compose version

동작 검증

간단한 Compose 파일을 만들어 plugin이 정상 동작하는지 확인한다. 여기서는 외부 포트를 열지 않고 hello-world 컨테이너만 실행한다.

mkdir -p ~/compose-smoke-test
cd ~/compose-smoke-test

cat >compose.yaml <<'EOF'
services:
 hello:
 image: hello-world:latest
EOF

docker compose pull
docker compose up
docker compose down

기존 docker-compose 명령과 호환시키기

문서나 스크립트가 docker-compose 명령을 호출한다면 우선 스크립트를 docker compose로 바꾸는 것이 정석이다. 당장 수정이 어렵다면 wrapper를 둘 수 있지만, 장기적으로는 Compose V2 문법에 맞춰 정리하는 편이 낫다.

sudo tee /usr/local/bin/docker-compose >/dev/null <<'EOF'
#!/usr/bin/env sh
exec docker compose "$@"
EOF

sudo chmod +x /usr/local/bin/docker-compose
docker-compose version

standalone 바이너리를 꼭 써야 하는 경우

폐쇄망이나 패키지 저장소를 쓸 수 없는 환경에서는 standalone 바이너리를 사용할 수 있다. 다만 이 방식은 apt로 자동 업데이트되지 않으므로 버전 고정, 체크섬 검증, 교체 절차를 별도로 관리해야 한다.

COMPOSE_VERSION="v2.27.0"
DOCKER_CONFIG="${DOCKER_CONFIG:-$HOME/.docker}"
mkdir -p "${DOCKER_CONFIG}/cli-plugins"

curl -fL \
 "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-$(uname -m)" \
 -o "${DOCKER_CONFIG}/cli-plugins/docker-compose"

chmod +x "${DOCKER_CONFIG}/cli-plugins/docker-compose"
docker compose version

자주 나는 오류

• docker: 'compose' is not a docker command: docker-compose-plugin이 설치되지 않았거나 Docker CLI가 너무 오래된 상태다.
• permission denied while trying to connect to the Docker daemon socket: 현재 사용자가 Docker socket 권한이 없거나 sudo 없이 실행한 상태다.
• Cannot connect to the Docker daemon: Docker 서비스가 내려가 있거나 container runtime 문제가 있다.
• Unsupported config option: Compose 파일 문법이 오래된 Compose V1 기준이거나 들여쓰기가 잘못되었을 가능성이 있다.

sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 100 --no-pager
docker compose config

정리

Ubuntu에서 Docker Compose를 설치할 때는 더 이상 오래된 docker-compose 단일 바이너리를 기본값으로 둘 필요가 없다. Docker 공식 저장소를 등록하고 docker-compose-plugin을 설치한 뒤 docker compose로 검증하는 흐름이 현재 기준의 표준 절차다. 기존 자동화가 하이픈 명령을 강하게 의존한다면 wrapper로 임시 호환시키되, 실제 Compose 파일과 운영 스크립트는 V2 기준으로 바꾸는 것이 좋다.

문서 링크

• Docker Docs: Install Docker Compose on Linux
• Docker Docs: Install Docker Compose