13년차의 서버실

서버, 인프라, 홈랩 기술 블로그

[태그:] Pi-hole

  • [HomeLabs] 홈랩 네트워크 광고 차단: Pi-hole vs AdGuard Home 비교 및 구축 가이드

    광고 때문에 인터넷 쓰기가 불편하셨던 적 있으신가요?

    솔직히 말씀드리면, 저도 한동안은 브라우저 확장 프로그램 하나로 버텼거든요. uBlock Origin 설치해두고 ‘이 정도면 됐지’ 싶었는데… 어느 날 스마트TV에서 광고가 막 뜨는 거 보고 현타가 왔습니다. 앱마다 확장 프로그램을 설치할 수도 없고, IoT 기기들은 어떻게 할 방법이 없더라고요.

    그때부터 네트워크 레벨 광고 차단(Network-level Ad Blocking)을 본격적으로 알아보기 시작했습니다. DNS 필터링 방식이라서 공유기에 연결된 모든 기기에 한 번에 적용되거든요. 홈랩을 운영하는 입장에서는 이게 진짜 맞는 방향이었어요.

    그리고 이 분야에서 가장 많이 언급되는 두 가지가 바로 Pi-hole과 AdGuard Home입니다. 둘 다 직접 써봤는데, 생각보다 차이가 꽤 있더라고요. 오늘은 홈랩 광고 차단 솔루션으로 어떤 걸 선택할지 고민하시는 분들을 위해 제 경험을 정리해봤습니다.

    ▲ DNS 필터링 기반 홈랩 광고 차단 구조 — 모든 기기의 DNS 요청이 Pi-hole 또는 AdGuard Home을 거쳐 광고 도메인을 차단합니다.

    DNS 필터링이 뭔지 먼저 짚고 넘어가겠습니다

    쉽게 말해서, 인터넷 주소록(DNS)을 중간에서 가로채는 방식이에요. 브라우저가 ads.example.com의 IP 주소를 물어볼 때, 일반 DNS 서버 대신 Pi-hole이나 AdGuard Home이 먼저 받아서 “그런 주소 없어요”라고 답해버리는 거거든요.

    그러면 광고 서버로 연결 자체가 안 되니까 광고가 뜨질 않죠. 브라우저 확장 프로그램과 다른 점은 네트워크에 연결된 모든 기기에 자동으로 적용된다는 겁니다. 스마트폰, TV, 게임기, 심지어 냉장고까지요.

    • 장점: 기기별 설정 불필요, 앱 내 광고도 일부 차단 가능, 중앙 집중 관리
    • 단점: DNS 우회 광고는 차단 불가, 잘못 설정하면 정상 사이트도 막힘, 서버 운영 필요

    Pi-hole vs AdGuard Home — 뭐가 다른가요?

    처음에 저도 “둘 다 DNS 필터링이면 거기서 거기 아닌가?” 싶었는데, 실제로 써보니 철학 자체가 좀 달랐습니다.

    항목 Pi-hole AdGuard Home
    출시 연도 2014년 2019년
    개발 언어 Bash / PHP Go / React
    설치 방법 쉘 스크립트, Docker 바이너리 실행, Docker
    DNS-over-HTTPS(DoH) 지원 별도 설정 필요 (cloudflared 등) 기본 내장
    DNS-over-TLS(DoT) 지원 별도 설정 필요 기본 내장
    DHCP 서버 기능 지원 지원
    클라이언트별 필터링 그룹 기반 (v5.0+) 클라이언트별 세밀 설정
    UI 직관성 익숙해지면 편함 처음부터 쓰기 편함
    커뮤니티 크기 매우 큼 빠르게 성장 중
    라이선스 EUPL (오픈소스) GPL-3.0 (오픈소스)

    제가 느낀 핵심 차이를 한 줄로 정리하면 이렇습니다. Pi-hole은 역사가 길고 커뮤니티가 탄탄하며, AdGuard Home은 최신 기능을 기본 제공하면서 설정이 더 직관적이에요.

    Pi-hole 구축 가이드 (Docker 기준)

    저는 홈랩 서버에서 Docker로 돌리는 방식을 씁니다. Raspberry Pi에 직접 설치하는 방법도 있지만, 관리 편의성을 생각하면 Docker가 훨씬 낫더라고요.

    1단계: docker-compose.yml 작성

    version: "3"
    
    services:
      pihole:
        container_name: pihole
        image: pihole/pihole:latest
        ports:
          - "53:53/tcp"
          - "53:53/udp"
          - "80:80/tcp"
        environment:
          TZ: 'Asia/Seoul'
          WEBPASSWORD: 'your_secure_password'  # 반드시 변경하세요!
        volumes:
          - './etc-pihole:/etc/pihole'
          - './etc-dnsmasq.d:/etc/dnsmasq.d'
        restart: unless-stopped
        cap_add:
          - NET_ADMIN
    

    2단계: 실행

    # 컨테이너 시작
    docker compose up -d
    
    # 로그 확인
    docker logs pihole
    
    # 정상 실행 여부 확인
    docker ps | grep pihole
    

    3단계: 공유기 DNS 설정 변경

    여기가 핵심이에요. 공유기 관리 페이지(보통 192.168.0.1 또는 192.168.1.1)에 접속해서 DNS 서버 주소를 Pi-hole이 실행 중인 서버의 IP로 변경해주면 됩니다. 이렇게 하면 공유기에 연결된 모든 기기가 Pi-hole을 DNS로 사용하게 돼요.

    # DNS 설정이 제대로 됐는지 테스트
    nslookup google.com 192.168.x.x  # Pi-hole 서버 IP 입력
    
    # 광고 도메인 차단 확인
    nslookup doubleclick.net 192.168.x.x
    # 0.0.0.0 또는 NXDOMAIN이 나오면 정상
    

    4단계: 블록리스트 추가

    기본 블록리스트도 나쁘지 않지만, 추가해주면 더 좋습니다. Pi-hole 웹 UI에서 Adlists 메뉴로 가서 아래 리스트들을 추가해보세요.

    • https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts — 종합 광고/악성 도메인 차단
    • https://adaway.org/hosts.txt — 모바일 광고 특화
    • https://raw.githubusercontent.com/anudeepND/blacklist/master/adservers.txt — 광고 서버 특화

    추가 후 Tools → Update Gravity를 실행하면 적용됩니다.

    AdGuard Home 구축 가이드 (Docker 기준)

    AdGuard Home은 솔직히 Pi-hole보다 초기 설정이 더 쉬웠어요. DoH/DoT 같은 기능을 별도 설정 없이 바로 쓸 수 있다는 게 특히 마음에 들었습니다.

    1단계: docker-compose.yml 작성

    version: "3"
    
    services:
      adguardhome:
        container_name: adguardhome
        image: adguard/adguardhome:latest
        ports:
          - "53:53/tcp"
          - "53:53/udp"
          - "3000:3000/tcp"  # 초기 설정 웹 UI
          - "80:80/tcp"      # 설정 완료 후 웹 UI
          - "443:443/tcp"    # HTTPS (선택)
        volumes:
          - './adguard/work:/opt/adguardhome/work'
          - './adguard/conf:/opt/adguardhome/conf'
        restart: unless-stopped
    

    2단계: 초기 설정 마법사 실행

    # 컨테이너 시작
    docker compose up -d
    
    # 브라우저에서 초기 설정 접속
    # http://서버IP:3000 으로 접속
    # 마법사 따라가면 5분 안에 완료됩니다
    

    3단계: DNS-over-HTTPS 업스트림 설정

    AdGuard Home의 진짜 강점이 여기서 나옵니다. Settings → DNS Settings → Upstream DNS servers에서 아래처럼 입력하면 돼요.

    # Cloudflare DoH
    https://cloudflare-dns.com/dns-query
    
    # Google DoH
    https://dns.google/dns-query
    
    # Quad9 DoH (악성 도메인 차단 포함)
    https://dns.quad9.net/dns-query
    

    이렇게 하면 Pi-hole처럼 별도로 cloudflared 같은 걸 설치할 필요가 없어요. 처음 설정할 때 이 부분에서 “오, 이게 되네?” 싶었습니다 ㅎㅎ

    ▲ AdGuard Home 웹 UI — DNS-over-HTTPS 업스트림 설정과 필터링 규칙을 직관적인 인터페이스에서 관리할 수 있습니다.

    4단계: 필터링 목록 추가

    Filters → DNS blocklists → Add blocklist에서 추가합니다. AdGuard Home은 기본으로 AdGuard DNS filter가 포함되어 있어서 별도 추가 없이도 바로 쓸 수 있어요.

    • AdGuard DNS filter (기본 포함)
    • EasyList (광고 특화)
    • EasyPrivacy (추적 특화)
    • Malware Domain List (악성 도메인)

    ⚠️ 삽질 경험 — 이것만 조심하세요

    실제로 구축하면서 제가 겪은 문제들입니다. 미리 알면 시간 많이 아낄 수 있어요.

    포트 53 충돌 문제 (Ubuntu 기준)

    Ubuntu 18.04 이상에서는 systemd-resolved가 이미 53번 포트를 쓰고 있어서 컨테이너가 뜨질 않더라고요. 처음에 이 오류 보고 한참 헤맸습니다.

    # 현재 53 포트 사용 확인
    sudo lsof -i :53
    
    # systemd-resolved의 stub listener 비활성화
    sudo nano /etc/systemd/resolved.conf
    # DNSStubListener=no 로 변경
    
    # 재시작
    sudo systemctl restart systemd-resolved
    
    # /etc/resolv.conf 심볼릭 링크 재설정
    sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
    

    정상 사이트가 막히는 경우

    가끔 은행 사이트나 업무 사이트가 갑자기 안 열리는 경우가 있는데, 대부분 블록리스트가 너무 공격적으로 잡아버리는 경우예요. Pi-hole이든 AdGuard Home이든 Whitelist(허용 목록)에 해당 도메인을 추가해주면 해결됩니다.

    # Pi-hole CLI로 화이트리스트 추가
    pihole -w example.com
    
    # 또는 웹 UI에서 Whitelist 메뉴 활용
    

    DNS 캐시 문제

    설정을 바꿨는데 적용이 안 되는 것 같을 때는 클라이언트 기기의 DNS 캐시를 지워줘야 해요.

    # Windows
    ipconfig /flushdns
    
    # macOS
    sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
    
    # Linux
    sudo systemd-resolve --flush-caches
    

    구축 결과 확인 — 이렇게 달라졌어요

    설정 완료 후 며칠 사용해보면 대시보드에서 통계가 쌓이기 시작합니다. 저는 처음에 결과 보고 좀 놀랐거든요. 전체 DNS 요청 중 광고/추적 도메인이 차지하는 비율이 생각보다 훨씬 높았어요.

    ▲ DNS 필터링 대시보드 통계 — 전체 쿼리 중 차단된 비율과 주요 차단 도메인을 실시간으로 확인할 수 있습니다.

    확인 방법은 간단합니다. 아래 사이트에 접속해보세요.

    # 광고 차단 테스트 사이트
    # https://d3ward.github.io/toolz/adblock.html
    # 위 사이트에서 차단율을 확인할 수 있습니다
    
    # DNS 응답 직접 확인
    nslookup pagead2.googlesyndication.com
    # 0.0.0.0 또는 NXDOMAIN이 나오면 정상 차단 중
    

    🎉 정상적으로 동작한다면 유튜브 이외의 대부분 사이트에서 광고가 사라진 걸 느끼실 수 있어요. (유튜브 광고는 같은 도메인을 쓰기 때문에 DNS 필터링으로는 차단이 어렵습니다. 이 부분은 솔직하게 말씀드리는 게 맞는 것 같아요.)

    어떤 걸 선택해야 할까요? — 제 추천

    결론부터 말씀드리면, 처음 시작하시는 분께는 AdGuard Home을 추천드립니다. 이유는 단순해요.

    • ✅ 초기 설정 마법사가 있어서 진입 장벽이 낮음
    • ✅ DoH/DoT를 별도 설정 없이 바로 사용 가능
    • ✅ 클라이언트별 필터링 설정이 직관적
    • ✅ 단일 바이너리라 관리가 단순함

    반면 Pi-hole이 더 나은 경우도 있습니다.

    • ✅ 커뮤니티가 워낙 크다 보니 문제 발생 시 레퍼런스가 훨씬 많음
    • ✅ Gravity 데이터베이스 방식이 대용량 블록리스트 처리에 효율적
    • ✅ 오래된 Raspberry Pi에서도 가볍게 돌아감
    • ✅ 이미 Pi-hole 사용 경험이 있다면 굳이 바꿀 필요 없음

    💡 팁: 두 개를 동시에 운영하면서 하나를 백업 DNS로 쓰는 방법도 있어요. 공유기 설정에서 1차 DNS는 AdGuard Home, 2차 DNS는 Pi-hole으로 설정하면 한 쪽이 다운되더라도 인터넷이 끊기지 않습니다.

    ▲ Pi-hole vs AdGuard Home 선택 가이드 — 사용 목적과 기술 수준에 따른 추천 기준을 정리했습니다.

    마무리 — 한 번 설정해두면 진짜 편합니다

    처음 구축할 때는 포트 충돌이니 DNS 설정이니 좀 헤매긴 했는데, 한번 돌아가기 시작하면 진짜 신경 쓸 게 없어요. 그냥 알아서 다 막아주거든요.

    제가 홈랩에서 이것저것 실험해보면서 느낀 건데, 네트워크 레벨 광고 차단은 홈랩 입문자가 처음 도전하기에 딱 좋은 프로젝트예요. 결과가 눈에 보이고, 실생활에 바로 도움이 되고, 배우는 것도 많거든요. DNS가 어떻게 동작하는지 자연스럽게 익히게 되는 부수 효과도 있고요.

    다음 단계로는 Unbound를 Recursive DNS Resolver(재귀 DNS 리졸버)로 연결해서 외부 DNS 의존도를 완전히 없애는 방법도 있는데, 이건 다음 글에서 다뤄볼게요. 관심 있으신 분들은 기대해 주세요.

    혹시 구축하다가 막히는 부분 있으시면 댓글로 남겨주세요. 제가 겪은 삽질이 더 있으면 추가로 공유해드리겠습니다 😄

    자주 묻는 질문 (FAQ)

    Q. Raspberry Pi 없이도 구축할 수 있나요?

    네, 가능합니다. 집에 항상 켜져 있는 NAS, 미니 PC, 또는 기존 홈서버가 있다면 Docker로 바로 실행할 수 있어요. 저도 별도의 Raspberry Pi 없이 기존 홈서버에서 운영 중입니다.

    Q. 유튜브 광고도 막을 수 있나요?

    아쉽지만 DNS 필터링만으로는 유튜브 광고 차단이 어렵습니다. 유튜브는 광고와 일반 콘텐츠를 같은 도메인에서 제공하기 때문이에요. 유튜브 광고는 브라우저 확장 프로그램(uBlock Origin 등)과 병행해서 사용하시는 걸 권장합니다.

    Q. DNS 서버가 다운되면 인터넷이 끊기나요?

    공유기에 1차 DNS만 Pi-hole/AdGuard Home으로 설정했다면, 서버가 다운될 경우 인터넷 접속이 안 될 수 있습니다. 2차 DNS로 공개 DNS(예: 1.1.1.1)를 설정해두거나, 앞서 언급한 것처럼 두 솔루션을 이중화하는 방법을 권장합니다.

    Q. Pi-hole과 AdGuard Home을 동시에 설치해도 되나요?

    같은 서버에 동시 설치는 포트 53 충돌 때문에 어렵습니다. 다른 서버(또는 VM/컨테이너)에 각각 설치해서 이중화 구성으로 운영하는 방식을 추천합니다.

  • [HomeLabs] 라즈베리파이 5 홈랩 구축: 저전력 미니PC 활용 완전 가이드

    전기세 걱정 없는 홈서버, 라즈베리파이 5로 시작해보세요

    홈랩(Home Lab)을 처음 꾸릴 때 저도 똑같은 고민을 했거든요. “중고 서버 살까? 미니PC 살까?” 근데 막상 중고 타워 서버를 들여놨더니 소음이 장난이 아니더라고요. 한밤중에 서버실(사실 제 방 한 켠이지만) 앞을 지나갈 때마다 데이터센터 온 느낌이랄까요. 그리고 전기 요금 고지서 받아보고 진짜 식겁했습니다.

    그래서 찾게 된 게 라즈베리파이 5(Raspberry Pi 5) 홈랩이에요. 저전력 홈서버로 이만한 게 없더라고요. 처음엔 “이 작은 게 뭘 할 수 있겠어?” 싶었는데, 막상 세팅하고 나니까 놀라웠습니다. 이 글에서는 제가 직접 구축하면서 겪은 삽질과 함께, 라즈베리파이 5 홈랩을 제대로 활용하는 방법을 공유해 드릴게요.

    라즈베리파이 5 기반 홈랩의 전체 구성도 — 단일 보드 컴퓨터 하나로 이렇게 많은 서비스를 돌릴 수 있습니다.

    라즈베리파이 5가 홈랩에 적합한 이유

    라즈베리파이 시리즈는 워낙 유명하지만, 5세대로 넘어오면서 진짜 “쓸만한” 홈서버로 거듭났어요. 이전 세대와 비교하면 체감 성능 차이가 꽤 납니다.

    라즈베리파이 5의 주요 스펙을 간단히 정리하면:

    • CPU: Broadcom BCM2712, Arm Cortex-A76 쿼드코어
    • RAM: 4GB 또는 8GB LPDDR4X (홈랩용이라면 8GB 추천)
    • 스토리지 인터페이스: PCIe 2.0 슬롯 추가 (NVMe SSD 연결 가능)
    • 네트워크: 기가비트 이더넷
    • USB: USB 3.0 포트 2개, USB 2.0 포트 2개

    여기서 제가 특히 주목한 건 PCIe 슬롯이에요. 이전 세대까지는 microSD 카드에 전적으로 의존하거나 USB 방식 외장 SSD를 써야 했거든요. 5세대부터는 공식 HAT(Hardware Attached on Top, 확장 보드)나 서드파티 어댑터를 통해 NVMe SSD를 직접 연결할 수 있어요. 속도 차이가 체감상 확연합니다.

    저전력 홈서버로서의 장점

    • ✅ 소음 없음: 액티브 쿨러를 달아도 일반 PC 대비 훨씬 조용
    • ✅ 저전력: 일반 데스크탑 PC 대비 전력 소모가 현저히 낮음
    • ✅ 공간 효율: 손바닥 크기라 어디든 놓을 수 있음
    • ✅ 활발한 커뮤니티: 문제 생기면 검색하면 다 나옴 (이게 진짜 중요해요)
    • ✅ 합리적인 가격: 진입 장벽이 낮음

    물론 단점도 있어요. x86 아키텍처가 아닌 ARM이라 일부 소프트웨어는 ARM 빌드를 따로 찾아야 하고, 고성능 컴퓨팅 작업에는 한계가 있습니다. 하지만 홈랩 용도, 특히 네트워크 서비스, 모니터링, 미디어 서버, 자동화 같은 작업에는 충분하더라고요.

    준비물 체크리스트

    본격적으로 시작하기 전에 뭐가 필요한지 정리해 드릴게요. 제가 처음에 이것저것 빠뜨려서 두 번 주문했던 기억이 나서 말이에요. ㅎㅎ

    항목 필수 여부 비고
    라즈베리파이 5 (8GB 모델 권장) ✅ 필수 홈랩이라면 8GB로
    공식 전원 어댑터 (27W USB-C PD) ✅ 필수 5세대는 전원 요구사항 달라짐
    microSD 카드 (32GB 이상) 또는 NVMe SSD ✅ 필수 NVMe 강력 추천
    케이스 + 쿨러 권장 발열 관리 필요
    NVMe HAT (M.2 어댑터) 선택 NVMe SSD 쓸 경우 필요
    이더넷 케이블 권장 Wi-Fi보다 유선 안정적

    💡 팁: 라즈베리파이 5는 공식 27W USB-C PD 어댑터를 권장합니다. 전력이 부족하면 부팅 중 경고 메시지가 뜨거나 불안정해질 수 있어요. 저도 처음에 아무 충전기나 꽂았다가 낭패 봤습니다.

    OS 설치 및 초기 설정

    자, 이제 본격적으로 세팅 시작해볼게요. 생각보다 어렵지 않습니다.

    1단계: Raspberry Pi OS 설치

    가장 쉬운 방법은 Raspberry Pi Imager를 사용하는 거예요. 공식 도구라 믿을 수 있고, 설치 전에 SSH 활성화, Wi-Fi 설정, 사용자 계정 설정까지 다 할 수 있거든요.

    1. Raspberry Pi 공식 사이트에서 Raspberry Pi Imager 다운로드
    2. OS 선택: Raspberry Pi OS Lite (64-bit) — 홈서버용이라면 GUI 없는 Lite 버전이 리소스 효율적
    3. 고급 설정(⚙️ 아이콘)에서 SSH 활성화, 사용자명/비밀번호 설정
    4. microSD 또는 NVMe에 Write

    설치 완료 후 첫 부팅, SSH로 접속해서 기본 설정부터 해줍니다.

    # 시스템 업데이트 (항상 첫 번째로 해야 할 일)
    sudo apt update && sudo apt upgrade -y
    
    # 한국 타임존 설정
    sudo timedatectl set-timezone Asia/Seoul
    
    # 호스트명 변경 (나중에 여러 대 운영할 때 헷갈리지 않으려면)
    sudo hostnamectl set-hostname homelab-pi5
    
    # 자동 보안 업데이트 설치
    sudo apt install unattended-upgrades -y
    sudo dpkg-reconfigure --priority=low unattended-upgrades

    2단계: 고정 IP 설정

    홈서버는 IP가 바뀌면 진짜 골치 아파요. 라우터에서 DHCP 예약을 하거나, 직접 고정 IP를 설정해 줍니다. 저는 라우터 DHCP 예약 방식을 선호하는데, 그게 관리하기 편하더라고요.

    직접 설정하고 싶다면 NetworkManager를 씁니다.

    # 현재 연결 이름 확인
    nmcli connection show
    
    # 고정 IP 설정 (예: 192.168.1.100)
    nmcli connection modify "Wired connection 1" \
      ipv4.method manual \
      ipv4.addresses 192.168.1.100/24 \
      ipv4.gateway 192.168.1.1 \
      ipv4.dns "1.1.1.1,8.8.8.8"
    
    # 적용
    nmcli connection up "Wired connection 1"

    3단계: Docker 설치

    홈랩의 핵심은 Docker(도커, 컨테이너 기반 가상화 플랫폼)예요. 여러 서비스를 격리된 환경에서 깔끔하게 관리할 수 있거든요. ARM64 지원이 많이 좋아져서 이제는 대부분의 인기 이미지가 ARM64 빌드를 제공합니다.

    # Docker 공식 설치 스크립트
    curl -fsSL https://get.docker.com -o get-docker.sh
    sudo sh get-docker.sh
    
    # 현재 사용자를 docker 그룹에 추가 (sudo 없이 docker 명령 사용)
    sudo usermod -aG docker $USER
    
    # 변경사항 적용을 위해 재로그인 필요
    newgrp docker
    
    # 설치 확인
    docker --version
    docker run hello-world

    Docker Compose도 함께 설치해 줍니다. 여러 컨테이너를 한 번에 관리할 때 필수예요.

    # Docker Compose V2는 Docker 설치 시 플러그인으로 포함됨
    # 확인
    docker compose version

    Docker 컨테이너로 구성한 홈랩 서비스 스택 — 각 서비스가 독립된 컨테이너로 동작하는 구조입니다.

    핵심 서비스 구축: 실전 Docker Compose 설정

    이제 진짜 재미있는 부분이에요. 어떤 서비스를 돌릴지가 홈랩의 핵심이거든요. 제가 실제로 운영 중인 서비스 스택을 공유해 드릴게요.

    홈랩 필수 서비스 구성

    # ~/homelab/docker-compose.yml
    version: '3.8'
    
    services:
    
      # Portainer: 도커 컨테이너 웹 UI 관리 도구
      portainer:
        image: portainer/portainer-ce:latest
        container_name: portainer
        restart: unless-stopped
        ports:
          - "9000:9000"
        volumes:
          - /var/run/docker.sock:/var/run/docker.sock
          - portainer_data:/data
    
      # Pi-hole: 네트워크 전체 광고 차단 DNS 서버
      pihole:
        image: pihole/pihole:latest
        container_name: pihole
        restart: unless-stopped
        ports:
          - "53:53/tcp"
          - "53:53/udp"
          - "8080:80/tcp"
        environment:
          TZ: 'Asia/Seoul'
          WEBPASSWORD: 'your_secure_password'  # 반드시 변경하세요!
        volumes:
          - pihole_data:/etc/pihole
          - dnsmasq_data:/etc/dnsmasq.d
        cap_add:
          - NET_ADMIN
    
      # Uptime Kuma: 서비스 모니터링 대시보드
      uptime-kuma:
        image: louislam/uptime-kuma:latest
        container_name: uptime-kuma
        restart: unless-stopped
        ports:
          - "3001:3001"
        volumes:
          - uptime_kuma_data:/app/data
    
    volumes:
      portainer_data:
      pihole_data:
      dnsmasq_data:
      uptime_kuma_data:
    # 서비스 시작
    cd ~/homelab
    docker compose up -d
    
    # 실행 상태 확인
    docker compose ps
    
    # 로그 확인
    docker compose logs -f

    🎉 이렇게 하면 세 가지 핵심 서비스가 한 번에 뜹니다. Portainer(포테이너)로 컨테이너를 웹에서 관리하고, Pi-hole(파이홀)로 집 안 모든 기기의 광고를 차단하고, Uptime Kuma(업타임 쿠마)로 서비스 가용성을 모니터링할 수 있어요.

    홈 미디어 서버 추가 (선택)

    미디어 서버도 많이들 구성하시는데, Jellyfin(젤리핀, 오픈소스 미디어 서버)이 ARM64 지원도 잘 되고 무료라서 추천드려요.

    # docker-compose.yml에 추가
      jellyfin:
        image: jellyfin/jellyfin:latest
        container_name: jellyfin
        restart: unless-stopped
        network_mode: host  # DLNA 사용 시 host 모드 권장
        volumes:
          - jellyfin_config:/config
          - jellyfin_cache:/cache
          - /mnt/media:/media:ro  # 미디어 파일 경로
        environment:
          - TZ=Asia/Seoul

    ⚠️ 삽질 경험담: 이것만 주의하세요

    13년 경력이라도 새 장비 세팅할 때는 항상 뭔가 하나씩 걸리더라고요. 제가 겪은 주요 문제들을 공유해 드릴게요.

    문제 1: 발열 관리

    라즈베리파이 5는 이전 세대보다 성능이 오른 만큼 발열도 있어요. 케이스 없이 쓰다가 CPU 쓰로틀링(Throttling, 과열 시 성능 제한)이 걸리는 걸 모니터링으로 발견했습니다.

    # CPU 온도 확인
    vcgencmd measure_temp
    
    # 실시간 모니터링
    watch -n 2 vcgencmd measure_temp
    
    # 쓰로틀링 여부 확인 (0x0이면 정상)
    vcgencmd get_throttled

    액티브 쿨러(팬)를 달거나, 방열판이 포함된 케이스를 사용하는 게 좋아요. 라즈베리파이 공식 액티브 쿨러 제품도 있고, 서드파티 케이스들도 많습니다.

    문제 2: ARM64 이미지 없는 경우

    가끔 원하는 Docker 이미지가 ARM64(aarch64)를 지원 안 하는 경우가 있어요. 이럴 때 확인하는 방법:

    # 이미지 아키텍처 확인
    docker manifest inspect [이미지명] | grep architecture
    
    # 만약 arm64 없으면 대안 이미지 검색 필요
    # 또는 QEMU 에뮬레이션 (성능 저하 있음)
    docker run --platform linux/amd64 [이미지명]

    ⚠️ QEMU 에뮬레이션으로 x86 이미지를 돌리면 성능이 많이 떨어집니다. 가능하면 ARM64 네이티브 이미지를 쓰세요.

    문제 3: microSD 카드 수명 문제

    Docker를 microSD에 올리고 로그를 막 쌓다 보면 카드 수명이 급격히 줄어요. 실제로 저 첫 번째 카드 6개월 만에 날렸습니다. 해결책은 두 가지예요.

    • NVMe SSD로 부팅 드라이브 변경 (가장 좋은 방법)
    • 로그 설정 최적화로 쓰기 횟수 줄이기
    # Docker 로그 크기 제한 설정
    # /etc/docker/daemon.json 생성 또는 수정
    sudo nano /etc/docker/daemon.json
    {
      "log-driver": "json-file",
      "log-opts": {
        "max-size": "10m",
        "max-file": "3"
      }
    }
    # Docker 재시작으로 적용
    sudo systemctl restart docker

    운영 결과 확인: 이렇게 쓰고 있습니다

    세팅 완료 후 실제로 어떻게 돌아가는지 확인해 보는 시간이에요. 드디어 됐다! 싶은 순간이기도 하고요.

    시스템 리소스 모니터링

    # 전체 시스템 상태 한눈에 보기
    htop
    
    # Docker 컨테이너별 리소스 사용량
    docker stats
    
    # 디스크 사용량
    df -h
    
    # 메모리 상세
    free -h

    제 경우 위에 소개한 서비스들을 다 올려도 RAM 사용량이 여유 있더라고요. 8GB 모델이라면 훨씬 더 여유롭게 쓸 수 있어요.

    Uptime Kuma 모니터링 대시보드 — 홈랩의 모든 서비스 상태를 한눈에 확인할 수 있습니다.

    자동 시작 설정

    정전이나 재부팅 후에도 서비스가 자동으로 올라오도록 설정해 줍니다.

    # Docker 서비스 자동 시작
    sudo systemctl enable docker
    
    # docker-compose를 systemd 서비스로 등록
    sudo nano /etc/systemd/system/homelab.service
    [Unit]
    Description=Homelab Docker Compose
    Requires=docker.service
    After=docker.service
    
    [Service]
    Type=oneshot
    RemainAfterExit=yes
    WorkingDirectory=/home/pi/homelab
    ExecStart=/usr/bin/docker compose up -d
    ExecStop=/usr/bin/docker compose down
    TimeoutStartSec=0
    
    [Install]
    WantedBy=multi-user.target
    # 서비스 등록 및 활성화
    sudo systemctl daemon-reload
    sudo systemctl enable homelab.service
    sudo systemctl start homelab.service

    다음 단계로 확장하기

    기본 세팅이 끝났다면 이제 더 재미있는 것들을 추가할 수 있어요. 제가 다음 글에서 다룰 예정인 주제들이기도 합니다.

    추천 확장 서비스 목록

    서비스 용도 ARM64 지원
    Nginx Proxy Manager 리버스 프록시, SSL 인증서 관리 ✅
    Grafana + Prometheus 메트릭 수집 및 시각화 대시보드 ✅
    Home Assistant 스마트홈 자동화 허브 ✅
    Vaultwarden 자체 호스팅 비밀번호 관리자 ✅
    Nextcloud 개인 클라우드 스토리지 ✅
    WireGuard VPN 서버 ✅

    💡 WireGuard(와이어가드, 경량 VPN 프로토콜)를 설정해 두면 외출 중에도 집 홈랩에 안전하게 접속할 수 있어요. 이건 다음 글에서 자세히 다루겠습니다.

    라즈베리파이 5 홈랩에서 활용 가능한 서비스 비교 — 용도에 맞게 골라서 구성해 보세요.

    자주 묻는 질문 (FAQ)

    Q. 라즈베리파이 5 홈랩, 24시간 켜놔도 되나요?

    네, 됩니다. 저도 항상 켜놓고 있어요. 다만 발열 관리(케이스 + 쿨러)와 안정적인 전원 공급이 중요합니다. UPS(무정전 전원 장치)까지 달면 더욱 안정적이에요.

    Q. microSD vs NVMe SSD, 어떤 게 낫나요?

    홈랩 용도라면 NVMe SSD를 강력히 추천드려요. 속도도 빠르고 수명도 훨씬 길거든요. 처음 세팅 비용이 조금 더 들지만, microSD 갈아 엎는 수고를 생각하면 훨씬 이득입니다.

    Q. 라즈베리파이 5 8GB vs 4GB, 뭐가 더 나을까요?

    홈랩 목적이라면 8GB를 권장합니다. Docker 컨테이너 여러 개 올리다 보면 4GB는 빠듯해질 수 있어요. 처음부터 8GB로 가는 게 나중에 후회가 없더라고요.

    마무리: 작게 시작해서 크게 배웁니다

    라즈베리파이 5 홈랩, 생각보다 어렵지 않죠? 처음엔 “이게 진짜 되겠어?” 싶었는데, 막상 세팅하고 나면 진짜 신세계가 열려요.

    제가 13년 동안 인프라 엔지니어로 일하면서 느낀 건, 홈랩이야말로 가장 빠르게 실력이 느는 방법이라는 거예요. 회사 서버는 함부로 건드릴 수 없으니까요. 집에서 마음껏 실험하고, 망가뜨려 보고, 복구해 보는 과정에서 진짜 실력이 쌓입니다.

    오늘 다룬 내용을 정리하면:

    • ✅ 라즈베리파이 5의 하드웨어 특성과 홈랩 적합성 이해
    • ✅ OS 설치 및 기본 시스템 설정
    • ✅ Docker 기반 서비스 스택 구성 (Portainer, Pi-hole, Uptime Kuma)
    • ✅ 발열, ARM64 호환성, 스토리지 수명 등 주요 이슈 해결
    • ✅ 시스템 안정성을 위한 자동 시작 설정

    다음 글에서는 Nginx Proxy Manager와 Let’s Encrypt를 활용한 HTTPS 설정을 다룰 예정이에요. 외부에서 홈랩 서비스에 안전하게 접속하는 방법인데, 이게 또 재미있거든요. 기대해 주세요! 😄

    궁금한 점이나 다른 삽질 경험이 있으시면 댓글로 공유해 주세요. 같이 고민해 봐요!