[이제와서 시작하는 Metabase 마스터하기 #2] Metabase 설치와 초기 설정

⚡ 빠른 답변

Q: Metabase 설치가 어렵나요? A: 아닙니다! Docker 명령어 한 줄만 복사-붙여넣기하면 5분 안에 완료됩니다.

Q: Docker가 뭔가요? 필수인가요? A: 프로그램을 상자에 담아 실행하는 도구입니다. 필수는 아니지만 가장 쉬운 방법이에요. 삭제도 간단합니다.

Q: 윈도우에서도 되나요? A: 네! 윈도우, 맥, 리눅스 모두 동일한 방법으로 설치 가능합니다.

---

시리즈 소개

안녕하세요! “이제와서 시작하는 Metabase 마스터하기” 두 번째 시간입니다.

지난 시간에 Metabase가 뭔지 알았으니, 이제 직접 설치해봅시다!

“어려우면 어떡하죠? 전 컴퓨터 잘 모르는데…“

걱정하지 마세요! 이 글에서는:

• ✅ 가장 쉬운 방법 딱 하나만 알려드립니다
• ✅ 복붙만 하면 됩니다 (명령어 직접 작성 NO!)
• ✅ 5분이면 끝납니다 (진짜로!)
• ✅ 오류 나도 해결 방법 바로 알려드립니다

이런 분들을 위해 준비했어요:

• 😰 “Docker? 처음 들어봐요…”
• 😱 “검은 화면(터미널)에 명령어 치는 게 무서워요…”
• 🤔 “설치하다가 막히면 어떡하죠?”

📌 이 글을 다 읽으면:

• 5분 뒤: Metabase 설치 완료! ✅
• 10분 뒤: 브라우저에서 Metabase 실행 중! ✅
• 15분 뒤: 첫 대시보드 구경! ✅

📌 2025년 10월 기준 최신 버전: v0.56.8

이 글에서 배울 것

핵심 (꼭 할 것!):

• ✅ Metabase 설치하기 (정말 쉬워요!)
• ✅ 브라우저에서 접속 확인하기
• ✅ 관리자 계정 만들기
• ✅ 샘플 데이터 둘러보기

부록 (나중에 필요하면):

• Docker Compose로 더 안정적으로 설치 (프로덕션용)
• 다른 설치 방법들 (JAR, 클라우드 등)
• 문제 해결 방법

💡 초보자 팁: 처음에는 “핵심” 부분만 따라하세요! “부록”은 나중에 회사에서 실제로 쓸 때 보면 됩니다.

1. 준비: Docker가 뭔가요?

“Docker? 처음 들어봐요…“

걱정하지 마세요! 쉽게 설명해드릴게요.

Docker = 프로그램을 포장해서 실행하는 도구

실생활 비유:

• 옛날 방식: 프로그램 설치 → 여기저기 파일 생성 → 삭제하기 어려움 😰
• Docker 방식: 상자 안에 프로그램 담기 → 깔끔! → 삭제? 상자만 버리면 끝! 😊

왜 Docker를 쓰나요?

1. 설치가 진짜 쉬워요
   • 명령어 하나로 끝
   • 컴퓨터를 지저분하게 만들지 않음
2. 삭제도 쉬워요
   • “마음에 안 들면?” → 명령어 하나로 깔끔하게 삭제
3. 어디서나 똑같이 작동해요
   • Windows, Mac, Linux 다 OK!

“근데 Docker 설치가 어렵지 않나요?”

→ 이것도 클릭 몇 번이면 끝납니다! 아래에서 알려드릴게요.

---

2. Docker 설치하기 (첫 번째 단계)

⏱️ 예상 시간: 3-5분

2-1. Docker가 이미 설치되어 있는지 확인

먼저 확인해봅시다! (이미 설치되어 있을 수도 있어요)

1단계: 터미널(또는 명령 프롬프트) 열기

• macOS: Cmd + Space → “터미널” 입력 → Enter
• Windows: Win + R → “cmd” 입력 → Enter
• Linux: Ctrl + Alt + T

2단계: 아래 명령어 입력

docker --version

결과 확인:

• ✅ Docker version 20.x.x... 나옴 → 설치 완료! 3단계로 건너뛰기 🎉
• ❌ command not found 또는 오류 → 설치 필요 → 바로 아래 계속

2-2. Docker 설치하기 (없는 경우만)

설치는 클릭 몇 번이면 끝납니다!

운영체제별 설치 방법:

macOS (맥)

1. Docker Desktop for Mac 다운로드 클릭
2. .dmg 파일 다운로드 (약 500MB)
3. 더블클릭해서 설치
4. Applications 폴더로 드래그
5. Docker 아이콘 클릭해서 실행
6. 화면 상단에 고래🐳 아이콘 보이면 성공!

Windows (윈도우)

1. Docker Desktop for Windows 다운로드 클릭
2. Docker Desktop Installer.exe 다운로드
3. 더블클릭해서 설치 (관리자 권한 필요)
4. 컴퓨터 재시작 (요청하면)
5. Docker Desktop 실행
6. 작업 표시줄에 고래🐳 아이콘 보이면 성공!

💡 Windows 팁:

• Windows 10/11 Home Edition 사용자는 WSL 2 설치가 필요할 수 있습니다
• 설치 중에 안내가 나오면 따라하세요 (자동으로 안내됨)

Linux (리눅스)

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# 로그아웃 후 다시 로그인

# 설치 확인
docker --version

설치 완료 확인:

docker --version
# Docker version 20.x.x 나오면 성공!

---

3. Metabase 설치하기 (두 번째 단계)

⏱️ 예상 시간: 2-3분

이제 Docker가 준비되었으니, Metabase를 설치합니다!

“복잡하지 않나요?” → 아니요! 명령어 하나만 복사 붙여넣기하면 끝입니다!

3-1. Metabase 실행 명령어

아래 명령어를 복사해서 터미널에 붙여넣고 Enter를 누르세요:

docker run -d -p 3000:3000 \
  --name metabase \
  -v ~/metabase-data:/metabase-data \
  metabase/metabase:v0.56.8

“이게 뭐 하는 명령어인가요?”

각 부분을 쉽게 설명하겠습니다:

• docker run → “Docker야, 프로그램 실행해줘”
• -d → “백그라운드에서 실행 (화면에 계속 안 보이게)”
• -p 3000:3000 → “3000번 포트로 접속할 수 있게 해줘”
• --name metabase → “이름을 ‘metabase’로 정해줘”
• -v ~/metabase-data:/metabase-data → “데이터를 내 컴퓨터에 저장해 (나중에 재시작해도 유지됨)”
• metabase/metabase:v0.56.8 → “Metabase 최신 버전 사용”

3-2. 첫 실행 (다운로드 중…)

처음 실행하면 이런 메시지가 나옵니다:

Unable to find image 'metabase/metabase:v0.56.8' locally
v0.56.8: Pulling from metabase/metabase
...

“오류인가요?” → 아니요! 정상입니다. Metabase 파일을 다운로드하는 중이에요.

⏱️ 다운로드 시간:

• 인터넷 빠름: 1-2분
• 인터넷 보통: 2-3분
• 인터넷 느림: 5분

다운로드가 끝나면 이런 메시지:

Status: Downloaded newer image for metabase/metabase:v0.56.8
abc123def456... (긴 숫자/문자)

이 긴 숫자가 나오면 성공! 🎉

3-3. Metabase가 잘 실행되는지 확인

“제대로 돌아가고 있나요?”

아래 명령어로 확인해봅시다:

docker ps

이런 화면이 나오면 성공입니다:

CONTAINER ID   IMAGE                         STATUS        PORTS
abc123def456   metabase/metabase:v0.56.8     Up 1 minute   0.0.0.0:3000->3000/tcp

중요: STATUS 확인!

• ✅ Up ... 나옴 → 정상 실행 중! 🎉
• ❌ 아무것도 안 나옴 → 문제 발생 (트러블슈팅 섹션 참고)

3-4. Metabase 시작 완료 기다리기

“언제 접속할 수 있나요?”

Metabase가 완전히 시작될 때까지 2-3분 기다려야 합니다.

진행 상황 확인하기:

docker logs -f metabase

화면에 로그가 주르륵 올라갑니다:

Starting Metabase...
Loading drivers...
Setting up database...
...
Metabase Initialization COMPLETE

“Metabase Initialization COMPLETE” 보이면 준비 끝! 🎉

💡 초보자 팁:

• 로그 보기 종료: Ctrl + C (Metabase는 계속 실행됨)
• 화면이 멈춘 것 같아도 기다리세요
• ERROR가 아니면 정상입니다!

---

4. 브라우저로 접속하기 (세 번째 단계)

⏱️ 예상 시간: 30초

드디어 접속할 시간입니다! 🎉

4-1. 접속하기

간단합니다:

1. 웹 브라우저 열기 (크롬, 사파리, 엣지, 파이어폭스 등 아무거나)
2. 주소창에 입력: http://localhost:3000
3. Enter!

화면 확인:

• ✅ 환영 화면 나옴 → 성공! 다음 단계로! 🎉
• ❌ “연결할 수 없음” → 아래 트러블슈팅 참고

4-2. “연결할 수 없음” 나오면?

당황하지 마세요! 대부분 시간이 더 필요한 경우입니다.

해결 방법:

1. 1-2분 더 기다리기 (Metabase 시작 중)
2. F5 (새로고침) 눌러보기
3. “COMPLETE” 메시지 확인:

   docker logs -f metabase | grep COMPLETE
   

4. 5분 이상 기다렸는데도 안 되면 → 트러블슈팅 섹션 참고

💡 용어 설명:

• localhost = “내 컴퓨터” (다른 사람은 접속 못 함)
• :3000 = 3000번 포트 (문 번호라고 생각하세요)
• 나중에 팀원과 공유하려면 다른 설정 필요 (나중에 배워요)

2.2 v0.52+ 중요 변경사항

# ⚠️ 주의사항
# v0.52부터 Docker 이미지는 Java 21 기반
# 볼륨 경로 변경: /metabase.db → /metabase-data

# 이전 버전에서 업그레이드하는 경우
docker run -d -p 3000:3000 \
  --name metabase \
  -v ~/metabase-data:/metabase-data \
  -e "MB_DB_FILE=/metabase-data/metabase.db" \
  metabase/metabase:v0.56.8

2.3 유용한 Docker 명령어

# 컨테이너 중지
docker stop metabase

# 컨테이너 시작
docker start metabase

# 컨테이너 재시작
docker restart metabase

# 컨테이너 삭제 (데이터는 볼륨에 보존됨)
docker rm -f metabase

# 로그 실시간 확인
docker logs -f metabase

# 컨테이너 내부 접속 (디버깅용)
docker exec -it metabase /bin/bash

# 리소스 사용량 확인
docker stats metabase

3. Docker Compose로 프로덕션 환경 구성

“회사에서 실제로 사용하려면 어떻게 해야 하나요?”

Docker 단독 설치는 테스트용으로는 좋지만, 실제 업무에 사용하려면 더 안정적인 환경이 필요합니다. 이럴 때 Docker Compose를 사용합니다!

왜 Docker Compose를 쓰나요?

• 안정성: 데이터베이스(PostgreSQL)를 따로 관리해요
• 편리함: 설정 파일 하나로 모든 걸 관리해요
• 백업: 데이터를 더 안전하게 보관할 수 있어요

“근데 설정이 복잡하지 않나요?”

아니요! 파일만 복사해서 붙여넣으면 됩니다. 차근차근 따라오세요.

3.1 PostgreSQL과 함께 구성

왜 PostgreSQL을 쓰나요?

Docker 단독 설치에서는 “H2”라는 간단한 데이터베이스를 사용합니다. 테스트용으로는 좋지만:

• ❌ 많은 사용자가 동시에 사용하면 느려져요
• ❌ 데이터가 많아지면 불안정해져요
• ❌ 백업이 어려워요

그래서 실제 업무에서는 “PostgreSQL”이라는 더 강력한 데이터베이스를 사용합니다:

• ✅ 많은 사용자도 OK
• ✅ 대용량 데이터도 OK
• ✅ 백업/복구 쉬움

프로덕션 환경에서는 H2 대신 PostgreSQL 사용을 강력히 권장합니다.

docker-compose.yml 작성

version: '3.9'

services:
  metabase:
    image: metabase/metabase:v0.56.8
    container_name: metabase
    hostname: metabase
    ports:
      - "3000:3000"
    environment:
      # 데이터베이스 설정
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabase
      MB_DB_PORT: 5432
      MB_DB_USER: metabase
      MB_DB_PASS: ${MB_DB_PASS:-mysecretpassword}  # 환경변수 또는 기본값
      MB_DB_HOST: postgres

      # v0.56 신규 기능
      MB_ENABLE_METABOT: "true"  # AI 기능 활성화
      MB_EMBEDDING_APP_ORIGIN: "*"  # 임베딩 허용 (프로덕션에서는 특정 도메인 지정)

      # 성능 최적화
      JAVA_OPTS: "-Xmx2g -Xms1g"  # JVM 메모리 설정

      # 보안 설정
      MB_PASSWORD_COMPLEXITY: strong  # 강력한 비밀번호 요구
      MB_PASSWORD_LENGTH: 10  # 최소 비밀번호 길이

    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./metabase-data:/metabase-data
    networks:
      - metabase-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  postgres:
    image: postgres:15-alpine  # 경량화된 PostgreSQL 15
    container_name: metabase_postgres
    hostname: postgres
    environment:
      POSTGRES_DB: metabase
      POSTGRES_USER: metabase
      POSTGRES_PASSWORD: ${MB_DB_PASS:-mysecretpassword}
      POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C"
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    networks:
      - metabase-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U metabase"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  metabase-network:
    driver: bridge

volumes:
  metabase-data:
  postgres-data:

.env 파일 작성

# .env 파일 생성 (보안을 위해 .gitignore에 추가)
cat > .env << 'EOF'
# Database Password
MB_DB_PASS=your_secure_password_here

# Metabase Settings
MB_SITE_URL=http://localhost:3000

# Email Settings (선택사항)
MB_EMAIL_SMTP_HOST=smtp.gmail.com
MB_EMAIL_SMTP_PORT=587
MB_EMAIL_SMTP_USERNAME=your-email@gmail.com
MB_EMAIL_SMTP_PASSWORD=your-app-password
MB_EMAIL_SMTP_SECURITY=tls
EOF

# .gitignore에 .env 추가
echo ".env" >> .gitignore

실행

# 1. 디렉토리 생성
mkdir -p metabase-production
cd metabase-production

# 2. docker-compose.yml과 .env 파일 작성 (위 내용 사용)

# 3. 실행
docker-compose up -d

# 4. 로그 확인
docker-compose logs -f

# 5. 상태 확인
docker-compose ps

# 출력 예시:
# Name              State    Ports
# metabase          Up       0.0.0.0:3000->3000/tcp
# metabase_postgres Up       5432/tcp

관리 명령어

# 중지
docker-compose stop

# 시작
docker-compose start

# 재시작
docker-compose restart

# 완전 삭제 (데이터 보존)
docker-compose down

# 완전 삭제 (데이터 포함)
docker-compose down -v

# 업그레이드
docker-compose pull
docker-compose up -d

# 백업
docker-compose exec postgres pg_dump -U metabase metabase > metabase_backup.sql

# 복구
docker-compose exec -T postgres psql -U metabase metabase < metabase_backup.sql

3.2 환경별 설정

개발 환경

# docker-compose.dev.yml
version: '3.9'
services:
  metabase:
    image: metabase/metabase:latest  # 최신 버전 사용
    ports:
      - "3000:3000"
    environment:
      MB_DB_TYPE: h2  # 개발은 H2로 빠르게
      MB_DEV_ADDITIONAL_DRIVER_MANIFEST_URL: "https://..."  # 커스텀 드라이버
    volumes:
      - ./metabase-dev-data:/metabase-data

# 실행
docker-compose -f docker-compose.dev.yml up -d

프로덕션 환경

# docker-compose.prod.yml
version: '3.9'
services:
  metabase:
    image: metabase/metabase:v0.56.8  # 고정 버전 사용
    ports:
      - "3000:3000"
    environment:
      MB_DB_TYPE: postgres
      # 외부 PostgreSQL 사용
      MB_DB_HOST: your-rds-endpoint.region.rds.amazonaws.com
      MB_DB_PORT: 5432
      MB_DB_DBNAME: metabase_prod
      MB_DB_USER: ${DB_USER}
      MB_DB_PASS: ${DB_PASS}

      # 보안 설정
      MB_SITE_URL: https://metabase.yourcompany.com
      MB_EMBEDDING_SECRET_KEY: ${EMBEDDING_SECRET}
      MB_ENCRYPTION_SECRET_KEY: ${ENCRYPTION_SECRET}

      # 성능 설정
      JAVA_OPTS: "-Xmx4g -Xms2g"
      MB_JETTY_MAX_THREADS: 100

    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

# 실행
docker-compose -f docker-compose.prod.yml up -d

4. JAR 파일로 설치

Docker를 사용하지 않는 환경에서 사용합니다.

4.1 사전 준비

# 1. Java 버전 확인 (21 이상 필요 - v0.53부터 필수)
java -version

# 출력 예시:
# openjdk version "21.0.1" 2023-10-17

# Java가 없거나 버전이 낮다면 설치
# macOS
brew install openjdk@21

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-21-jdk

# CentOS/RHEL
sudo yum install java-21-openjdk

4.2 설치 및 실행

# 1. Metabase JAR 다운로드 (v0.56.8 - 2025년 10월 최신)
wget https://downloads.metabase.com/v0.56.8/metabase.jar

# 또는 curl 사용
curl -o metabase.jar https://downloads.metabase.com/v0.56.8/metabase.jar

# 2. 다운로드 확인
ls -lh metabase.jar
# 출력: metabase.jar (약 300MB)

# 3. 실행
java -jar metabase.jar

# 4. 백그라운드 실행
nohup java -jar metabase.jar > metabase.log 2>&1 &

# 5. 프로세스 확인
ps aux | grep metabase

# 6. 로그 확인
tail -f metabase.log

4.3 고급 설정

# JVM 메모리 설정
export JAVA_OPTS="-Xmx4g -Xms2g"
java $JAVA_OPTS -jar metabase.jar

# 환경변수로 설정
export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabase
export MB_DB_PORT=5432
export MB_DB_USER=metabase
export MB_DB_PASS=mysecretpassword
export MB_DB_HOST=localhost

java -jar metabase.jar

# 포트 변경
export MB_JETTY_PORT=8080
java -jar metabase.jar

4.4 서비스 등록 (systemd)

프로덕션에서는 서비스로 등록하여 자동 시작되도록 설정합니다.

# /etc/systemd/system/metabase.service 생성
sudo tee /etc/systemd/system/metabase.service > /dev/null << 'EOF'
[Unit]
Description=Metabase Server
After=network.target

[Service]
Type=simple
User=metabase
WorkingDirectory=/opt/metabase
ExecStart=/usr/bin/java -Xmx2g -Xms1g -jar /opt/metabase/metabase.jar
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

Environment="MB_DB_TYPE=postgres"
Environment="MB_DB_DBNAME=metabase"
Environment="MB_DB_PORT=5432"
Environment="MB_DB_USER=metabase"
Environment="MB_DB_PASS=mysecretpassword"
Environment="MB_DB_HOST=localhost"

[Install]
WantedBy=multi-user.target
EOF

# 사용자 생성
sudo useradd -r -s /bin/false metabase

# 디렉토리 준비
sudo mkdir -p /opt/metabase
sudo mv metabase.jar /opt/metabase/
sudo chown -R metabase:metabase /opt/metabase

# 서비스 활성화 및 시작
sudo systemctl daemon-reload
sudo systemctl enable metabase
sudo systemctl start metabase

# 상태 확인
sudo systemctl status metabase

# 로그 확인
sudo journalctl -u metabase -f

5. 클라우드 환경 배포

5.1 Heroku 배포

# 1. Heroku CLI 설치 후 로그인
brew install heroku/brew/heroku  # macOS
heroku login

# 2. 앱 생성
heroku create my-metabase-app

# 3. PostgreSQL 애드온 추가
heroku addons:create heroku-postgresql:mini

# 4. 환경변수 설정
heroku config:set MB_DB_TYPE=postgres
heroku config:set MB_DB_CONNECTION_URI=$(heroku config:get DATABASE_URL)
heroku config:set JAVA_OPTS="-Xmx512m -Xms256m"

# 5. Buildpack 설정
heroku buildpacks:set heroku/jvm

# 6. 배포
git clone https://github.com/metabase/metabase-deploy.git
cd metabase-deploy
git push heroku master

# 7. 앱 열기
heroku open

# 8. 로그 확인
heroku logs --tail

5.2 AWS EC2 배포

# EC2 인스턴스에서 실행

# 1. 시스템 업데이트
sudo yum update -y

# 2. Docker 설치
sudo yum install docker -y
sudo service docker start
sudo usermod -a -G docker ec2-user

# 3. Metabase 실행
docker run -d -p 80:3000 \
  --name metabase \
  --restart always \
  -v /home/ec2-user/metabase-data:/metabase-data \
  metabase/metabase:v0.56.8

# 4. 보안 그룹 설정
# AWS 콘솔에서 인바운드 규칙 추가: HTTP (80)

# 5. 접속
# http://your-ec2-public-ip

5.3 AWS ECS (Fargate) 배포

// task-definition.json
{
  "family": "metabase",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "metabase",
      "image": "metabase/metabase:v0.56.8",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "MB_DB_TYPE", "value": "postgres"},
        {"name": "MB_DB_HOST", "value": "your-rds-endpoint.region.rds.amazonaws.com"},
        {"name": "MB_DB_DBNAME", "value": "metabase"},
        {"name": "MB_DB_USER", "value": "metabase"}
      ],
      "secrets": [
        {
          "name": "MB_DB_PASS",
          "valueFrom": "arn:aws:secretsmanager:region:account-id:secret:metabase-db-pass"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/metabase",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

# AWS CLI로 배포
aws ecs register-task-definition --cli-input-json file://task-definition.json

aws ecs create-service \
  --cluster my-cluster \
  --service-name metabase \
  --task-definition metabase \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"

6. Kubernetes 배포

엔터프라이즈 환경을 위한 고가용성 구성입니다.

6.1 Helm Chart 사용 (추천)

# 1. Helm 설치
brew install helm  # macOS
# 또는 https://helm.sh/docs/intro/install/

# 2. Metabase Helm Chart 추가
helm repo add metabase https://metabase.github.io/metabase-helm-chart
helm repo update

# 3. values.yaml 작성
cat > metabase-values.yaml << 'EOF'
image:
  repository: metabase/metabase
  tag: v0.56.8

replicaCount: 2  # 고가용성을 위한 복제본

service:
  type: LoadBalancer
  port: 80

database:
  type: postgres
  host: postgres-service.default.svc.cluster.local
  port: 5432
  dbname: metabase
  username: metabase
  existingSecret: metabase-db-secret
  existingSecretPasswordKey: password

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 500m
    memory: 2Gi

ingress:
  enabled: true
  hosts:
    - host: metabase.example.com
      paths:
        - path: /
          pathType: Prefix

persistence:
  enabled: true
  size: 10Gi
  storageClass: gp3

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 70

env:
  - name: MB_ENABLE_METABOT
    value: "true"
  - name: JAVA_OPTS
    value: "-Xmx3g -Xms1g"
EOF

# 4. Secret 생성
kubectl create secret generic metabase-db-secret \
  --from-literal=password=your-secure-password

# 5. 배포
helm install metabase metabase/metabase -f metabase-values.yaml

# 6. 상태 확인
kubectl get pods -l app.kubernetes.io/name=metabase
kubectl get svc metabase

# 7. 접속
kubectl port-forward svc/metabase 3000:80

6.2 수동 배포 (YAML)

metabase-k8s.yaml (펼치기/접기)

apiVersion: v1
kind: Namespace
metadata:
  name: metabase

excerpt_separator: "<!--more-->"
---
apiVersion: v1
kind: Secret
metadata:
  name: metabase-db-secret
  namespace: metabase
type: Opaque
stringData:
  password: your-secure-password

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: metabase-pvc
  namespace: metabase
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: gp3

excerpt_separator: "<!--more-->"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: metabase
  namespace: metabase
spec:
  replicas: 2
  selector:
    matchLabels:
      app: metabase
  template:
    metadata:
      labels:
        app: metabase
    spec:
      containers:
      - name: metabase
        image: metabase/metabase:v0.56.8
        ports:
        - containerPort: 3000
          name: http
        env:
        - name: MB_DB_TYPE
          value: "postgres"
        - name: MB_DB_HOST
          value: "postgres-service"
        - name: MB_DB_PORT
          value: "5432"
        - name: MB_DB_DBNAME
          value: "metabase"
        - name: MB_DB_USER
          value: "metabase"
        - name: MB_DB_PASS
          valueFrom:
            secretKeyRef:
              name: metabase-db-secret
              key: password
        - name: JAVA_OPTS
          value: "-Xmx3g -Xms1g"
        - name: MB_ENABLE_METABOT
          value: "true"
        volumeMounts:
        - name: metabase-data
          mountPath: /metabase-data
        resources:
          limits:
            cpu: 2000m
            memory: 4Gi
          requests:
            cpu: 500m
            memory: 2Gi
        livenessProbe:
          httpGet:
            path: /api/health
            port: 3000
          initialDelaySeconds: 120
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /api/health
            port: 3000
          initialDelaySeconds: 60
          periodSeconds: 10
      volumes:
      - name: metabase-data
        persistentVolumeClaim:
          claimName: metabase-pvc

apiVersion: v1
kind: Service
metadata:
  name: metabase
  namespace: metabase
spec:
  type: LoadBalancer
  selector:
    app: metabase
  ports:
    - port: 80
      targetPort: 3000
      protocol: TCP

excerpt_separator: "<!--more-->"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: metabase
  namespace: metabase
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: metabase
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

# 배포
kubectl apply -f metabase-k8s.yaml

# 상태 확인
kubectl get all -n metabase

# 로그 확인
kubectl logs -n metabase -l app=metabase -f

# 스케일링 테스트
kubectl scale deployment metabase -n metabase --replicas=3

5. 초기 설정하기 (네 번째 단계)

⏱️ 예상 시간: 2-3분

드디어 Metabase를 사용할 차례입니다!

브라우저에서 http://localhost:3000에 접속하면 설정 화면이 나옵니다.

5-1. Step 1: 언어 선택

화면에 나오는 첫 질문: “What’s your preferred language?”

• 한국어 선택 (또는 English)
• 나중에 바꿀 수 있으니 걱정하지 마세요!

5-2. Step 2: 관리자 계정 만들기

“Let’s get started” 화면에서 정보 입력:

이름: 홍길동 (본인 이름)
이메일: hong@company.com (로그인 ID로 사용됩니다!)
비밀번호: ******** (10자 이상, 복잡하게!)
회사/조직: 우리 회사 (아무거나 OK)

💡 초보자 팁:

• 이메일: 나중에 로그인할 때 사용해요 (잊지 마세요!)
• 비밀번호: 테스트라면 간단해도 되지만, 까먹지 마세요!
• 회사 이름: 그냥 “테스트” 라고 써도 돼요

“Next” 클릭!

5-3. Step 3: 사용 목적 (건너뛰어도 됨)

“How will you use Metabase?” 라고 물어봅니다

• 아무거나 선택하거나
• “Skip” 클릭해도 됩니다
• 통계 수집용이니 걱정하지 마세요 (개인정보 안 보냄)

5-4. Step 4: 데이터베이스 연결 (나중에 할 거예요)

“Add your data” 화면:

💡 초보자 팁: “I’ll add my data later” (나중에 추가하기) 선택하세요!

왜냐면:

• 아직 연결할 데이터베이스가 없을 수 있어요
• Metabase에는 샘플 데이터가 있어서 바로 연습 가능해요
• 다음 글에서 자세히 배울 거예요!

“Take me to Metabase” 클릭!

5-5. 🎉 성공! 첫 화면!

축하합니다! Metabase 메인 화면이 나타났습니다!

보이는 것들:

• 왼쪽: 메뉴 (Home, Questions, Dashboards 등)
• 중간: “Our analytics” 섹션
• 오른쪽 위: “+ New” 버튼 (여기서 차트 만들어요!)

샘플 데이터베이스도 자동으로 준비되어 있습니다:

• Orders (주문 데이터)
• Products (제품)
• People (사람들)
• Reviews (리뷰)

다음 글에서 이 샘플 데이터로 첫 차트를 만들어볼 거예요! 🎨

7.3 이메일 설정 (선택)

자동 리포트 발송을 위한 SMTP 설정:

Gmail 사용

Admin > Settings > Email

SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Security: TLS
SMTP Username: your-email@gmail.com
SMTP Password: app-specific-password  # Google 앱 비밀번호 생성 필요
From Address: your-email@gmail.com

Google 앱 비밀번호 생성:

1. Google 계정 > 보안 > 2단계 인증 활성화
2. 앱 비밀번호 > 메일 > 기타 > “Metabase” 입력
3. 생성된 16자리 비밀번호 복사

AWS SES 사용

# 환경변수 설정
export MB_EMAIL_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
export MB_EMAIL_SMTP_PORT=587
export MB_EMAIL_SMTP_USERNAME=your-ses-smtp-username
export MB_EMAIL_SMTP_PASSWORD=your-ses-smtp-password
export MB_EMAIL_SMTP_SECURITY=tls

테스트

Admin > Settings > Email > Send test email

받은 메일함에서 테스트 이메일 확인

7.4 기본 설정 최적화

성능 설정

Admin > Settings > Caching

Caching: Enabled
Cache duration: 24 hours (기본값)
Preemptive caching: Enabled (v0.53+)
  → 자주 사용하는 파라미터 조합 자동 캐시

보안 설정

Admin > Settings > Security

Password complexity: Strong
Minimum password length: 10
Session timeout: 72 hours (기본값)

Advanced:
Enable embedding: Yes (필요시)
Embedding secret key: (자동 생성됨)

일반 설정

Admin > Settings > General

Site Name: Your Company BI
Site URL: https://metabase.yourcompany.com (프로덕션)
Timezone: Asia/Seoul
Language: 한국어

Advanced:
Report timezone: Asia/Seoul
First day of week: Monday

8. 트러블슈팅 (문제 해결)

“오류가 났어요! 어떡하죠?”

걱정하지 마세요! 대부분의 문제는 쉽게 해결할 수 있습니다. 아래에서 여러분의 문제와 비슷한 걸 찾아보세요.

8.1 자주 발생하는 문제들

문제 1: “포트를 이미 사용 중입니다” 오류

어떤 오류인가요?

Error: bind: address already in use

무슨 뜻인가요?

• 3000번 포트를 이미 다른 프로그램이 사용하고 있어요
• 예를 들어 이미 Metabase가 실행 중이거나, 다른 웹서버가 3000번 포트를 쓰고 있을 수 있어요

해결 방법 1: 다른 포트 사용하기 (초보자 추천)

# 8080번 포트로 실행
docker run -d -p 8080:3000 \
  --name metabase \
  -v ~/metabase-data:/metabase-data \
  metabase/metabase:v0.56.8

# 그럼 이제 http://localhost:8080 으로 접속하세요

해결 방법 2: 기존 프로그램 종료하기

# macOS/Linux
lsof -i :3000  # 3000번 포트를 쓰는 프로그램 찾기
kill -9 <PID>  # 그 프로그램 종료 (PID는 위에서 나온 숫자)

# Windows (PowerShell)
netstat -ano | findstr :3000
taskkill /PID <PID> /F

문제 2: “메모리가 부족합니다” 오류

어떤 오류인가요?

OutOfMemoryError: Java heap space

무슨 뜻인가요?

• Metabase가 사용할 수 있는 메모리가 부족해요
• 데이터가 많거나 복잡한 쿼리를 실행하면 발생할 수 있어요

해결 방법: 메모리 늘려주기

# 기존 컨테이너 삭제
docker rm -f metabase

# 메모리를 더 많이 할당해서 다시 실행 (4GB 할당)
docker run -d -p 3000:3000 \
  --name metabase \
  --memory="4g" \
  -e "JAVA_OPTS=-Xmx3g -Xms1g" \
  -v ~/metabase-data:/metabase-data \
  metabase/metabase:v0.56.8

💡 초보자 팁:

• --memory="4g": Docker에게 최대 4GB까지 사용하라고 알려줘요
• -Xmx3g: Java에게 최대 3GB까지 사용하라고 알려줘요
• 내 컴퓨터 RAM이 8GB 이상이면 위 설정이 안전해요

문제 3: 권한 문제

# 증상
Permission denied: /metabase-data

# 해결 방법
# 볼륨 권한 설정
sudo chown -R 1000:1000 ~/metabase-data

# Docker Compose의 경우
services:
  metabase:
    user: "1000:1000"
    volumes:
      - ./metabase-data:/metabase-data

문제 4: “시작이 너무 느려요!”

어떤 증상인가요?

• Metabase가 시작하는데 5분 이상 걸려요
• 브라우저에서 “연결 중” 메시지만 계속 나와요

무슨 뜻인가요?

• 처음 시작할 때는 시간이 좀 걸려요 (정상입니다!)
• 데이터베이스를 준비하고 설정을 초기화하는 중이에요

해결 방법: 참고 기다리기

# 로그를 보면서 진행 상황 확인
docker logs -f metabase

# 이런 메시지들이 보이면 정상적으로 진행 중이에요:
# "Starting Metabase..."
# "Setting up database..."
# "Loading drivers..."
# "Metabase Initialization COMPLETE" ← 이게 나오면 완료!

💡 초보자 팁:

• 첫 시작은 2-5분 정도 걸립니다 (정상!)
• 로그에 ERROR가 아니면 기다리면 됩니다
• 10분 넘게 걸리면 뭔가 문제가 있는 거예요 (컴퓨터 재부팅 후 다시 시도)

문제 5: “데이터베이스에 연결할 수 없습니다”

어떤 오류인가요?

Failed to connect to database

무슨 뜻인가요?

• Metabase가 데이터를 저장하는 데이터베이스에 접속하지 못해요
• 주로 Docker Compose를 사용할 때 발생해요

해결 방법 1: 네트워크 확인

# Docker 네트워크가 제대로 만들어졌는지 확인
docker network ls

# metabase-network가 있어야 해요

해결 방법 2: PostgreSQL이 잘 실행되는지 확인

# PostgreSQL 컨테이너 상태 확인
docker ps | grep postgres

# STATUS가 "Up"이면 정상이에요

해결 방법 3: 호스트명 확인 (중요!)

# docker-compose.yml에서 확인
environment:
  MB_DB_HOST: postgres  # ✅ 이렇게 써야 해요 (서비스 이름)
  # MB_DB_HOST: localhost  # ❌ 이건 안 돼요!

💡 초보자 팁:

• Docker 안에서는 localhost가 “자기 자신”을 의미해요
• 다른 컨테이너에 접속하려면 서비스 이름(postgres)을 써야 해요
• 이게 Docker 네트워킹의 핵심입니다!

8.2 로그 분석

# Docker
docker logs metabase --tail 100

# Docker Compose
docker-compose logs metabase --tail 100 -f

# systemd
sudo journalctl -u metabase -n 100 -f

# 주요 로그 패턴
[INFO] Starting Metabase  # 시작
[INFO] Database setup  # DB 초기화
[INFO] Metabase Initialization COMPLETE  # 준비 완료
[ERROR] Failed to connect  # 연결 실패

8.3 성능 진단

# 컨테이너 리소스 사용량
docker stats metabase

# 출력 예시:
# NAME       CPU %   MEM USAGE / LIMIT   MEM %
# metabase   25.4%   1.5GiB / 4GiB       37.5%

# JVM 메모리 확인
docker exec metabase java -XX:+PrintFlagsFinal -version | grep -i heapsize

# 데이터베이스 크기 확인
docker exec metabase_postgres psql -U metabase -c "SELECT pg_size_pretty(pg_database_size('metabase'));"

8.4 백업 및 복구

H2 데이터베이스 백업

# 1. Metabase 중지
docker stop metabase

# 2. 데이터 백업
tar -czf metabase-backup-$(date +%Y%m%d).tar.gz ~/metabase-data

# 3. 복구 시
tar -xzf metabase-backup-20251010.tar.gz -C ~/

# 4. Metabase 시작
docker start metabase

PostgreSQL 백업

# 백업
docker-compose exec postgres pg_dump -U metabase metabase | gzip > metabase-backup-$(date +%Y%m%d).sql.gz

# 복구
gunzip < metabase-backup-20251010.sql.gz | docker-compose exec -T postgres psql -U metabase metabase

# 자동 백업 (cron)
# crontab -e
0 2 * * * docker-compose exec postgres pg_dump -U metabase metabase | gzip > /backup/metabase-$(date +\%Y\%m\%d).sql.gz

9. 초보자를 위한 핵심 정리

“이 글에서 꼭 기억해야 할 것은?”

설치 방법 요약

1. 가장 쉬운 방법 (초보자)

docker run -d -p 3000:3000 --name metabase metabase/metabase:v0.56.8

→ 5분이면 끝! http://localhost:3000 접속

2. 회사에서 쓸 방법 (프로덕션)

• Docker Compose + PostgreSQL 사용
• 더 안정적이고 관리하기 좋음
• 백업과 복구가 쉬움

3. Docker 못 쓸 때

• JAR 파일로 설치
• Java만 있으면 됨

자주 쓰는 명령어

# 상태 확인
docker ps

# 로그 보기
docker logs -f metabase

# 중지
docker stop metabase

# 시작
docker start metabase

# 재시작
docker restart metabase

문제가 생기면?

1. 로그를 먼저 확인하세요: docker logs metabase
2. 이 글의 “8. 트러블슈팅” 섹션을 보세요
3. 그래도 안 되면 컨테이너를 삭제하고 다시 시작하세요:

   docker rm -f metabase
   # 그리고 설치 명령어 다시 실행
   

10. 실습 과제

“어떤 걸 해봐야 하나요?”

필수 과제 (꼭 해보세요!)

1. Docker로 설치하기

• Metabase 컨테이너 실행
• 브라우저로 http://localhost:3000 접속 확인
• 관리자 계정 생성
• 샘플 데이터베이스 둘러보기

2. 기본 명령어 익히기

• docker ps로 상태 확인
• docker logs로 로그 보기
• docker stop과 docker start로 중지/시작

선택 과제 (여유 있으면)

3. Docker Compose 구성

• PostgreSQL과 함께 구성
• 데이터가 유지되는지 확인 (재시작 테스트)
• 백업 스크립트 작성

4. 고급 설정

• 이메일 설정 (선택사항)
• 첫 Question 만들어보기

6. 마무리 & 다음 단계

🎉 축하합니다! Metabase 설치 완료!

오늘 한 일을 정리하면:

✅ 5분 만에 Metabase 설치 완료!

• Docker 설치 (또는 확인)
• 명령어 하나로 Metabase 실행
• 브라우저로 접속 성공

✅ 계정 만들고 로그인까지!

• 관리자 계정 생성
• Metabase 메인 화면 진입
• 샘플 데이터 준비 완료

“생각보다 쉬웠어요!”

맞죠? 복사 붙여넣기만 해도 90%는 성공합니다!

---

📝 유용한 명령어 (북마크하세요!)

# Metabase 상태 확인
docker ps

# Metabase 로그 보기
docker logs -f metabase

# Metabase 중지
docker stop metabase

# Metabase 시작
docker start metabase

# Metabase 재시작
docker restart metabase

# Metabase 완전 삭제 (데이터는 유지)
docker rm -f metabase

---

🚀 다음 단계

지금 바로 해보세요:

1. 샘플 데이터 둘러보기 (Orders, Products 테이블 클릭해보세요!)
2. ”+ New” 버튼 눌러보기 (아직 만들지는 마세요, 구경만!)
3. 다음 글 읽기 → 첫 차트 만들기!

다음 글 예고:

• 📊 클릭만으로 첫 차트 만들기
• 🎨 예쁜 대시보드 만들기
• 💡 실전 예제로 배우기

“오류가 났어요…“ → 이 글의 “8. 트러블슈팅” 섹션을 보세요. 대부분의 문제 해결법이 있습니다!

---

📚 고급 기능 (나중에 배우세요)

💡 초보자는 건너뛰세요! 아래 내용은 회사에서 실제로 운영할 때 필요한 고급 기능입니다. 지금은 몰라도 되고, 나중에 필요할 때 다시 보세요!

클릭: Docker Compose로 프로덕션 환경 구성 (고급)

이 글의 “3. Docker Compose로 프로덕션 환경 구성” 섹션을 참고하세요.

• PostgreSQL과 함께 안정적으로 구성
• 자동 백업 설정
• 복구 방법

클릭: 다른 설치 방법들 (JAR, Kubernetes 등)

이 글의 다음 섹션들을 참고하세요:

• 1. JAR 파일로 설치
• 1. 클라우드 환경 배포
• 1. Kubernetes 배포

다음 글에서 뵙겠습니다! 이제 진짜 재미있는 부분입니다 - 데이터 분석! 🎨

다음 시간 예고

[이제와서 시작하는 Metabase 마스터하기 #3] 첫 데이터베이스 연결

다음 글에서 배울 내용:

• 🔌 PostgreSQL, MySQL 연결하는 법
• 📊 데이터 구조 이해하기
• 🔗 테이블 관계 설정하기
• 📝 첫 번째 간단한 분석 해보기

“데이터베이스가 없는데요?”

• 걱정하지 마세요! 샘플 데이터로도 충분히 연습할 수 있어요
• 테스트용 데이터베이스 만드는 방법도 알려드릴게요

excerpt_separator: “”

📚 시리즈 전체 목차

🚀 기초편 (1-5화)

1. Metabase 소개와 핵심 개념
2. [현재 글] 설치와 초기 설정
3. 첫 데이터베이스 연결 (다음 글)
4. Question 만들기
5. Dashboard 구성하기

💪 활용편 (6-10화)

1. 필터와 파라미터
2. SQL 네이티브 쿼리
3. 데이터 모델링
4. 자동화와 알림
5. 권한과 보안

🎯 고급편 (11-16화)

1. 임베딩과 공유
2. 성능 최적화
3. 멀티 데이터소스
4. 커스터마이징
5. 운영과 모니터링
6. 실전 프로젝트

이 시리즈가 도움이 되셨나요?

• 다음 글에서는 실제 데이터베이스를 연결하고 데이터를 탐색해보겠습니다
• 궁금한 점이나 어려운 부분이 있다면 댓글로 알려주세요!