Docker에서 WordPress를 설치해보자 : MariaDB와 연결되는 첫 번째 웹서비스

 

 

※ 이 글은 운영자가 직접 홈서버를 운영하며 겪은 경험과 WordPress, MariaDB, Docker 공식 문서를 참고해 작성했습니다. 글의 문장 정리와 구성에는 AI 도구의 도움을 약간 받았지만, 최종적으로는 운영자가 직접 내용을 검토하고 확인했습니다.

Docker에서 WordPress를 설치해보자: MariaDB와 연결되는 첫 번째 웹서비스

도입

어제는 WordPress가 왜 데이터베이스를 필요로 하는지 살펴봤습니다. 처음에는 블로그 글이 HTML 파일처럼 저장되는 줄 알았지만, 실제로는 글, 댓글, 사용자 정보, 설정값 같은 핵심 정보가 MariaDB에 저장된다는 점을 알게 됐습니다.

이번에는 한 걸음 더 나아가 WordPress를 직접 설치해보려고 합니다. 다만 이번 글은 단순히 명령어를 따라 하는 설치 기록이 아닙니다. WordPress 컨테이너와 MariaDB 컨테이너가 어떻게 연결되는지, 왜 같은 Docker 네트워크 안에 있어야 하는지, 그리고 왜 DB_HOST를 localhost가 아니라 서비스명으로 적어야 하는지 확인하는 글에 가깝습니다.

처음에는 WordPress 하나만 실행하면 블로그가 바로 만들어질 줄 알았어요. 그런데 실제로는 WordPress가 혼자 움직이는 것이 아니라 MariaDB와 계속 대화하면서 동작하더라고요. 결국 WordPress 설치는 웹 화면 하나를 띄우는 일이 아니라, 웹서비스와 데이터베이스가 서로 연결되는 구조를 만드는 일이었습니다.

Docker Compose 환경에서 WordPress와 MariaDB는 같은 Docker Network 안에서 서비스명으로 연결되며, Volume을 통해 데이터를 안전하게 보존하는 구조로 동작합니다.

※ 다이어그램은 운영 환경 설계를 바탕으로 AI 도구를 활용해 제작했으며, 최종 구성과 내용은 운영자가 직접 검수했습니다.
출처: 디지털 장난감

본문

왜 Docker로 WordPress를 설치할까?

WordPress를 설치하는 방법은 여러 가지가 있습니다. 서버에 직접 Apache, PHP, MariaDB를 설치할 수도 있고, 웹호스팅을 이용할 수도 있습니다. 하지만 홈서버에서 여러 서비스를 실험해보는 입장에서는 Docker Compose 방식이 꽤 편하게 느껴졌습니다.

Docker를 사용하면 WordPress와 MariaDB를 각각 컨테이너로 분리해서 실행할 수 있습니다. 문제가 생기면 컨테이너를 다시 만들 수 있고, 설정 파일을 정리해두면 다른 서버로 옮길 때도 구조를 이해하기 쉽습니다. 무엇보다 docker-compose.yml 하나에 서비스 구성을 기록해둘 수 있다는 점이 좋았습니다.

• 재설치가 쉽다: 컨테이너를 다시 만들 수 있습니다.
• 구성이 보인다: Compose 파일에 서비스 구조가 정리됩니다.
• 분리가 쉽다: WordPress와 MariaDB를 따로 관리할 수 있습니다.
• 이전이 쉽다: 설정 파일과 데이터 폴더를 기준으로 옮기기 좋습니다.

물론 Docker가 모든 문제를 해결해주는 것은 아닙니다. 오히려 처음에는 네트워크, Volume, 환경변수 같은 개념이 낯설 수 있어요. 그래도 홈서버에서 서비스를 하나씩 쌓아가는 방식에는 Docker Compose가 잘 맞는다고 느꼈습니다.

docker-compose.yml 구조 살펴보기

WordPress와 MariaDB를 함께 실행하려면 두 개의 서비스가 필요합니다. 하나는 웹 화면을 담당하는 WordPress이고, 다른 하나는 데이터를 저장하는 MariaDB입니다.

services:
  mariadb:
    image: mariadb:latest
    container_name: wordpress_mariadb
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: wordpress_db
      MYSQL_USER: wordpress_user
      MYSQL_PASSWORD: wordpress_password
    volumes:
      - ./mariadb_data:/var/lib/mysql

  wordpress:
    image: wordpress:latest
    container_name: wordpress_app
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: mariadb
      WORDPRESS_DB_NAME: wordpress_db
      WORDPRESS_DB_USER: wordpress_user
      WORDPRESS_DB_PASSWORD: wordpress_password
    volumes:
      - ./wordpress_data:/var/www/html
    depends_on:
      - mariadb

이 예시는 기본 구조를 이해하기 위한 형태입니다. 실제 운영에서는 비밀번호를 더 안전하게 관리하고, 이미지 버전을 고정하고, 백업 경로도 따로 정리하는 편이 좋습니다.

여기서 중요한 것은 WordPress와 MariaDB가 서로 다른 컨테이너라는 점입니다. 두 컨테이너가 따로 실행되지만, Compose 안에서는 같은 프로젝트 네트워크에 묶이기 때문에 서비스명으로 서로를 찾을 수 있습니다.

왜 DB_HOST가 localhost가 아닐까?

이번 글에서 가장 중요하게 느껴진 부분은 WORDPRESS_DB_HOST였습니다. 처음에는 데이터베이스가 같은 서버 안에 있으니 당연히 localhost를 쓰면 될 것 같았습니다.

그런데 Docker에서는 상황이 조금 달랐습니다. WordPress 컨테이너 안에서 localhost는 MariaDB 컨테이너가 아니라 WordPress 컨테이너 자기 자신을 가리킬 수 있습니다. 그래서 WordPress가 MariaDB를 찾으려면 Compose 서비스명인 mariadb를 사용해야 합니다.

입력값	의미	Docker 환경에서의 판단
localhost	현재 컨테이너 자신	MariaDB를 찾지 못할 수 있음
mariadb	Compose 서비스명	같은 네트워크 안에서 MariaDB 서비스로 연결
서버IP:3306	호스트 외부 포트 접근	구성에 따라 가능하지만 내부 연결에는 불필요할 수 있음

이 부분을 이해하고 나니 예전에 자주 보던 데이터베이스 연결 오류가 조금 다르게 보였습니다. 단순히 비밀번호가 틀린 문제가 아니라, WordPress가 MariaDB를 어디서 찾아야 하는지 모르는 상황일 수도 있었습니다.

Volume은 왜 필요할까?

WordPress와 MariaDB를 Docker로 실행할 때 Volume 설정도 중요합니다. 컨테이너는 삭제하고 다시 만들 수 있지만, 그 안의 데이터까지 함께 사라지면 곤란합니다.

MariaDB에는 게시글, 댓글, 사용자 정보, 설정값이 저장됩니다. WordPress 쪽에는 업로드한 이미지, 테마, 플러그인 파일이 들어갈 수 있습니다. 그래서 두 서비스 모두 데이터를 호스트 경로에 연결해두는 편이 좋습니다.

volumes:
  - ./mariadb_data:/var/lib/mysql
  - ./wordpress_data:/var/www/html

처음에는 WordPress 설치 화면이 뜨는지만 확인하려고 했습니다. 그런데 조금 더 생각해보니, 설치보다 중요한 것은 데이터를 어디에 보관할 것인가였습니다. 컨테이너가 아니라 데이터가 오래 남아야 블로그도 계속 이어질 수 있으니까요.

컨테이너 실행하기

Compose 파일을 준비했다면 이제 컨테이너를 실행할 수 있습니다. 작업 폴더에서 아래 명령어를 실행합니다.

docker compose up -d

실행 후에는 컨테이너 상태를 확인합니다.

docker compose ps

WordPress와 MariaDB가 모두 Up 상태라면 일단 기본 실행은 성공한 것입니다. 다만 여기서 끝내면 안 됩니다. 실제로 WordPress가 MariaDB에 연결되는지, 로그에 오류가 없는지 확인해야 합니다.

# WordPress 로그 확인
docker compose logs wordpress --tail=100

# MariaDB 로그 확인
docker compose logs mariadb --tail=100

로그를 확인하는 습관은 홈서버 운영에서 꽤 중요했습니다. 화면이 정상처럼 보여도 내부에서 경고나 오류가 반복되고 있을 수 있기 때문입니다.

브라우저에서 설치 화면 확인하기

컨테이너가 정상적으로 실행되었다면 브라우저에서 WordPress 설치 화면을 확인할 수 있습니다. 예시 구성에서는 호스트의 8080 포트를 WordPress 컨테이너의 80 포트에 연결했기 때문에 다음 주소로 접속합니다.

http://서버IP:8080

설치 화면이 보인다면 WordPress 컨테이너가 정상적으로 올라온 것입니다. 여기서 사이트 제목, 관리자 계정, 비밀번호 등을 입력하면 초기 설정을 진행할 수 있습니다.

이 과정에서 WordPress는 MariaDB에 필요한 테이블을 만들고, 사이트 기본 정보를 저장합니다. 겉으로는 설치 화면 몇 개를 넘기는 과정처럼 보이지만, 뒤에서는 WordPress와 MariaDB가 실제로 연결되고 있는 셈입니다.

설치보다 연결 구조가 더 중요했다

이번 실습에서 가장 크게 느낀 점은 WordPress 설치 자체보다 연결 구조가 더 중요하다는 것이었습니다. WordPress 컨테이너, MariaDB 컨테이너, Docker Network, Volume이 서로 맞물려야 하나의 웹서비스가 됩니다.

명령어만 보면 간단해 보이지만, 왜 이렇게 쓰는지 모르면 문제가 생겼을 때 막막해질 수 있습니다. 특히 DB_HOST, 데이터베이스 사용자, Volume 경로는 나중에 장애가 생겼을 때 가장 먼저 확인해야 할 부분이었습니다.

운영노트

아래 표는 Docker Compose로 WordPress와 MariaDB를 연결하면서 확인해야 할 운영 기록입니다. 실제 경로와 포트 번호는 운영 환경에 따라 달라질 수 있습니다.

확인 항목	확인 방법	운영 판단
WordPress 컨테이너	docker compose ps	Up 상태 확인
MariaDB 컨테이너	docker compose ps	DB 서비스 실행 확인
DB 연결 정보	WORDPRESS_DB_HOST	mariadb 서비스명 사용 확인
WordPress 데이터	./wordpress_data	업로드 파일과 설정 보존
MariaDB 데이터	./mariadb_data	DB 데이터 보존
접속 포트	8080:80	브라우저 접속 확인

에디터의 해석노트

처음에는 WordPress 하나만 설치하면 블로그가 바로 만들어지는 줄 알았어요. 그런데 Docker Compose로 구조를 살펴보니 WordPress는 혼자 움직이는 서비스가 아니었습니다.

WordPress는 화면을 담당하고, MariaDB는 데이터를 기억합니다. 그리고 Docker Network는 두 컨테이너가 서로를 찾을 수 있게 해줍니다. 이 세 가지가 맞물려야 비로소 하나의 블로그가 만들어지는 구조였습니다.

이번 글을 작성하면서 설치 명령어보다 연결 구조를 먼저 이해하는 것이 더 중요하다는 생각이 들었습니다. 명령어는 다시 찾아볼 수 있지만, 구조를 모르면 오류가 났을 때 어디를 봐야 할지 알기 어렵기 때문입니다.

참고 링크 (References)

1. WordPress Official Docker Image
2. How to install WordPress
3. Editing wp-config.php
4. MariaDB Official Docker Image
5. Docker Compose Documentation

트러블슈팅

문제: WordPress 설치 화면이 열리지 않거나 데이터베이스 연결 오류가 발생함

Docker Compose로 WordPress를 실행했는데 브라우저에서 설치 화면이 보이지 않거나, 데이터베이스 연결 오류가 나타날 수 있습니다. 이때는 WordPress만 확인하지 말고 MariaDB, 포트, Volume, 네트워크를 함께 확인해야 합니다.

확인: 컨테이너 상태, 포트, 로그, DB Host, Volume 경로를 순서대로 점검

# 컨테이너 상태 확인
docker compose ps

# WordPress 로그 확인
docker compose logs wordpress --tail=100

# MariaDB 로그 확인
docker compose logs mariadb --tail=100

# 포트 사용 확인
ss -tuln | grep 8080

원인: 80 또는 8080 포트 충돌, DB_HOST 설정 오류, MariaDB 초기화 지연, 비밀번호 불일치, Volume 권한 문제

해결: 포트 번호를 변경하고, WORDPRESS_DB_HOST가 mariadb로 되어 있는지 확인한 뒤, MariaDB 로그에서 초기화 완료 여부를 확인합니다.

• 포트 충돌: 8080:80을 다른 포트로 변경합니다.
• DB_HOST 오류: Docker 내부 연결에서는 localhost 대신 서비스명을 사용합니다.
• DB 초기화 지연: MariaDB가 완전히 준비될 때까지 로그를 확인합니다.
• 비밀번호 오류: MariaDB 환경변수와 WordPress 환경변수가 일치하는지 확인합니다.
• Volume 문제: 데이터 폴더 권한과 경로를 확인합니다.

이번 단계에서는 오류를 빨리 없애는 것보다, 어떤 항목이 WordPress와 MariaDB의 연결에 영향을 주는지 이해하는 것이 더 중요했습니다. 구조를 알면 다음 오류를 만났을 때도 조금 덜 당황할 수 있을 것 같습니다.

마무리

Docker에서 WordPress를 설치해보니, 생각보다 설치 명령어 자체는 어렵지 않았습니다. 하지만 WordPress와 MariaDB가 어떻게 연결되는지 이해하는 일이 더 중요하게 느껴졌어요.

WordPress는 화면을 보여주는 역할을 하고, MariaDB는 글과 설정을 기억합니다. 그리고 Docker Compose는 이 둘을 하나의 구조로 묶어줍니다. 이 흐름을 이해하고 나니 WordPress 설치가 단순한 웹사이트 만들기가 아니라, 여러 컨테이너가 함께 동작하는 작은 시스템을 만드는 일처럼 보였습니다.

다음 글에서는 WordPress를 조금 더 안정적으로 운영하기 위해 PHP 메모리 부족 문제와 기본 성능 설정을 살펴보겠습니다.