OrbStack으로 macOS에서 Docker와 Linux 사용하기

macOS에서 개발하다 보면 웹 서버 하나를 확인하려고 Docker Desktop을 켜는 일이 자주 생기는데요. 컨테이너 몇 개만 실행하면 되는데 관리 화면이나 설정이 복잡하게 느껴질 때도 있습니다. 터미널에서는 익숙한 Docker 명령어를 쓰고, 실행 중인 서비스를 앱에서 바로 확인할 수 있다면 편하겠죠?

OrbStack은 이런 작업에 사용할 수 있는 macOS용 도구입니다. 이번 글에서는 OrbStack을 설치하고 컨테이너를 실행한 뒤, 개발용 도메인과 Linux 머신까지 사용해 보겠습니다. Docker Desktop에서 옮겨 올 때 헷갈리기 쉬운 연결 설정과 데이터 이전도 함께 살펴볼게요.

OrbStack이란?

OrbStack은 macOS에서 Docker 컨테이너(container)와 Linux 환경을 실행하고 관리하는 앱입니다. Docker 명령어를 처리하는 Docker 엔진(engine)을 포함하고 있어서 기존 프로젝트의 실행 방식을 대부분 그대로 유지할 수 있습니다.

macOS는 Linux 커널(kernel)을 사용하는 운영체제가 아닙니다. 따라서 Linux용 컨테이너를 실행하려면 중간에 Linux 환경이 필요한데요. OrbStack은 내부적으로 가벼운 가상 머신(virtual machine)을 실행하고, 그 안에서 Docker 엔진을 구동합니다. 터미널에서 입력한 Docker 명령어는 이 엔진에 전달됩니다.

이 구조를 알면 OrbStack이 무엇을 바꿔 주는지도 분명해집니다. 프로젝트의 Dockerfile이나 Compose 파일을 유지하면서 Mac에서 컨테이너를 실행해 주는 환경을 바꾸는 것입니다. 그래픽 사용자 인터페이스(graphical user interface, 이하 GUI)에서는 컨테이너와 볼륨을 관리하고, 자동으로 만들어지는 도메인으로 웹 서비스에 접근할 수 있습니다.

OrbStack은 자원 사용량과 macOS 통합에 초점을 맞추고 있습니다. 다만 프로젝트마다 파일을 읽는 양과 실행하는 서비스가 다르므로, 어느 환경에서나 빌드가 몇 배 빨라진다고 단정하기는 어렵습니다. 실제 전환을 검토한다면 평소 사용하는 프로젝트로 시작 시간, 파일 변경 반영 속도, 메모리 사용량을 비교해 보는 편이 좋습니다.

설치하고 Docker 연결 확인하기

Homebrew를 사용한다면 다음 명령어로 설치할 수 있습니다.

brew install --cask orbstack
open -a OrbStack

앱을 처음 열면 안내에 따라 초기 설정을 마칩니다. Homebrew를 사용하지 않는다면 공식 다운로드 페이지에서 앱을 받을 수도 있습니다.

OrbStack에는 Docker 명령줄 인터페이스(command-line interface, 이하 CLI)와 Compose 도구가 포함되어 있습니다. 작동하는 도구가 이미 설치되어 있으면 이를 사용할 수 있으므로, 먼저 터미널에서 연결 상태부터 확인해 보겠습니다.

docker context ls
docker context use orbstack
docker version
docker compose version

Docker 컨텍스트(context)는 Docker CLI가 어느 엔진에 연결할지 정해 놓은 설정입니다. OrbStack은 orbstack이라는 컨텍스트를 생성합니다. 목록에 이 이름이 있는지 확인한 뒤 선택하면 이후 명령어가 OrbStack의 엔진으로 전달됩니다. docker version 결과에 클라이언트뿐 아니라 서버 정보까지 표시되는지 확인하세요. CLI 설치와 엔진 연결은 별개라서 클라이언트 버전만 확인해서는 컨테이너를 실행할 준비가 끝났다고 볼 수 없습니다.

기본 예제로 컨테이너 실행까지 확인해 볼까요?

docker run --rm hello-world

이미지를 내려받고 컨테이너가 정상 종료되면 기본 연결이 된 것입니다. --rm은 실행이 끝난 컨테이너를 자동으로 삭제하는 옵션입니다. 이후 예제에서도 잠깐 실행하고 버리는 컨테이너에는 이 옵션을 사용하겠습니다.

웹 서버 실행하기

이번에는 브라우저에서 접속할 수 있는 Nginx 웹 서버를 실행해 보겠습니다. docker run 사용법에서 다룬 옵션을 그대로 사용할 수 있습니다.

docker run -d --name orb-web -p 127.0.0.1:8080:80 nginx:alpine

-d는 컨테이너를 백그라운드(background)에서 실행하고, --name은 나중에 찾기 쉬운 이름을 붙입니다. -p는 호스트(host)인 Mac의 포트(port)와 컨테이너의 포트를 연결합니다. 여기서는 Mac의 루프백(loopback) 주소인 127.0.0.1의 8080번 포트로 들어온 요청을 컨테이너의 80번 포트로 보냅니다.

브라우저에서 http://localhost:8080을 열어 보세요. Nginx 기본 페이지가 표시되면 웹 서버까지 정상적으로 실행된 것입니다. 터미널에서는 컨테이너 상태와 요청 기록을 다음과 같이 확인할 수 있습니다.

docker ps
docker logs orb-web

OrbStack 앱에서도 같은 컨테이너를 확인할 수 있습니다. 터미널에서 실행한 컨테이너와 앱에서 관리하는 컨테이너가 별개로 존재하는 것은 아닙니다. CLI와 GUI가 같은 엔진의 상태를 보여 주는 것이죠.

포트 번호 대신 도메인 사용하기

여러 프로젝트를 동시에 실행하다 보면 8080번 포트는 어느 프로젝트에 썼는지 헷갈릴 수 있습니다. OrbStack은 컨테이너 이름을 바탕으로 개발용 도메인(domain)을 만들어 줍니다. 앞에서 만든 컨테이너는 http://orb-web.orb.local로 접근할 수 있습니다.

이 주소는 방금 지정한 Mac의 8080번 포트를 이용하는 방식과 다릅니다. OrbStack이 컨테이너의 웹 서버를 찾아 연결해 주므로, 도메인만 사용할 때는 호스트 포트를 따로 공개하지 않아도 됩니다. 앞의 컨테이너를 지우고 -p 없이 다시 만들어 보겠습니다.

docker rm -f orb-web
docker run -d --name orb-web nginx:alpine

이제 http://localhost:8080 연결은 사라지지만 http://orb-web.orb.local에서는 같은 웹 서버에 접근할 수 있습니다. 여러 웹 컨테이너가 각자 내부 80번 포트를 사용하더라도, 이름이 다르면 서로 다른 도메인으로 열 수 있는 것입니다. 실행 중인 컨테이너의 주소를 한꺼번에 보고 싶다면 http://orb.local을 열어 보세요.

도메인 기능은 OrbStack의 네트워크(network) 설정에서 컨테이너 도메인과 IP 접근이 허용되어 있어야 작동합니다. 연결되지 않는다면 앱의 Settings → Network에서 해당 설정을 확인하세요. 컨테이너 안에서 웹 서버가 실제로 실행 중인지도 함께 확인해야 합니다. 정확한 이름 규칙과 설정은 컨테이너 도메인 문서에 정리되어 있습니다.

HTTPS도 사용할 수 있습니다. 처음에는 https://orb.local에 접속해 인증서 설치 안내를 따른 뒤, https://orb-web.orb.local을 열어 보세요. OrbStack이 로컬 인증서와 역방향 프록시(reverse proxy)를 설정하므로 예제의 Nginx에 HTTPS 설정을 따로 넣을 필요가 없습니다. 이 동작은 HTTPS 공식 문서에서 확인할 수 있습니다.

다만 이 주소는 로컬 개발용입니다. 팀원에게 URL을 전달한다고 내 Mac의 서버가 인터넷에 공개되는 것은 아닙니다.

Docker Compose로 프로젝트 실행하기

Docker Compose를 쓰는 프로젝트도 같은 방식으로 실행할 수 있습니다. 여기서는 정적 페이지를 제공하는 작은 예제를 만들어 보겠습니다. 먼저 새 작업 디렉터리(directory)를 만들고 이동합니다.

mkdir orbstack-demo
cd orbstack-demo
mkdir html

다음 두 파일을 작성하세요.

<!doctype html>
<html lang="ko">
  <meta charset="utf-8" />
  <title>OrbStack 예제</title>
  <h1>OrbStack에서 실행한 웹 서버입니다.</h1>
</html>

name: orbstack-demo

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8081:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro

name으로 프로젝트 이름을 명시하고, web이라는 서비스를 정의했습니다. volumes에서는 Mac의 html 디렉터리를 컨테이너의 웹 문서 디렉터리에 연결합니다. 이렇게 호스트의 경로를 연결하는 것을 바인드 마운트(bind mount)라고 부릅니다. :ro를 붙였으므로 컨테이너에서는 이 경로를 읽기 전용으로 사용합니다.

Compose 파일이 있는 디렉터리에서 실행합니다.

docker compose up -d
docker compose ps

브라우저에서 http://localhost:8081을 열면 작성한 페이지를 볼 수 있습니다. Mac에서 html/index.html의 문구를 고치고 새로고침해 보세요. 같은 파일이 컨테이너에 연결되어 있으므로 이미지를 다시 빌드하지 않아도 변경한 내용이 표시됩니다.

Compose 프로젝트에서는 서비스명.프로젝트명.orb.local 형식의 도메인이 만들어집니다. 따라서 이 예제는 http://web.orbstack-demo.orb.local로도 접근할 수 있습니다. 프로젝트 이름을 파일에 적어 두면 작업 디렉터리의 이름이 달라져도 주소를 예측하기 쉽습니다.

이 예제의 ports 설정은 일반적인 Docker 환경에서도 localhost로 접속할 수 있도록 넣었습니다. OrbStack 도메인만 사용한다면 생략할 수 있지만, 다른 환경을 쓰는 팀원과 파일을 공유할 때는 공통으로 사용할 접속 방법을 남겨 두면 좋겠죠. OrbStack 전용 도메인을 프로젝트의 유일한 접속 주소로 가정하지 않는 편이 협업하기 편합니다.

예제를 마치면 다음 명령어로 정리합니다.

docker compose down
docker rm -f orb-web

Compose로 만든 컨테이너와 앞에서 따로 실행한 컨테이너는 관리 단위가 다르므로 각각 정리했습니다. Mac에 작성한 HTML 파일은 그대로 남습니다.

파일 공유와 데이터 보관

앞의 HTML 예제는 Mac에서 편집한 파일을 컨테이너가 읽어야 하므로 바인드 마운트가 잘 맞습니다. 반면 컨테이너 안에서 생성한 데이터를 계속 보관하려면 이름 있는 볼륨(named volume)을 사용할 수 있습니다. 볼륨과 바인드 마운트의 차이를 구분해 두면 저장 위치를 결정하기 쉬워집니다.

예를 들어 다음 명령어는 볼륨을 만들고 그 안에 파일 하나를 저장합니다.

docker volume create orb-data
docker run --rm -v orb-data:/data alpine sh -c 'echo hello > /data/message.txt'
docker run --rm -v orb-data:/data alpine cat /data/message.txt

파일을 쓰는 컨테이너와 읽는 컨테이너는 서로 다릅니다. 첫 번째 컨테이너가 종료되어 삭제되어도 볼륨에 저장한 파일은 두 번째 컨테이너에서 읽을 수 있습니다. 컨테이너를 다시 만든다고 데이터까지 항상 사라지는 것은 아니죠.

OrbStack의 볼륨 데이터는 Linux 쪽에 저장됩니다. 공식 문서도 파일 접근 성능이 중요한 경우 볼륨 사용을 권장합니다. Mac에서 파일을 살펴보고 싶다면 Finder의 OrbStack 항목이나 ~/OrbStack/docker 경로로 접근할 수 있습니다. 컨테이너에 연결할 때는 Finder에 보이는 경로 대신 orb-data처럼 볼륨 이름을 사용하세요. 이 구분은 파일 공유 문서에서도 안내합니다.

실행 중인 데이터베이스(database)의 파일을 Finder에서 직접 수정하는 용도로 쓰지는 않는 것이 좋습니다. 내용 확인과 데이터 변경은 다른 작업이므로, 데이터베이스는 해당 도구가 제공하는 쿼리나 백업 기능으로 다루세요. 위에서 만든 연습용 볼륨은 다음과 같이 삭제할 수 있습니다.

docker volume rm orb-data

Docker Desktop에서 옮겨 오기

OrbStack으로 연결을 바꾼 뒤 기존 컨테이너가 보이지 않아 당황할 수 있습니다. Docker Desktop의 엔진과 OrbStack의 엔진은 각자 데이터를 관리하기 때문인데요. 컨텍스트 전환은 연결 대상을 바꾸는 작업이지, 이미지와 볼륨을 옮기는 작업은 아닙니다.

기존 데이터가 필요하다면 OrbStack 앱의 File → Migrate Docker Data 기능을 사용하거나 다음 명령어를 실행할 수 있습니다.

orb docker migrate

공식 설치 문서에 따르면 이전 기능은 Docker Desktop의 데이터를 복사합니다. 원본을 곧바로 지우기보다는 이전을 마친 뒤 애플리케이션이 시작되는지, 필요한 데이터가 있는지 확인하세요. 데이터베이스처럼 중요한 상태가 있다면 별도로 백업해 두는 것이 좋습니다.

반대로 이미지는 다시 내려받고 컨테이너도 Compose로 재생성할 수 있는 프로젝트라면, 모든 데이터를 복사할 필요는 없을 수 있습니다. 소스 코드는 Mac에 있는지, 따로 옮겨야 하는 볼륨 데이터는 무엇인지 먼저 구분해 보세요. Compose 파일은 서비스를 어떻게 실행할지 설명하지만, 기존 볼륨의 내용까지 담고 있지는 않습니다.

Docker Desktop으로 돌아가려면 해당 앱을 실행한 뒤 컨텍스트를 다시 선택합니다.

docker context use desktop-linux

이름이 다른 환경에서는 먼저 컨텍스트 목록을 확인하세요. 연결만 일시적으로 확인하고 싶다면 기본 선택을 바꾸는 대신 명령어에 대상을 지정할 수도 있습니다.

docker --context orbstack ps
docker --context desktop-linux ps

두 엔진을 함께 실행할 때는 같은 Mac 포트를 동시에 사용하지 않도록 해야 합니다. 평소에는 사용할 환경만 켜 두면 포트 충돌과 불필요한 자원 사용을 줄일 수 있습니다.

연결이 예상대로 바뀌지 않을 때

컨텍스트를 바꿨는데도 예전 엔진으로 연결된다면 환경 변수를 확인해 보세요. DOCKER_HOST나 DOCKER_CONTEXT가 이전 환경을 가리키고 있을 수 있습니다.

printenv DOCKER_HOST
printenv DOCKER_CONTEXT

Docker 컨텍스트 문서에서 설명하듯 환경 변수나 명령줄 옵션은 기본 컨텍스트 선택을 덮어쓸 수 있습니다. 기존 설정이 더 이상 필요 없다면 현재 셸에서 해제하고 다시 연결합니다.

unset DOCKER_HOST DOCKER_CONTEXT
docker context use orbstack
docker version

새 터미널을 열 때 같은 문제가 반복된다면 셸 초기화 파일에 해당 변수를 설정하는 줄이 남아 있는지도 살펴보세요. 연결 오류를 해결하려고 컨테이너나 볼륨부터 삭제할 필요는 없습니다. CLI가 어느 엔진을 보고 있는지부터 확인하는 것이 순서입니다.

Linux 머신 사용하기

OrbStack에서는 컨테이너 외에 Ubuntu 같은 Linux 환경을 만들어 쓸 수도 있습니다. Linux 명령어를 연습하거나 운영체제의 서비스 관리 방식을 확인하고 싶을 때 유용한데요. macOS 터미널에서 다음 명령어를 실행합니다.

orb create ubuntu dev-linux
orb list
orb -m dev-linux

dev-linux라는 머신을 만들고 그 안의 셸(shell)로 들어가는 예제입니다. 들어간 뒤에는 일반적인 Linux 환경처럼 명령어를 실행하면 됩니다.

cat /etc/os-release
uname -a
exit

exit으로 macOS 셸로 돌아올 수 있습니다. 머신 안에서 명령어 하나만 실행하고 싶다면 매번 셸에 들어가지 않고 다음처럼 호출하세요.

orb -m dev-linux uname -a

사용을 마친 머신은 멈춰 두고, 다시 필요해지면 시작할 수 있습니다. 아래 명령어는 macOS 터미널에서 실행합니다.

orb stop dev-linux
orb start dev-linux

머신 선택과 명령어 실행 구문은 Linux 머신 명령어 문서를 참고하세요.

한 가지 구분할 점은 OrbStack의 Linux 머신이 각각 독립적인 커널을 가진 가상 머신은 아니라는 것입니다. 아키텍처 문서에 따르면 머신들은 커널을 공유합니다. Ubuntu 같은 배포판(distribution)의 도구와 서비스를 쓰는 데는 편리하지만, 머신마다 서로 다른 커널을 부팅하는 실험과는 용도가 다릅니다. 기본 머신은 Mac과 파일도 공유하므로, Mac의 파일과 완전히 분리된 환경이라고 가정해서는 안 됩니다.

사용 범위와 선택 기준

2026년 9월 확인 기준으로 OrbStack은 개인의 비상업적 용도에는 무료이고, 업무와 상업적 용도에는 유료 구독이 필요합니다. 개인 Mac에서 실행하더라도 회사 업무에 쓰는 경우에는 개인용 무료 범위라고 단정할 수 없습니다. 도입 전에 공식 요금 안내에서 사용 조건을 확인하세요.

기존에 Colima를 사용하고 있다면 GUI와 자동 도메인이 실제 작업에 얼마나 도움이 되는지 비교해 보면 좋겠습니다. 터미널 위주로 이미 만족스럽게 사용하고 있다면 굳이 실행 환경을 바꿀 이유는 적을 수 있습니다. 반면 여러 프로젝트의 웹 서비스를 번갈아 열거나 컨테이너와 Linux 환경을 앱 하나에서 관리하고 싶다면 OrbStack의 기능을 활용하기 좋습니다.

전환 여부는 작은 프로젝트 하나로 판단해 보세요. 평소 사용하는 Compose 파일을 실행하고, 파일 변경이 반영되는지와 데이터 보관 방식이 맞는지 확인하면 설치 성공 여부보다 더 많은 것을 알 수 있습니다. 팀에서 사용하는 기능이 따로 있다면 그 작업까지 확인한 뒤 본격적으로 옮기면 됩니다.

마치며

OrbStack에서는 익숙한 Docker 명령어로 컨테이너를 실행하면서 자동 도메인과 Linux 머신 기능을 함께 사용할 수 있습니다. 웹 서버 하나를 띄워 보고 기존 Compose 프로젝트까지 실행해 보면 평소 개발 과정에 어떻게 맞는지 감을 잡을 수 있을 거예요.

Docker Desktop에서 옮겨 온다면 연결 대상과 저장 데이터를 나눠서 확인하세요. 컨텍스트가 맞는지, 필요한 볼륨을 옮겼는지, 프로젝트가 정상적으로 동작하는지를 차례로 확인하면 전환 과정이 덜 헷갈립니다.

전체 기능은 OrbStack 공식 문서에서 확인할 수 있습니다.