Umami Docker 설치 가이드: 심플한 프라이버시 웹 분석

작성자:


Umami는 가장 심플하고 가벼운 Google Analytics 대안입니다. Next.js로 구축되어 빠르고, 깔끔한 UI로 필요한 지표만 보여줍니다. 쿠키를 사용하지 않아 GDPR 걱정 없이 사용할 수 있으며, 설치와 설정이 매우 간단합니다. 리소스 사용량이 적어 Raspberry Pi에서도 실행 가능합니다. GitHub Stars 25K+로 가장 인기 있는 GA 대안 중 하나입니다.

Umami 주요 특징

Umami는 심플함을 최우선으로 합니다.

핵심 기능

  • 실시간 분석: 방문자 실시간 확인
  • 페이지뷰 & 방문자: 기본 트래픽 지표
  • 유입 경로: 레퍼러, 검색 엔진
  • 지역 & 기기: 국가, 브라우저, OS, 디바이스
  • 이벤트 추적: 커스텀 이벤트 수집
  • UTM 파라미터: 캠페인 추적

프라이버시 & 성능

  • 쿠키 사용 안 함
  • GDPR/CCPA 준수
  • 가벼운 스크립트 (< 2KB)
  • 빠른 로딩

기술적 장점

  • Next.js 기반 (빠른 UI)
  • PostgreSQL/MySQL 지원
  • 다중 사이트 관리
  • 팀 협업 기능
  • REST API
  • 다크 모드

사전 요구 사항

  • Docker 및 Docker Compose 설치
  • 최소 512MB RAM
  • PostgreSQL 또는 MySQL

Docker Compose로 Umami 설치

기본 설치 (PostgreSQL)

# docker-compose.yml
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD}@umami-db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
    depends_on:
      umami-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/heartbeat || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 5

  umami-db:
    image: postgres:16-alpine
    container_name: umami-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - umami-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  umami-db:

환경 변수 파일

# .env
DB_PASSWORD=your_secure_password
APP_SECRET=your_random_secret_string

시크릿 생성:

openssl rand -hex 32

설치 및 실행

# 디렉토리 생성
mkdir umami && cd umami

# docker-compose.yml 및 .env 생성

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

# 로그 확인
docker compose logs -f umami

# 브라우저에서 접속
# http://localhost:3000
# 기본 로그인: admin / umami

초기 설정

1. 기본 비밀번호 변경

  1. http://localhost:3000 접속
  2. admin / umami 로 로그인
  3. Settings → Profile → Change password
  4. 새 비밀번호 설정

2. 웹사이트 추가

  1. Settings → Websites → Add website
  2. Name: 사이트 이름
  3. Domain: example.com
  4. “Save” 클릭
  5. “Edit” → “Tracking code” → 코드 복사

3. 추적 코드 설치

웹사이트 <head> 태그에 추가:

<script defer src="https://umami.yourdomain.com/script.js" 
        data-website-id="your-website-id"></script>

고급 설정

Redis 캐시 추가 (성능 향상)

# docker-compose.yml
services:
  umami:
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD}@umami-db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
      REDIS_URL: redis://umami-redis:6379
    depends_on:
      - umami-db
      - umami-redis

  umami-redis:
    image: redis:alpine
    container_name: umami-redis
    restart: unless-stopped

  umami-db:
    # ... (이전과 동일)

Traefik 연동

# docker-compose.yml
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami
    restart: unless-stopped
    expose:
      - "3000"
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD}@umami-db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: ${APP_SECRET}
      TRACKER_SCRIPT_NAME: stats  # 애드블로커 우회
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.umami.rule=Host(`stats.yourdomain.com`)"
      - "traefik.http.routers.umami.entrypoints=websecure"
      - "traefik.http.routers.umami.tls.certresolver=letsencrypt"
      - "traefik.http.services.umami.loadbalancer.server.port=3000"
    networks:
      - umami-net
      - traefik-public

networks:
  umami-net:
    driver: bridge
  traefik-public:
    external: true

Caddy 리버스 프록시

# Caddyfile
stats.yourdomain.com {
    encode zstd gzip
    reverse_proxy umami:3000 {
        health_uri /api/heartbeat
        health_interval 10s
        health_timeout 2s
    }
}

Nginx 리버스 프록시

server {
    listen 443 ssl http2;
    server_name stats.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/stats.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/stats.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

주요 환경 변수

변수설명필수
DATABASE_URLDB 연결 문자열✅
DATABASE_TYPEpostgresql 또는 mysql✅
APP_SECRET세션 암호화 키✅
REDIS_URLRedis 연결 (캐시)❌
TRACKER_SCRIPT_NAME스크립트 파일명 변경❌
DISABLE_TELEMETRY텔레메트리 비활성화❌

커스텀 이벤트 추적

JavaScript

// 버튼 클릭 추적
umami.track('signup-button-click');

// 데이터와 함께 추적
umami.track('purchase', { product: 'T-Shirt', price: 29.99 });

HTML 속성

<button data-umami-event="signup-click">Sign Up</button>

<button data-umami-event="purchase" data-umami-event-product="T-Shirt">Buy</button>

관리 명령어

# 로그 확인
docker compose logs -f umami

# 데이터베이스 백업
docker compose exec umami-db pg_dump -U umami umami > backup_$(date +%Y%m%d).sql

# 업데이트
docker compose pull
docker compose up -d

# 재시작
docker compose restart umami

# 헬스 체크
curl http://localhost:3000/api/heartbeat

문제 해결

기본 계정으로 로그인 불가

데이터베이스가 초기화되지 않았을 수 있습니다:

docker compose down -v
docker compose up -d

애드블로커에 의해 차단됨

스크립트 이름을 analytics가 아닌 이름으로 변경:

environment:
  TRACKER_SCRIPT_NAME: stats

그리고 추적 코드도 변경:

<script src="https://stats.yourdomain.com/stats.js" ...></script>

localhost 접근만 허용하기

리버스 프록시 뒤에서 실행 시:

ports:
  - "127.0.0.1:3000:3000"

Plausible vs Umami 비교

항목UmamiPlausible
메모리 사용량낮음 (~100MB)높음 (~500MB+)
데이터베이스PostgreSQL/MySQLPostgreSQL + ClickHouse
설치 복잡도매우 쉬움보통
UI모던, 미니멀깔끔, 단순
이벤트 추적✅✅
목표 전환기본상세

마무리

Umami는 가장 심플하고 가벼운 GA 대안입니다. 설치가 쉽고 리소스 사용량이 적어 소규모 사이트부터 대규모 서비스까지 사용할 수 있습니다. 깔끔한 UI와 필요한 기능만 제공하여 복잡한 분석 도구가 필요 없는 경우 최적의 선택입니다.

참고 링크

  • 공식 사이트: https://umami.is
  • GitHub: https://github.com/umami-software/umami
  • 문서: https://umami.is/docs
  • Docker: ghcr.io/umami-software/umami


댓글 남기기