Intel N100 홈서버에 MariaDB 구축하기 : Docker Compose로 데이터베이스 서버 만들기

 

 

※ 이 글은 운영자가 직접 홈서버를 운영하며 경험한 내용을 바탕으로, MariaDB와 Docker의 공식 문서도 함께 참고해 작성했습니다. 문장을 정리하고 구성할 때 AI 도구의 도움을 받기도 했지만, 최종 내용은 운영자가 직접 꼼꼼히 확인했습니다.

Intel N100 홈서버에 MariaDB 구축하기 : Docker Compose로 데이터베이스 서버 만들기

도입

6주차 월요일에는 홈서버에 어떤 데이터베이스를 쓰는 게 좋을지 고민해봤어요. SQLite, MySQL, MariaDB, PostgreSQL을 각각 비교해봤는데, 지금 제가 가진 Intel N100 홈서버 환경에서는 설치 방법이나 Docker 관련 자료가 많고, 다양한 셀프 호스팅 서비스와 연동도 쉬운 MariaDB가 가장 현실적인 선택이라는 결론이 나왔습니다.

오늘은 화요일이라, 직접 MariaDB를 Docker Compose로 설치하는 과정을 정리해보려고 합니다. 이 글은 데이터베이스 고급 튜닝을 다루지 않습니다. 대신 홈서버에 MariaDB 컨테이너를 만들고, 데이터 저장 경로를 지정하며, 잘 실행되는지 확인하는 등 기본적인 설치와 설정에 초점을 맞췄습니다.

데이터베이스는 서비스가 기억해야 하는 정보를 담아두는 공간입니다. 예를 들어 WordPress에서는 글을, Nextcloud에서는 파일 정보를, n8n에서는 워크플로우 기록을 데이터베이스에 저장합니다. 이렇게 서비스가 오래도록 제대로 동작하려면 데이터베이스 역시 함께 안정적으로 관리되어야 합니다.

Intel N100 홈서버에서 MariaDB를 Docker Compose로 구축하는 과정을 정리한 다이어그램입니다. 디렉터리 구조, .env 설정, 데이터 저장 경로, 컨테이너 실행 및 접속 확인 흐름을 한눈에 확인할 수 있습니다.

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

본문

왜 MariaDB를 먼저 구축할까?

홈서버에서 데이터베이스를 처음 다룰 때는 익숙한 구조부터 시작하는 게 가장 중요합니다. MariaDB는 MySQL과 거의 호환되어 활용이 쉽고, 워드프레스나 넥스트클라우드, 북스택 등 다양한 서비스에서 자주 쓰입니다. 실제로 이런 서비스와 연동한 설치 예제가 많이 나와 있어 처음 접하는 사람도 따라 하기 좋습니다.

Intel N100 같은 저전력 홈서버에서 여러 가지 서비스를 돌릴 때는 단순히 성능만 따질 수 없었습니다. 다양한 자료가 얼마나 잘 갖춰져 있는지, Docker Compose 예제가 충분한지, 그리고 백업 방법이 얼마나 간단한지도 중요한 부분이었죠. 그런 기준에서 보면 MariaDB는 처음 실습해보기에 꽤 괜찮은 선택이었습니다.

• 웹서비스 호환성 : WordPress, Nextcloud 등에서 자주 사용
• 자료 접근성 : MySQL 계열 자료를 함께 참고 가능
• Docker 예제 : Compose 예제가 많아 홈랩 실습에 유리
• 운영 난이도 : 초기 학습 부담이 비교적 낮은 편
• 백업 연습 : 데이터베이스 백업과 복구 흐름을 익히기 좋음

MariaDB 폴더 구조 준비하기

Docker Compose로 MariaDB를 운영할 때는 먼저 각 서비스를 따로 디렉터리로 나누는 것이 좋습니다. 이렇게 하면 Compose 파일과 데이터 저장 위치가 한눈에 들어와서, 나중에 백업이나 점검을 할 때도 구조를 쉽게 파악할 수 있습니다.

/opt/docker/
└─ mariadb/
   ├─ compose.yml
   ├─ .env
   └─ data/

여기서 compose.yml은 MariaDB 컨테이너 실행 구조를 담고, .env 파일은 비밀번호나 포트처럼 바뀔 수 있는 설정값을 분리하는 데 사용할 수 있습니다. data 디렉터리는 MariaDB의 실제 데이터가 저장될 경로로 사용합니다.

# 예시 디렉터리 생성
mkdir -p /opt/docker/mariadb/data

# 작업 디렉터리 이동
cd /opt/docker/mariadb

실제로 서비스를 운영할 때는 경로나 권한 설정을 꼼꼼히 확인해야 합니다. 특히 데이터를 Bind Mount 방식으로 저장할 땐, 호스트 디렉터리의 권한이 제대로 되어 있지 않으면 컨테이너 실행에 문제가 생길 수 있습니다.

.env 파일로 기본 설정 분리하기

MariaDB 비밀번호를 Compose 파일 안에 직접 적는 방식도 가능하지만, 운영 관점에서는 .env 파일로 분리하는 편이 관리하기 쉽습니다. 다만 .env 파일은 보안 도구가 아니라 설정 분리 파일이므로 접근 권한과 백업 위치를 함께 관리해야 합니다.

# .env 예시
MARIADB_ROOT_PASSWORD=change_this_root_password
MARIADB_DATABASE=homelab
MARIADB_USER=homelab_user
MARIADB_PASSWORD=change_this_user_password
TZ=Asia/Seoul

위 값은 예시입니다. 실제 운영에서는 단순한 비밀번호를 그대로 사용하지 말고, 충분히 긴 비밀번호를 별도로 지정해야 합니다. 또한 공개 저장소나 공유 폴더에 .env 파일을 그대로 올리지 않는 것이 중요합니다.

Docker Compose 파일 작성하기

이제 MariaDB 컨테이너를 실행할 compose.yml 파일을 작성합니다. 아래 예시는 기본 실습용 구성입니다. 실제 환경에서는 포트 공개 여부, 네트워크 구성, 백업 방식에 맞춰 조정해야 합니다.

services:
  mariadb:
    image: mariadb:latest
    container_name: mariadb
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${MARIADB_DATABASE}
      MARIADB_USER: ${MARIADB_USER}
      MARIADB_PASSWORD: ${MARIADB_PASSWORD}
      TZ: ${TZ}
    volumes:
      - ./data:/var/lib/mysql
    ports:
      - "3306:3306"

이 구성에서 중요한 부분은 volumes입니다. ./data 디렉터리를 컨테이너 내부의 /var/lib/mysql에 연결하여 컨테이너를 재생성해도 데이터가 남을 수 있도록 구성합니다.

다만 ports 항목은 신중하게 다뤄야 합니다. 3306:3306으로 설정하면 호스트의 3306 포트를 통해 DB에 접근할 수 있습니다. 외부 네트워크에 직접 노출할 필요가 없다면 내부 Docker network에서만 접근하도록 구성하는 것도 검토할 수 있습니다.

MariaDB 컨테이너 실행하기

Compose 파일과 .env 파일을 준비했다면 컨테이너를 실행합니다.

# Compose 설정 확인
docker compose config

# MariaDB 컨테이너 실행
docker compose up -d

# 서비스 상태 확인
docker compose ps

docker compose config는 변수 치환이 제대로 되었는지 확인하는 데 도움이 됩니다. 비밀번호나 데이터베이스 이름이 비어 있거나 변수명이 잘못되었을 경우, 실행 전에 문제를 발견할 수 있습니다.

실행 후에는 docker compose ps로 컨테이너 상태를 확인합니다. Up 상태라면 일단 컨테이너는 실행 중입니다. 하지만 데이터베이스가 완전히 준비되기까지는 몇 초 정도 시간이 걸릴 수 있으므로 로그도 함께 확인하는 것이 좋습니다.

# 최근 로그 확인
docker compose logs --tail=100

# 특정 서비스 로그 확인
docker compose logs mariadb --tail=100

MariaDB 접속 확인하기

컨테이너가 제대로 실행되고 있다면, 이제 MariaDB에 접속해볼 차례입니다. 가장 간단한 방법은 컨테이너 안에서 바로 MariaDB 클라이언트를 실행하는 것입니다.

# 컨테이너 내부 접속
docker exec -it mariadb bash

# MariaDB 접속
mariadb -u root -p

일부 환경에서는 mysql -u root -p 명령이 사용되기도 합니다. MariaDB 클라이언트가 설치된 컨테이너라면 mariadb 또는 mysql 명령으로 접속할 수 있습니다.

접속 후에는 데이터베이스 목록을 확인합니다.

SHOW DATABASES;

.env에서 지정한 MARIADB_DATABASE 값이 정상적으로 반영되었다면, 초기 데이터베이스가 함께 생성되어 있어야 합니다.

테스트 데이터베이스와 사용자 확인하기

실습을 위해 데이터베이스를 하나 더 만들어볼 수 있습니다. 실제 운영 환경에서는 서비스마다 데이터베이스와 사용자 권한을 분리하는 것이 일반적이지만, 오늘은 전체적인 구축 과정을 알아보는 데에 집중해 간단하게 진행하겠습니다.

CREATE DATABASE testdb;

SHOW DATABASES;

데이터베이스가 정상적으로 생성됐다면 MariaDB 서버도 제대로 작동 중이라고 볼 수 있습니다. 다만, 실제 서비스에 연결할 때는 데이터베이스 이름이나 사용자명, 비밀번호, 호스트, 포트 번호 등을 모두 정확하게 입력해야 문제가 생기지 않습니다.

• DB Host : 같은 Docker network 안에서는 서비스명 사용 가능
• DB Port : 기본값은 3306
• DB Name : 서비스별로 별도 생성 권장
• DB User : root 계정보다 전용 사용자 권장
• Password : 충분히 긴 값 사용

데이터 영속성 확인하기

Docker로 데이터베이스를 운영할 때 가장 신경 써야 할 점은 바로 데이터가 안전하게 보관되는지입니다. 컨테이너는 언제든지 새로 만들 수 있지만, 데이터베이스 안의 데이터가 한 번 사라지면 다시 복구하기가 쉽지 않죠. 그렇기 때문에 데이터를 어떻게 보존할지 미리 잘 준비해 두는 것이 중요합니다.

이번 구성에서는 ./data 디렉터리를 /var/lib/mysql에 연결했습니다. 즉 MariaDB의 실제 데이터는 호스트의 /opt/docker/mariadb/data 경로에 남게 됩니다.

# 데이터 디렉터리 확인
ls -la /opt/docker/mariadb/data

# 디렉터리 크기 확인
du -sh /opt/docker/mariadb/data

컨테이너를 다시 만들어도 이 디렉터리가 남아 있다면 데이터도 그대로 보존됩니다. 그래서 MariaDB 백업을 계획할 때는 이 데이터 디렉터리를 잘 관리하는 것뿐만 아니라, SQL 덤프 방식의 백업도 따로 고려해보는 것이 좋습니다.

기본 보안 점검

홈서버에서 MariaDB를 운영할 때는 기본적인 보안 설정을 반드시 함께 챙겨야 합니다. 특히 데이터베이스 포트를 외부 인터넷에 바로 열어두는 것은 매우 신중하게 결정해야 할 사안입니다. 대부분의 셀프 호스팅 서비스에서는 같은 Docker 네트워크 내에서만 DB에 접근하게 해도 충분한 경우가 많으니, 굳이 외부로 포트를 개방할 필요는 없습니다. 이렇게 하면 보안 사고 위험도 크게 줄일 수 있습니다.

• root 비밀번호를 단순하게 설정하지 않습니다.
• 서비스별 전용 DB 사용자 생성을 고려합니다.
• DB 포트를 외부에 직접 노출하지 않는 구성을 우선 검토합니다.
• .env 파일을 공개 저장소에 올리지 않습니다.
• 백업 파일의 저장 위치와 접근 권한을 함께 관리합니다.

이번 글에서는 기본적인 구축 과정에 초점을 맞췄지만, 수요일에는 MariaDB 권한 설정과 접속 관련 문제를 어떻게 해결할 수 있는지 중점적으로 다뤄볼 예정입니다.

운영 로그

아래 표는 6주차 화요일을 기준으로 정리한 MariaDB Docker Compose 구축 항목입니다. 실제 값은 운영 환경이나 보안 정책, 네트워크 구성, 백업 방식에 따라 달라질 수 있습니다.

점검 항목	설정 또는 명령어	운영 판단
DB 종류	MariaDB	6주차 실습 기준 DB
실행 방식	Docker Compose	서비스 구조 문서화에 유리
데이터 경로	./data:/var/lib/mysql	컨테이너 재생성 대비
설정 파일	.env	비밀번호와 DB 이름 분리 관리
상태 확인	docker compose ps	컨테이너 실행 여부 확인
로그 확인	docker compose logs mariadb	초기화 오류와 권한 문제 확인

에디터의 해석 노트 (Editor's Lab Note)

• Docker 서비스를 여러 개 운영하다 보면 결국 데이터를 저장할 안정적인 공간이 필요해졌습니다.
• MariaDB는 자료가 많고 예제가 풍부하며 WordPress나 Nextcloud와도 잘 연결되는 편이었습니다.
• 이번 구축에서 가장 중요한 것은 컨테이너 실행보다 데이터 저장 경로를 분리하는 일이었습니다.
• 홈서버에서 데이터베이스는 설치보다 백업, 권한, 접속 범위를 함께 생각해야 하는 운영 요소였습니다.

참고 링크 (References)

1. MariaDB Documentation
2. MariaDB Official Docker Image
3. Docker Compose Documentation
4. Docker volumes documentation
5. docker compose logs reference

트러블슈팅

문제: MariaDB 컨테이너는 실행되지만 DB 접속이 되지 않음

MariaDB 컨테이너가 Up 상태로 보이더라도 DB 접속이 바로 되는 것은 아닐 수 있습니다. 초기화 중이거나, 비밀번호가 다르거나, 포트 또는 network 설정이 맞지 않을 수 있습니다.

확인: 컨테이너 상태, 로그, 환경 변수, 포트, 데이터 경로를 순서대로 점검

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

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

# Compose 최종 설정 확인
docker compose config

# 포트 확인
docker ps

# 데이터 경로 확인
ls -la /opt/docker/mariadb/data

원인: 비밀번호 오타, .env 변수명 오류, 포트 충돌, 데이터 디렉터리 권한 문제, 초기화 완료 전 접속 시도

해결: docker compose config로 변수 치환 결과를 확인하고, 로그에서 초기화 오류가 있는지 확인한 뒤 포트와 데이터 경로를 다시 점검

현재 구성에서는 DB 접속 문제를 바로 설정 변경으로 해결하기보다, 로그와 .env 값을 먼저 확인하는 편이 더 안정적이었습니다.

마무리

MariaDB를 Docker Compose로 구축하면서 가장 크게 느낀 점은, 데이터베이스가 그저 컨테이너 하나를 띄우는 것 이상이라는 사실이었습니다. MariaDB는 서비스가 꼭 기억해야 하는 중요한 정보를 담는 공간이기 때문에, 이 데이터는 컨테이너가 중단되거나 삭제돼도 계속 보존되어야 하죠.

이번 구축에서는 폴더 구조, .env 파일, Compose 설정, 데이터 경로, 로그 확인을 함께 다뤘습니다. 특히 ./data:/var/lib/mysql처럼 데이터 저장 위치를 명확히 분리하는 것은 나중에 백업과 복구를 설계할 때 중요한 기준이 됩니다.

월요일에는 어떤 데이터베이스를 선택할지 고민했고, 화요일에는 실제로 MariaDB를 구축했습니다. 이제 데이터를 저장할 공간이 준비되었으니, 수요일에는 MariaDB 사용자와 권한 설정 과정에서 발생할 수 있는 문제들을 트러블슈팅 관점으로 살펴보겠습니다.