Apache Airflow 설치 및 Docker Compose 활용 가이드

Airflow는 워크플로우(Workflow) 관리 도구로, 데이터 파이프라인을 시각적으로 설계하고 스케줄링할 수 있는 강력한 플랫폼입니다.
이 포스팅에서는 **직접 설치(pip 기반)**와 Docker Compose 기반 두 가지 방식으로 Airflow를 설치하고,
도커 실행 중 발생할 수 있는 권한 오류 및 WSL 마운트 에러 해결법까지 다룹니다.

 

Airflow 기본 설치 (pip 기반)

먼저, Python 환경에서 Airflow를 직접 설치하는 방식입니다.

# airflow home directory 설정
export AIRFLOW_HOME=~/airflow

# 설치할 airflow 버전 지정
export AIRFLOW_VERSION=2.6.2

# 현재 설치된 Python 버전 추출
export PYTHON_VERSION="$(python --version | cut -d " " -f 2 | cut -d "." -f 1-2)"

# 제약(Constraint) 파일 URL 설정
export CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"

# airflow 설치
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

명령어 해석

명령어	의미
export AIRFLOW_HOME=~/airflow	Airflow 실행 시 기본 디렉토리를 ~/airflow로 설정
export AIRFLOW_VERSION=2.6.2	설치할  Airflow 버전 지정
export  PYTHON_VERSION=...	현재 Python 버전 추출 (예.3.8)
export  CONSTRAINT_URL=...	Python 버젼별 Airflow 종속성 관리 URL 지정
pip install ...	위 설정값을 사용하여 Airflow 설

constraint 파일은 Airflow에서 요구하는 패키지 버전 조합을 고정하기 위해 사용됩니다.
잘못된 버전 충돌을 방지하는 핵심 역할을 합니다.

 

Airflow 실행 (Standalone 모드)

설치가 완료되면 아래 명령어로 Airflow를 단독 실행할 수 있습니다.

# start airflow
airflow standalone

설명

이 명령어는 내부적으로 다음 과정을 자동 실행합니다.

1. SQLite 데이터베이스 초기화 (airflow db init)
2. 기본 관리자 계정 생성
3. Webserver + Scheduler 프로세스 자동 실행
4. 접속 주소 및 계정 정보 출력

접속: http://localhost:8080

기본 계정: admin / admin

 

 

Docker Compose를 활용한 설치

Airflow는 여러 서비스(Postgres, Redis, Scheduler, Webserver 등)를 포함하므로
Docker Compose 환경을 활용하면 훨씬 간단하게 구성할 수 있습니다.

# download docker compose file
curl -LfO 'https://airflow.apache.org/docs/apache-airflow/2.6.2/docker-compose.yaml'

명령어 해석

명령어	설명
curl	파일 다운로드 명령어
-L	리디렉션 허용(공식 사이트에서 실제 파일로 연결됨)
-f	실패 시 오류 메세지 출력
-O	다운로드 파일을 원래 이름으로 저장
'https://airflow.apache.org/docs/apache-airflow/2.6.2/docker-compose.yaml'	Airflow 2.6.2 버전용 Docker Compose 설정 파일 경로

이 명령으로 docker-compose.yaml 파일이 로컬 디렉토리에 저장됩니다.

 

 

Airflow Docker Compose 실행

docker compose up airflow-init
docker compose up -d

• airflow-init: DB 초기화 및 사용자 생성
• -d: 백그라운드 실행(detach 모드)

접속 주소 👉 http://localhost:8080

 

Airflow Docker 기반의 아키텍처

 

실행 중 발생한 오류와 해결 방법

Airflow Docker 실행 중 아래와 같은 오류가 발생할 수 있습니다.

 

오류 — Permission Denied (로그 디렉토리 접근 불가)

PermissionError: [Errno 13] Permission denied: '/opt/airflow/logs/scheduler'

원인

./logs 디렉토리가 root 소유이거나 권한이 제한되어 있어
Airflow 컨테이너 내부에서 로그를 쓸 수 없을 때 발생.

 

해결

chmod -R 777 ./dags ./logs ./plugins

 

 

 

 

정리하면

 

이번 실습에서 핵심적으로 배운 점 👇

• Airflow는 환경 일관성이 매우 중요하다.
• logs, dags, plugins 디렉토리 권한 문제는 Docker 실행 실패의 주원인이다.
• WSL --shutdown은 Docker 마운트 에러 해결에 매우 효과적이다.

Airflow는 처음엔 설치가 까다로워 보이지만,
docker-compose.yaml + .env + 폴더 권한 세 가지 세팅만 맞추면 안정적으로 실행됩니다.