개요

이번에는 AWX 24.6.1 버전을 도커 환경에 설치하는 방법에 대해 알아본다.

기본적으로 AWX 18.0 버전부터는 AWX Operator를 사용하여 AWX를 설치하는 것이 권장된다. Docker 환경에 설치 및 실행할 수 있지만, 개발/테스트 용으로만 권장된다.


설치 시 주의사항

  • 2026.03.04 기준 아래의 방법으로 설치 및 정상 동작을 확인했다.
  • 내부적으로 CentOS 9 Stream 최신 버전의 컨테이너 이미지를 사용하면서 각 패키지들끼리 호환이 안되는 상황이 종종 일어난다.
  • awx 소스 코드 내부에서도 github를 통해 필요한 패키지들을 다운로드 받는데 특정 버전이 아닌 가장 최신 버전 또는 개발 버전을 설치하도록 되어 있어 마찬가지로 호환 문제로 설치가 제대로 안되는 상황이 일어난다.


설치 환경

Docker 환경에서 AWX를 설치할 때 사용한 환경을 기술한다. OS로 Rocky Linux 9을 사용하면서, dnf의 기본 리포지토리를 통해 설치할 수 파이썬 버전 (3.9.x)을 사용했음에 유의한다.

  • Rocky Linux 9.7
  • Docker 26.1.4
  • Docker-compose 2.35.1
  • Python 3.9.25
  • ansible 7.5.0


AWX 소스 다운로드

(awx) [ahrah@jslim108 awx-builder]$ git clone -b 24.6.1 https://github.com/ansible/awx.git awx-24.6.1
(awx) [ahrah@jslim108 awx-builder]$ cd awx-24.6.1


설치 관련 파일 수정

Dockerfile.j2

  • 컨테이너 이미지 생성 시 특정 버전의 패키지가 설치되도록 아래와 같이 변경

openssl-3.0.7

  • centos stream 9에서는 최신 버전의 패키지만 설치할 수 있으며, 현재 기준에서는 3.5.2 만 설치 가능
    • 변경 내용 : openssl-3.0.7 -> openssl
  • 변경 전
(awx) [ahrah@jslim108 awx-24.6.1]$ vi tools/ansible/roles/dockerfile/templates/Dockerfile.j2

~~~~ (생략) ~~~~
# Install build dependencies
RUN dnf -y update && dnf install -y 'dnf-command(config-manager)' && \

~~~~ (생략) ~~~~
    openldap-devel \
    # pin to older openssl, see jira AAP-23449
    openssl-3.0.7 \
    patch \
    postgresql \
    postgresql-devel \
    python3.11 \
    "python3.11-devel" \
    "python3.11-pip" \
    "python3.11-setuptools" \
    "python3.11-packaging" \
    "python3.11-psycopg2" \
    swig \
    unzip \
    xmlsec1-devel \
    xmlsec1-openssl-devel
    
~~~~ (생략) ~~~~

# Install runtime requirements
RUN dnf -y update && dnf install -y 'dnf-command(config-manager)' && \
    dnf config-manager --set-enabled crb && \
    dnf -y install acl \
    git-core \
    git-lfs \
    glibc-langpack-en \
    krb5-workstation \
    nginx \
    "openldap >= 2.6.2-3" \
    # pin to older openssl, see jira AAP-23449
    openssl-3.0.7 \
    postgresql \
    python3.11 \
    "python3.11-devel" \
    "python3.11-pip*" \
    "python3.11-setuptools" \
    "python3.11-packaging" \
    "python3.11-psycopg2" \
    rsync \
    rsyslog-8.2102.0-106.el9 \
    subversion \
    sudo \
    vim-minimal \
    which \
    unzip \
    xmlsec1-openssl && \
    dnf -y clean all

~~~~ (생략) ~~~~
  • 변경 후
(awx) [ahrah@jslim108 awx-24.6.1]$ vi tools/ansible/roles/dockerfile/templates/Dockerfile.j2

~~~~ (생략) ~~~~
# Install build dependencies
RUN dnf -y update && dnf install -y 'dnf-command(config-manager)' && \
~~~~ (생략) ~~~~
    nss \
    openldap-devel \
    # pin to older openssl, see jira AAP-23449
    openssl \
    patch \
    postgresql \
    postgresql-devel \
    python3.11 \
    "python3.11-devel" \
    "python3.11-pip" \
    "python3.11-setuptools" \
    "python3.11-packaging" \
    "python3.11-psycopg2" \
    swig \
    unzip \
    xmlsec1-devel \
    xmlsec1-openssl-devel
    
~~~~ (생략) ~~~~

# Install runtime requirements
RUN dnf -y update && dnf install -y 'dnf-command(config-manager)' && \
    dnf config-manager --set-enabled crb && \
    dnf -y install acl \
    git-core \
    git-lfs \
    glibc-langpack-en \
    krb5-workstation \
    nginx \
    "openldap >= 2.6.2-3" \
    # pin to older openssl, see jira AAP-23449
    openssl \
    postgresql \
    python3.11 \
    "python3.11-devel" \
    "python3.11-pip*" \
    "python3.11-setuptools" \
    "python3.11-packaging" \
    "python3.11-psycopg2" \
    rsync \
    rsyslog-8.2102.0-106.el9 \
    subversion \
    sudo \
    vim-minimal \
    which \
    unzip \
    xmlsec1-openssl && \
    dnf -y clean all

~~~~ (생략) ~~~~

pip constraints 추가

  • chardet은 requirements 파일에 등록되어있지 않지만 tox의 의존성 패키지로 최신 버전이 설치된다.
    • 2026.02.24 기준 최신 버전 : 6.0.0.post1
  • 문제는 이 최신 버전이 requirements/requirements.txt 에 의해 설치되는 requests 2.31.0 버전과 호환이 되지 않는다.
    • 호환되는 chardet 버전은 3.0.2 이상 6.0.0 미만이다.
    • 설치된 requests의 init.py 에서 확인 가능
  • requests와 chardet 간 버전 호환성이 맞지 않아 추후 awx 컨테이너 실행 시 아래와 같은 오류 메시지가 출력된다.
/var/lib/awx/venv/awx/lib64/python3.11/site-packages/requests/__init__.py:109: RequestsDependencyWarning: urllib3 (1.26.18) or chardet (6.0.0.post1)/charset_normalizer (3.3.2) doesn't match a supported version!
  warnings.warn(
  • requirements 에 chardet==5.2.0 을 명시해도 이미지 빌드 과정에서 최신 버전으로 업그레이드가 되기 때문에 아래와 같이 설정을 추가하여 버전이 고정되어 설치되게 한다.
(awx) [ahrah@jslim108 awx-24.6.1]$ vi tools/ansible/roles/dockerfile/templates/Dockerfile.j2

~~~~ (생략) ~~~~
# 아래 2줄 추가. 반드시 make requirements_awx 보다 앞에 추가해야 한다.
RUN echo "chardet==5.2.0" > /tmp/requirements/constraints.txt
ENV PIP_CONSTRAINT=/tmp/requirements/constraints.txt

RUN cd /tmp && make requirements_awx


requirements

  • 이미지 설치 시 ansible-runner 를 설치하게 되는데 가장 최신 브랜치 (devel) 소스 코드를 사용한다. 문제는 최신 코드는 python 3.10 이상을 요구하지만 centos 9 stream 에서 dnf 로 설치하게 되는 가장 최신 버전은 python 3.9 이다. 이대로 놔두면 설치가 안되기 때문에 python 3.9 를 사용하는 ansible-runner 를 다운로드 받도록 아래와 같이 수정한다.
# 이대로 빌드할 경우 보게 되는 에러 메시지

~~~~ (생략) ~~~~

49.96 INFO: pip is looking at multiple versions of aiohttp to determine which version is compatible with other requirements. This could take a while.
49.96 INFO: pip is looking at multiple versions of adal to determine which version is compatible with other requirements. This could take a while.
49.96 ERROR: Package 'ansible-runner' requires a different Python: 3.9.23 not in '>=3.10'
49.96 WARNING: You are using pip version 21.2.4; however, version 25.2 is available.
49.96 You should consider upgrading via the '/var/lib/awx/venv/awx/bin/python3.9 -m pip install --upgrade pip' command.
50.78 make: *** [Makefile:142: requirements_awx] Error 1
------
Dockerfile:59
--------------------
  57 |         /tmp/requirements/
  58 |     
  59 | >>> RUN cd /tmp && make requirements_awx
  60 |     
  61 |     ARG VERSION
--------------------
ERROR: failed to build: failed to solve: process "/bin/sh -c cd /tmp && make requirements_awx" did not complete successfully: exit code: 2
make: *** [Makefile:562: docker-compose-build] Error 1
  • ansible/django-ansible-base 설치 버전을 AWX 24.6.1 릴리즈 이전 날짜로 수정하여 다운로드 하도록 변경한다.
    • 기본값을 사용하면 컨테이너 생성 시 django 에서 admin 계정을 생성할 시에 에러가 발생하면서 이후 설치가 진행되지 않는다.
  • 변경
(awx) [ahrah@jslim108 awx]$ vi requirements/requirements_git.txt

## 변경 전 
git+https://github.com/ansible/ansible-runner.git@devel#egg=ansible-runner
django-ansible-base @ git+https://github.com/ansible/django-ansible-base@devel#egg=django-ansible-base[rest_filters,jwt_consumer,resource_registry,rbac]


## 변경 후
git+https://github.com/ansible/ansible-runner.git@2.3.2#egg=ansible-runner
django-ansible-base @ git+https://github.com/ansible/django-ansible-base@2025.5.8#egg=django-ansible-base[rest_filters,jwt_consumer,resource_registry,rbac]


이미지 빌드

  • receptor 설치 시 AWX 22.1.0 이 출시된 2023.4.19 시기와 맞는 v.1.4.0.dev2 버전을 사용하도록 설정 후 이미지 빌드
    • 현재 사용하고 있는 AWX 22.1.0 컨테이너 내부에 설치된 receptor 버전이 1.4.0.dev2 라 기존 버전과 맞추기 위한 조치
(awx) [ahrah@jslim108 awx-22.1.0]$ export RECEPTOR_IMAGE=quay.io/ansible/receptor:v1.6.3
(awx) [ahrah@jslim108 awx]$ make docker-compose-build

(awx) [ahrah@jslim108 awx]$ docker images
REPOSITORY                  TAG       IMAGE ID       CREATED          SIZE
ghcr.io/ansible/awx_devel   HEAD      079fe15b3405   About a minute ago   2.29GB

컨테이너 생성

(awx) [ahrah@jslim108 awx-24.6.1]$ make docker-compose COMPOSE_UP_OPTS=-d

(awx) [ahrah@jslim108 awx-24.6.1]$ docker ps -a
CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS              PORTS                                                                                                                                                                                                                                                                                                                                                                                NAMES
694fbbfa4fb4   ghcr.io/ansible/awx_devel:HEAD     "/entrypoint.sh laun…"   2 minutes ago   Up About a minute   0.0.0.0:2222->2222/tcp, :::2222->2222/tcp, 0.0.0.0:6899->6899/tcp, :::6899->6899/tcp, 0.0.0.0:7899-7999->7899-7999/tcp, :::7899-7999->7899-7999/tcp, 0.0.0.0:8013->8013/tcp, :::8013->8013/tcp, 0.0.0.0:8043->8043/tcp, :::8043->8043/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 22/tcp, 0.0.0.0:9888->9888/tcp, :::9888->9888/tcp, 0.0.0.0:3000->3001/tcp, :::3000->3001/tcp   tools_awx_1
e4c2da494294   quay.io/sclorg/postgresql-15-c9s   "container-entrypoin…"   2 minutes ago   Up 2 minutes        0.0.0.0:5441->5432/tcp, :::5441->5432/tcp                                                                                                                                                                                                                                                                                                                                            tools_postgres_1
8e7e9aeb7ae7   redis:latest                       "redis-server /usr/l…"   2 minutes ago   Up 2 minutes        6379/tcp                                                                                                                                                                                                                                                                                                                                                                             tools_redis_1
  • 컨테이너가 실행되면서 awx 내부의 패키지들이 설치되고 실행된다. 이 때 awx 접속용 admin 계정의 임시 패스워드가 로그에 출력된다. 아래와 같이 로그를 통해 확인한다.
(awx) [ahrah@jslim108 awx]$ docker logs -f tools_awx_1

~~~~ (생략) ~~~~

  Applying sso.0001_initial... OK
  Applying sso.0002_expand_provider_options... OK
  Applying sso.0003_convert_saml_string_to_list... OK
Superuser created successfully.
Admin password: sesGgvnrutmglPkIBtkE
Default organization added.
Demo Credential, Inventory, and Job Template added.
(changed: True)

~~~~ (생략) ~~~~
  • ui 초기화
    • VM을 사용하는 경우 최소 10GB 이상이 필요하다.
(awx) [ahrah@jslim108 awx-24.6.1]$ docker exec tools_awx_1 make clean-ui ui-devel

~~~~ (생략) ~~~~

Search for the keywords to learn more about each warning.
To ignore, add // eslint-disable-next-line to the line before.

File sizes after gzip:

  921.82 kB  build/static/js/main.be3da92f.js
  99.29 kB   build/static/css/main.bcaaa591.css
  61.85 kB   build/static/js/489.6fff47ab.chunk.js
  48.75 kB   build/static/js/118.55093eea.chunk.js
  45.69 kB   build/static/js/138.c73deea6.chunk.js
  44.45 kB   build/static/js/787.49d56b6e.chunk.js
  44.06 kB   build/static/js/896.7b610740.chunk.js
  43.2 kB    build/static/js/11.355f18b0.chunk.js
  42.28 kB   build/static/js/418.0a72109b.chunk.js
  30.71 kB   build/static/js/311.0bfa73ce.chunk.js
  386 B      build/static/js/979.f16bcc0c.chunk.js

The bundle size is significantly larger than recommended.
Consider reducing it with code splitting: https://goo.gl/9VhYWB
You can also analyze the project dependencies: https://goo.gl/LeUzfb

The project was built assuming it is hosted at ./.
You can control this with the homepage field in your package.json.

The build folder is ready to be deployed.

Find out more about deployment here:

  https://cra.link/deployment

touch awx/ui/.ui-built
make[1]: Leaving directory '/awx_devel'


AWX 접속

앞서 확인한 admin 의 임시 패스워드를 통해 접속한다. 접속 시 다음의 tcp 포트를 이용하면 된다.

  • http 포트 : TCP 8013
  • https 포트 : TCP 8043


난 24.6.1을 설치했는데 왜?

AWX 이미지를 빌드할 때 파이썬의 동적 버전 관리 도구 setuptools_scm을 사용한다. 이 도구는 현재 소스코드 폴더의 git 상태를 실시간으로 읽어서 버전을 결정한다. 앞서 Dockerfile.j2 파일 등을 수정했는데 원래의 24.6.1 공식 소스코드에서 파일이 하나라도 수정되면 (Dirty state) setuptools_scm 은 사용자가 수정한 커스텀 버전으로 인식하게 된다. setuptools_scm 에 의해 버전이 변경되는 공식은 다음과 같다.

공식 문서


참고자료

Docker Compose for Development

Run the latest Ansible AWX in Docker containers

Basic Setup and Use of Podman in a Rootless environment

태그: ,

카테고리:

Published:

Updated:  

참고