Karakeep Docker 설치 가이드: AI 기반 북마크 관리의 새로운 패러다임 ⋆ Blog * JackerLab

개요

Karakeep(구 Hoarder)는 AI 기반 자동 태깅과 전체 텍스트 검색을 지원하는 셀프호스팅 북마크 관리 앱입니다. 링크, 노트, 이미지, PDF를 저장하고 AI가 자동으로 태그와 요약을 생성합니다. Pocket의 종료 이후 가장 주목받는 read-it-later 앱으로, 데이터 수집가(Data Hoarder)를 위한 완벽한 도구입니다.

항목	내용
GitHub	https://github.com/karakeep-app/karakeep
공식 사이트	https://karakeep.app
문서	https://docs.karakeep.app
데모	https://try.karakeep.app
라이선스	AGPL-3.0
GitHub Stars	21K+

Karakeep이란?

Karakeep이라는 이름은 아랍어 “كراكيب”(karakeeb)에서 영감을 받았습니다. 이 단어는 “잡동사니”, “버리기 아까운 물건들”을 의미하며, 바로 우리가 북마크하는 것들의 본질을 담고 있습니다.

탄생 배경

Pocket 종료 → 대안 필요
memos 사용 → 링크 미리보기/태깅 부재
Linkwarden → 링크 중심, 이미지/노트 미지원
mymind → 상용 서비스

→ Karakeep: 모든 것을 저장하는 셀프호스팅 앱

핵심 철학

"모든 것을 북마크하라"
- 링크, 노트, 이미지, PDF, 동영상
- AI가 자동으로 태깅/요약
- 로컬 또는 클라우드 AI 선택
- 전체 텍스트 검색 (Meilisearch)

주요 기능

저장 가능한 콘텐츠

유형	기능
링크	제목, 설명, 이미지 자동 추출
노트	마크다운 지원 텍스트 메모
이미지	업로드 + OCR 텍스트 추출
PDF	업로드 + 텍스트 검색
동영상	YouTube 등 yt-dlp 지원 사이트

AI 기능

기능	설명
자동 태깅	콘텐츠 분석 후 태그 자동 생성
요약	긴 글 자동 요약
이미지 분석	이미지 내용 기반 태깅
OCR	이미지/PDF 내 텍스트 인식
다국어	한국어 포함 다양한 언어 지원

아카이브 기능

기능	설명
스크린샷	전체 페이지 스크린샷 저장
전체 페이지 아카이브	Monolith로 단일 HTML 저장
PDF 아카이브	페이지를 PDF로 저장
동영상 다운로드	yt-dlp 기반 동영상 저장

검색 및 정리

기능	설명
전체 텍스트 검색	Meilisearch 기반 빠른 검색
리스트	북마크 분류 (중첩 지원)
태그	AI + 수동 태그
필터	유형, 태그, 리스트별 필터링
자동 완성	검색어 자동 완성

앱 및 확장

플랫폼	지원
웹	PWA 지원
iOS	App Store
Android	Play Store
Chrome	확장 프로그램
Firefox	확장 프로그램
Safari	확장 프로그램

추가 기능

기능	설명
RSS 피드	RSS 구독 및 자동 저장
협업 리스트	여러 사용자와 리스트 공유
자동 백업	정기 백업 스케줄링
가져오기	Pocket, 브라우저, Omnivore, Linkwarden
내보내기	JSON, HTML 형식
OIDC	Google, Microsoft 등 SSO
API	REST API 제공

북마크 도구 비교

기능	Karakeep	Linkwarden	Wallabag	Shiori	Raindrop
셀프호스팅	✅	✅	✅	✅	❌
AI 태깅	✅	❌	❌	❌	❌
AI 요약	✅	❌	❌	❌	❌
이미지 저장	✅	✅	❌	❌	✅
노트	✅	❌	❌	❌	✅
PDF 저장	✅	✅	❌	❌	✅
전체 페이지 아카이브	✅	✅	✅	✅	❌
동영상 다운로드	✅	❌	❌	❌	❌
OCR	✅	❌	❌	❌	❌
로컬 AI (Ollama)	✅	❌	❌	❌	❌
모바일 앱	✅	✅	✅	❌	✅
라이선스	AGPL	MIT	MIT	MIT	상용

선택 가이드

상황	추천
AI 태깅/요약 필요	Karakeep
링크 + 이미지 + 노트 통합	Karakeep
동영상 아카이브 필요	Karakeep
로컬 AI 사용	Karakeep
심플한 북마크만	Shiori
팀 협업 중심	Linkwarden
read-it-later 중심	Wallabag

시스템 요구 사항

최소 사양

항목	최소	권장
CPU	2 Core	4 Core
RAM	2GB	4GB+
저장소	10GB	50GB+

AI (Ollama) 사용 시

항목	최소	권장
RAM	8GB	16GB+
VRAM	–	8GB+ (GPU 사용 시)
저장소	20GB+	50GB+

Docker 설치

방법 1: 기본 설치 (권장)

# docker-compose.yml
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    container_name: karakeep-web
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    env_file:
      - .env
    environment:
      - MEILI_ADDR=http://meilisearch:7700
      - BROWSER_WEB_URL=http://chrome:9222
      - DATA_DIR=/data
    depends_on:
      - chrome
      - meilisearch

  chrome:
    image: gcr.io/zenika-hub/alpine-chrome:124
    container_name: karakeep-chrome
    restart: unless-stopped
    command:
      - --no-sandbox
      - --disable-gpu
      - --disable-dev-shm-usage
      - --remote-debugging-address=0.0.0.0
      - --remote-debugging-port=9222
      - --hide-scrollbars

  meilisearch:
    image: getmeili/meilisearch:v1.13
    container_name: karakeep-meilisearch
    restart: unless-stopped
    environment:
      - MEILI_NO_ANALYTICS=true
    volumes:
      - ./meilisearch:/meili_data

# .env
NEXTAUTH_SECRET=your_random_secret_here_use_openssl_rand
NEXTAUTH_URL=http://localhost:3000
MEILI_MASTER_KEY=your_meilisearch_master_key

# 선택: OpenAI API
# OPENAI_API_KEY=sk-xxxxxxxx

# 선택: 회원가입 비활성화
# DISABLE_SIGNUPS=true

실행:

mkdir -p ~/karakeep && cd ~/karakeep

# 시크릿 키 생성
openssl rand -base64 36

# .env 파일 생성 후 위 키 입력
# docker-compose.yml 생성

docker compose up -d

# 로그 확인
docker compose logs -f web

접속: http://localhost:3000

방법 2: OpenAI API 사용

# .env
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=http://localhost:3000
MEILI_MASTER_KEY=your_meilisearch_key

# OpenAI 설정
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
# INFERENCE_TEXT_MODEL=gpt-4o-mini      # 기본값
# INFERENCE_IMAGE_MODEL=gpt-4o-mini     # 기본값
INFERENCE_CONTEXT_LENGTH=2048
INFERENCE_LANG=korean

방법 3: Ollama (로컬 AI) 사용

# docker-compose.yml
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    container_name: karakeep-web
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    env_file:
      - .env
    environment:
      - MEILI_ADDR=http://meilisearch:7700
      - BROWSER_WEB_URL=http://chrome:9222
      - DATA_DIR=/data
      - OLLAMA_BASE_URL=http://ollama:11434
      - INFERENCE_TEXT_MODEL=llama3.2
      - INFERENCE_IMAGE_MODEL=llava
      - INFERENCE_CONTEXT_LENGTH=4096
      - INFERENCE_LANG=korean
    depends_on:
      - chrome
      - meilisearch
      - ollama

  chrome:
    image: gcr.io/zenika-hub/alpine-chrome:124
    container_name: karakeep-chrome
    restart: unless-stopped
    command:
      - --no-sandbox
      - --disable-gpu
      - --disable-dev-shm-usage
      - --remote-debugging-address=0.0.0.0
      - --remote-debugging-port=9222
      - --hide-scrollbars

  meilisearch:
    image: getmeili/meilisearch:v1.13
    container_name: karakeep-meilisearch
    restart: unless-stopped
    environment:
      - MEILI_NO_ANALYTICS=true
    volumes:
      - ./meilisearch:/meili_data

  ollama:
    image: ollama/ollama:latest
    container_name: karakeep-ollama
    restart: unless-stopped
    volumes:
      - ./ollama:/root/.ollama
    # GPU 사용 시 (Nvidia)
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: 1
    #           capabilities: [gpu]

# Ollama 모델 다운로드
docker exec -it karakeep-ollama ollama pull llama3.2
docker exec -it karakeep-ollama ollama pull llava

방법 4: 외부 Ollama 서버 연결

이미 Ollama가 다른 서버에서 실행 중인 경우:

# .env
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=http://localhost:3000
MEILI_MASTER_KEY=your_meilisearch_key

# 외부 Ollama
OLLAMA_BASE_URL=http://192.168.1.100:11434
INFERENCE_TEXT_MODEL=llama3.2
INFERENCE_IMAGE_MODEL=llava
INFERENCE_CONTEXT_LENGTH=4096
INFERENCE_LANG=korean

⚠️ OPENAI_API_KEY가 설정되어 있으면 Ollama보다 우선합니다. Ollama 사용 시 OPENAI_API_KEY를 제거하세요.

방법 5: 전체 기능 활성화

# docker-compose.yml
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    container_name: karakeep-web
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    env_file:
      - .env
    environment:
      - MEILI_ADDR=http://meilisearch:7700
      - BROWSER_WEB_URL=http://chrome:9222
      - DATA_DIR=/data
    depends_on:
      - chrome
      - meilisearch

  chrome:
    image: ghcr.io/karakeep-app/karakeep-chrome:release
    container_name: karakeep-chrome
    restart: unless-stopped
    environment:
      - CHROME_PORT=9222
    # 동영상 다운로드용 볼륨
    # volumes:
    #   - ./videos:/videos

  meilisearch:
    image: getmeili/meilisearch:v1.13
    container_name: karakeep-meilisearch
    restart: unless-stopped
    environment:
      - MEILI_NO_ANALYTICS=true
    volumes:
      - ./meilisearch:/meili_data

# .env - 전체 기능
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=https://karakeep.example.com
MEILI_MASTER_KEY=your_meilisearch_key

# AI 설정
OPENAI_API_KEY=sk-xxxxxxxx
INFERENCE_CONTEXT_LENGTH=4096
INFERENCE_LANG=korean

# 아카이브 설정
CRAWLER_FULL_PAGE_SCREENSHOT=true
CRAWLER_FULL_PAGE_ARCHIVE=true
CRAWLER_STORE_PDF=true
CRAWLER_VIDEO_DOWNLOAD=true
CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE=500

# 업로드 제한
MAX_ASSET_SIZE_MB=50

# 사용자 설정
DISABLE_SIGNUPS=true
DISABLE_PASSWORD_AUTH=false

# OCR
OCR_LANGS=kor+eng

방법 6: Traefik 연동

# docker-compose.yml
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    container_name: karakeep-web
    restart: unless-stopped
    volumes:
      - ./data:/data
    env_file:
      - .env
    environment:
      - MEILI_ADDR=http://meilisearch:7700
      - BROWSER_WEB_URL=http://chrome:9222
      - DATA_DIR=/data
    depends_on:
      - chrome
      - meilisearch
    networks:
      - karakeep_internal
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.karakeep.rule=Host(`karakeep.example.com`)"
      - "traefik.http.routers.karakeep.entrypoints=websecure"
      - "traefik.http.routers.karakeep.tls.certresolver=letsencrypt"
      - "traefik.http.services.karakeep.loadbalancer.server.port=3000"

  chrome:
    image: gcr.io/zenika-hub/alpine-chrome:124
    container_name: karakeep-chrome
    restart: unless-stopped
    command:
      - --no-sandbox
      - --disable-gpu
      - --disable-dev-shm-usage
      - --remote-debugging-address=0.0.0.0
      - --remote-debugging-port=9222
      - --hide-scrollbars
    networks:
      - karakeep_internal

  meilisearch:
    image: getmeili/meilisearch:v1.13
    container_name: karakeep-meilisearch
    restart: unless-stopped
    environment:
      - MEILI_NO_ANALYTICS=true
    volumes:
      - ./meilisearch:/meili_data
    networks:
      - karakeep_internal

networks:
  karakeep_internal:
  traefik_network:
    external: true

방법 7: S3 스토리지 사용

대용량 미디어를 S3 호환 스토리지에 저장:

# .env
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=https://karakeep.example.com
MEILI_MASTER_KEY=your_meilisearch_key

# S3 설정
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=karakeep-assets
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_REGION=us-east-1

방법 8: 최소 설치 (AI 없음)

리소스가 제한된 환경:

# docker-compose.yml
services:
  web:
    image: ghcr.io/karakeep-app/karakeep:release
    container_name: karakeep
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - DATA_DIR=/data
      - NEXTAUTH_SECRET=your_random_secret_here

⚠️ 최소 설치는 AI 태깅, 스크린샷, 전체 텍스트 검색이 비활성화됩니다.

환경 변수

필수 설정

변수	설명	예시
`NEXTAUTH_SECRET`	인증 시크릿 (필수)	`openssl rand -base64 36`
`NEXTAUTH_URL`	앱 URL	`https://karakeep.example.com`
`MEILI_MASTER_KEY`	Meilisearch 마스터 키	`openssl rand -base64 36`

AI 설정

변수	설명	기본값
`OPENAI_API_KEY`	OpenAI API 키	–
`OPENAI_BASE_URL`	OpenAI 호환 API URL	–
`OLLAMA_BASE_URL`	Ollama 서버 URL	–
`INFERENCE_TEXT_MODEL`	텍스트 모델	`gpt-4o-mini`
`INFERENCE_IMAGE_MODEL`	이미지 모델	`gpt-4o-mini`
`INFERENCE_CONTEXT_LENGTH`	컨텍스트 길이	`512`
`INFERENCE_LANG`	태그 언어	`english`
`INFERENCE_JOB_TIMEOUT_SEC`	AI 작업 타임아웃	`60`

크롤러 설정

변수	설명	기본값
`CRAWLER_FULL_PAGE_SCREENSHOT`	전체 페이지 스크린샷	`false`
`CRAWLER_FULL_PAGE_ARCHIVE`	전체 페이지 아카이브	`false`
`CRAWLER_STORE_PDF`	PDF 저장	`false`
`CRAWLER_VIDEO_DOWNLOAD`	동영상 다운로드	`false`
`CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE`	동영상 최대 크기 (MB)	`100`
`BROWSER_WEB_URL`	Chrome 서비스 URL	`http://chrome:9222`
`BROWSER_COOKIE_PATH`	쿠키 파일 경로	–

사용자 설정

변수	설명	기본값
`DISABLE_SIGNUPS`	회원가입 비활성화	`false`
`DISABLE_PASSWORD_AUTH`	비밀번호 인증 비활성화	`false`
`MAX_ASSET_SIZE_MB`	최대 업로드 크기	`4`

OCR 설정

변수	설명	예시
`OCR_LANGS`	OCR 언어	`kor+eng`

S3 스토리지

변수	설명
`S3_ENDPOINT`	S3 엔드포인트 URL
`S3_BUCKET`	버킷 이름
`S3_ACCESS_KEY`	액세스 키
`S3_SECRET_KEY`	시크릿 키
`S3_REGION`	리전

초기 설정

1) 첫 접속

URL: http://localhost:3000

Sign Up 클릭
이메일, 비밀번호 입력
계정 생성

2) 회원가입 비활성화

본인 계정 생성 후:

# .env 수정
DISABLE_SIGNUPS=true

# 재시작
docker compose up -d

3) 브라우저 확장 프로그램 설치

Chrome: Chrome 웹 스토어에서 “Karakeep” 검색
Firefox: Firefox Add-ons에서 “Karakeep” 검색

확장 프로그램 설정에서 서버 URL 입력 후 API 키로 로그인

4) 모바일 앱 설치

iOS: App Store에서 “Karakeep” 검색
Android: Play Store에서 “Karakeep” 검색

사용 가이드

북마크 추가

웹 UI:

상단 “New Item” 클릭
URL 붙여넣기 또는 텍스트 입력
자동으로 메타데이터 추출 및 AI 태깅

브라우저 확장:

저장하고 싶은 페이지에서 확장 프로그램 클릭
원클릭 저장

모바일 앱:

공유 메뉴에서 Karakeep 선택
즉시 저장

리스트 관리

좌측 메뉴에서 Lists 선택
New List 클릭
이름, 아이콘 설정
중첩 리스트 가능 (하위 리스트 생성)

AI 기능 사용

자동 태깅:

북마크 저장 시 자동 실행
Settings → AI Settings에서 추가 프롬프트 설정 가능

수동 요약:

북마크 클릭
“Summarize with AI” 버튼 클릭

가져오기

Pocket:

Pocket에서 CSV 내보내기
Settings → Import → Pocket 선택
CSV 파일 업로드

브라우저 북마크:

브라우저에서 북마크 HTML 내보내기
Settings → Import → Browser 선택
HTML 파일 업로드

지원 가져오기 소스:

Pocket
Browser (HTML)
Omnivore
Linkwarden
JSON

백업 및 복원

자동 백업 설정

Settings → Backups에서 자동 백업 스케줄 설정

수동 백업

# 데이터 디렉토리 백업
tar -czvf karakeep-backup-$(date +%Y%m%d).tar.gz ./data ./meilisearch

내보내기

Settings → Import/Export → Export

JSON 형식
HTML 형식

업데이트

cd ~/karakeep

# 버전 지정 방식
# .env에서 KARAKEEP_VERSION=0.30.0 수정 후
docker compose pull
docker compose up -d

# release 태그 사용 시
docker compose pull
docker compose up -d

💡 업데이트 전 항상 백업을 권장합니다. 릴리즈 노트에서 breaking changes를 확인하세요.

트러블슈팅

AI 태깅이 작동하지 않음

OpenAI 사용 시:

# 로그 확인
docker compose logs web | grep -i inference

# 일반적인 원인:
# - API 키 오타
# - 크레딧 부족 (OpenAI 선불 필요)
# - .env 변경 후 재시작 안 함

Ollama 사용 시:

# 모델 다운로드 확인
docker exec -it karakeep-ollama ollama list

# 연결 테스트
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Hello"
}'

# 일반적인 원인:
# - OPENAI_API_KEY가 설정되어 있음 (제거 필요)
# - INFERENCE_TEXT_MODEL 오타 (예: INTERFERENCE_TEXT_MODEL)
# - 모델 미다운로드
# - 메모리 부족

스크린샷/아카이브가 생성되지 않음

# Chrome 서비스 확인
docker compose logs chrome

# Chrome 서비스 재시작
docker compose restart chrome

# 환경 변수 확인
# CRAWLER_FULL_PAGE_SCREENSHOT=true
# CRAWLER_FULL_PAGE_ARCHIVE=true

검색이 작동하지 않음

# Meilisearch 상태 확인
docker compose logs meilisearch

# 인덱스 재생성
# Admin Panel → Rebuild Search Index

링크 메타데이터가 추출되지 않음

# Chrome 서비스 실행 확인
docker compose ps

# Chrome 서비스 로그
docker compose logs chrome

Proxmox LXC에서 Docker 문제

# 권한 모드로 전환 또는
# AppArmor 규칙 조정

보안

회원가입 비활성화

DISABLE_SIGNUPS=true

OIDC 인증

# .env
OAUTH_WELLKNOWN_URL=https://auth.example.com/.well-known/openid-configuration
OAUTH_CLIENT_ID=karakeep
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_SCOPE=openid email profile

HTTPS 필수

프로덕션에서는 반드시 Traefik/Nginx + HTTPS를 사용하세요.

API 키 관리

Settings → API Keys에서 API 키 생성/삭제

사용 사례

1. 리서치/학습 자료 수집

논문, 튜토리얼 자동 아카이브
AI 태깅으로 주제별 자동 분류
전체 텍스트 검색으로 빠른 검색

2. 개발자 북마크

코드 스니펫, 문서, 블로그 저장
GitHub 리포지토리 북마크
Stack Overflow 답변 아카이브

3. 뉴스/콘텐츠 큐레이션

RSS 피드 구독
기사 자동 요약
리스트로 주제별 정리

4. 미디어 아카이브

YouTube 동영상 다운로드
이미지 OCR로 텍스트 추출
PDF 문서 관리

마무리

Karakeep은 Pocket의 종료 이후 등장한 가장 강력한 셀프호스팅 북마크 관리 도구입니다. 링크, 노트, 이미지, PDF, 동영상을 한 곳에서 관리하고, AI가 자동으로 태깅과 요약을 생성합니다. OpenAI API 또는 로컬 Ollama를 선택할 수 있어 프라이버시와 비용을 모두 고려할 수 있습니다.

핵심 장점

장점	설명
모든 것 저장	링크, 노트, 이미지, PDF, 동영상
AI 태깅/요약	자동 분류 및 요약
로컬 AI	Ollama로 프라이버시 보장
전체 아카이브	스크린샷, HTML, PDF 저장
빠른 검색	Meilisearch 기반
크로스 플랫폼	웹, iOS, Android, 브라우저 확장

이런 분께 추천

Pocket 대안을 찾는 분
AI 기반 자동 분류가 필요한 분
링크 + 이미지 + 노트를 통합 관리하고 싶은 분
동영상/PDF 아카이브가 필요한 분
로컬 AI로 프라이버시를 지키고 싶은 분

개요