Docker에 우분투, MariaDB 설치하기

1. Docker 설치

---

 

🐳 Docker로 Ubuntu와 MariaDB 설치하기 (Windows 11 Home 기준)

Docker를 이용하면 MariaDB를 훨씬 더 간단하고 깔끔하게 실행할 수 있습니다. 설치와 삭제가 자유롭고, 여러 버전도 동시에 다룰 수 있어 실제 서비스와 유사한 환경을 만들 수 있습니다. 이 글에서는 Windows 11 Home 사용자 기준으로 Docker, Ubuntu, MariaDB 설치 방법을 순서대로 안내합니다.

---

✅ 1단계: Docker 설치

📌 다운로드

🔗 Docker Desktop 공식 다운로드

• Windows 11 Home 사용자는 Download for Windows – AMD64 클릭
• 설치 파일 실행 후 기본 설정 그대로 진행

📌 설치 전 요구사항 확인

항목	설명
OS	Windows 10/11 (Home 포함)
가상화 기능	BIOS에서 Virtualization(VT-x) 활성화
WSL 2	설치 필요 (아래 단계 참고)

📌 설치 후 WSL 2 백엔드 활성화 (Home 필수)

wsl --install

위 명령어 실행 후 Microsoft Store에서 Ubuntu 설치
🔗 Ubuntu 설치 바로가기

Ubuntu를 설치한 뒤에는 다음과 같이 초기 설정이 나타납니다:

Please create a default UNIX user account.
Enter new UNIX username: yourname

→ 사용자 이름 입력 (사용자명은 소문자 영어, 숫자 가능 / 띄어쓰기, 한글 안 됨)

사용자명 입력 후 비밀번호 설정(2회)
프롬프트에 다음과 같이 뜨면 성공입니다:

yourname@DESKTOP-XXXX:~$

---

✅ 2단계: Docker에서 Ubuntu 컨테이너 실행

Ubuntu 개발 환경을 Docker로 실행하고 싶은 경우 다음을 수행하세요:

docker pull ubuntu
docker run -it --name ubuntu-dev ubuntu

• -it: 터미널 모드
• --name ubuntu-dev: 컨테이너 이름 지정
• ubuntu: 사용할 이미지 이름

셸이 실행되면 아래처럼 root@컨테이너ID:/# 형태로 바뀝니다.
이 안에서 일반적인 Ubuntu 명령어 사용 가능 (ls, apt, cd, 등)

✅ 종료 및 재실행

# 종료
exit

# 다시 시작할 때
docker start -ai ubuntu-dev

---

✅ 3단계: Ubuntu 개발 환경 설정

Ubuntu 안에서 기본 개발 도구 설치:

apt update
apt install -y vim git curl build-essential

설치되는 도구 설명:

패키지명	역할
vim	텍스트 편집기
git	버전 관리 도구
curl	HTTP 요청 및 테스트
build-essential	컴파일 도구 모음 (gcc, make 등)

이 패키지들은 나중에 MariaDB 소스 빌드, 의존성 해결, API 테스트 등에서 필수입니다.

vim 없으면 서버에서 코드 수정할 때 매우 불편함

git은 거의 모든 개발 프로젝트가 Git 기반이라 필수

curl은 REST API, 네트워크 관련 작업에 자주 쓰임

build-essential 없으면 MariaDB, Node.js 네이티브 모듈, Python 패키지 등 설치 실패하는 경우가 많음

---

✅ 4단계: MariaDB Docker로 실행

이제 Docker Desktop에서 MariaDB를 바로 실행해보세요:

1. Docker Desktop과 WSL 2 통합 설정

 WSL 2 (Ubuntu 등 리눅스 배포판)에서 docker 명령어가 인식되지 않는 문제를 해결하기 위해 Docker Desktop에서 WSL 연동 설정을 하세요.

 

1) Docker Desktop에 로그인하고 설정 들어가서

---

 

2) "Resources > WSL Integration" 메뉴 클릭

• 왼쪽 메뉴: Resources > WSL Integration
• "Enable integration with my default WSL distro" 체크
• 하단에 설치된 배포판 목록이 보입니다.
  • 예: Ubuntu, Ubuntu-20.04, Ubuntu-24.04 등

✅ 현재 사용하는 WSL 배포판을 확인해서 활성화하세요.
예: Ubuntu-24.04가 현재 사용 중이면 그 항목 체크

적용 후에는 Docker Desktop이 Ubuntu WSL 환경과 통신할 수 있게 됩니다.

3) 저장 후 Docker Desktop 재시작

• 변경사항 저장
• Docker Desktop 종료 후 다시 실행 (또는 그냥 Apply & Restart)

---

✅ 이후 다시 시도

WSL 터미널(Ubuntu 등)에서 다시 실행:

docker --version

정상 출력되면:

docker run -d \
  --name mariadb \
  -e MARIADB_ROOT_PASSWORD=my-secret-pw \
  -p 3306:3306 \
  mariadb

정상 동작 시, docker ps 명령어로 실행 상태 확인 가능.

---

📌 추가 팁: WSL에서 현재 기본 배포판 확인

wsl -l -v

ccc출력 예시:

  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

→ 여기 표시된 이름이 Docker Desktop 설정에서 활성화해야 할 배포판입니다.

 

---

🔄 확인 후에도 안 될 경우

• Docker Desktop 완전히 종료 → 관리자 권한으로 재실행
• wsl --shutdown 후 다시 터미널 열기
• 윈도우 재시작

항목	설명
-d	백그라운드 실행
--name mariadb	컨테이너 이름
-e MARIADB_ROOT_PASSWORD=...	루트 비밀번호 지정
-p 3306:3306	로컬포트:컨테이너포트 매핑
mariadb	사용할 이미지 이름 (최신 버전 자동 다운로드)

실행 후 확인:

docker ps

MariaDB 접속:

docker exec -it mariadb mariadb -u root -p

---

✅ 5단계: 설치 확인

Docker와 MariaDB가 정상 설치됐는지 확인합니다.

docker --version
# 예시: Docker version 24.0.5, build ce2f9fe

docker run hello-world
# 예시: Hello from Docker!

---

🚨 설치 중 자주 발생하는 오류 & 해결 방법

증상	해결 방법
Docker 실행 안 됨	BIOS에서 가상화(VT-x) 활성화 확인
Docker 명령어 인식 안 됨	설치 후 재부팅, 환경 변수 등록 확인
WSL2 설정 오류	wsl --install, wsl --set-default-version 2 다시 실행
MariaDB 접속 오류	포트 충돌 여부 확인, 컨테이너 재시작 (docker restart mariadb)

 

---

💬 다음 단계

• MariaDB를 Docker Volume으로 데이터 영구 저장하는 방법
• docker-compose.yml 파일로 컨테이너 자동 실행 구성하기
• Node.js + MariaDB 연동 실습 예제

---

 

🧱 1. MariaDB 데이터를 Docker Volume으로 영구 저장하는 방법

Docker는 기본적으로 컨테이너 삭제 시 데이터도 함께 사라지므로, 데이터를 유지하려면 "볼륨(volume)"을 사용해야 합니다.

docker volume create mariadb_data

📦 볼륨을 사용하는 방식으로 컨테이너 실행

docker run -d \
  --name mariadb \
  -e MARIADB_ROOT_PASSWORD=my-secret-pw \
  -p 3306:3306 \
  -v mariadb_data:/var/lib/mysql \
  mariadb

-v mariadb_data:/var/lib/mysql
MariaDB의 데이터가 저장되는 경로(/var/lib/mysql)를 호스트의 볼륨(mariadb_data)에 연결하여, 컨테이너를 삭제해도 데이터는 유지됩니다.

---

⚙️ 2. docker-compose.yml로 자동 실행 설정

매번 명령어를 입력하는 번거로움을 줄이고, 컨테이너 구성을 코드로 관리하기 위해 docker-compose를 사용합니다.

📄 docker-compose.yml 예시

version: '3.8'
services:
  mariadb:
    image: mariadb
    container_name: mariadb
    environment:
      MARIADB_ROOT_PASSWORD: my-secret-pw
    ports:
      - "3306:3306"
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  mariadb_data:

✅ 실행 방법

docker compose up -d

🔄 중단 및 재시작

docker compose down    # 컨테이너 중지 및 정리
docker compose up -d   # 다시 실행

---

🌐 3. Node.js + MariaDB 연동 실습 예제

📁 프로젝트 디렉토리 구조 예시

node-mariadb-example/
├── index.js
├── package.json
└── docker-compose.yml

📦 의존성 설치

npm init -y
npm install express mariadb

📝 index.js 예제 코드

const express = require('express');
const mariadb = require('mariadb');
const app = express();
const port = 3000;

const pool = mariadb.createPool({
  host: 'localhost',
  user: 'root',
  password: 'my-secret-pw',
  database: 'test', // 사전에 생성하거나 아래에서 쿼리로 생성 가능
  connectionLimit: 5
});

app.get('/', async (req, res) => {
  let conn;
  try {
    conn = await pool.getConnection();
    const rows = await conn.query('SELECT NOW() AS now');
    res.send(`현재 시간: ${rows[0].now}`);
  } catch (err) {
    res.status(500).send('DB 연결 실패: ' + err);
  } finally {
    if (conn) conn.release();
  }
});

app.listen(port, () => {
  console.log(`서버 실행 중: http://localhost:${port}`);
});

💡 포인트

• Docker 컨테이너에서 DB가 돌아가고, Node.js는 호스트에서 실행될 수도 있고, 다른 컨테이너로도 구성 가능
• 로컬에서 접속 시엔 localhost 또는 127.0.0.1로 접근
• 컨테이너 간 통신을 하려면 container_name으로 접근해야 함 (host: 'mariadb')

---

🔚 마무리

이제 다음과 같은 구성을 완료했습니다:

• ✅ MariaDB 데이터 볼륨으로 영구 저장
• ✅ docker-compose를 통한 자동 실행 및 관리
• ✅ Node.js로 DB 연동 실습

---

 

---