Karakeep: VPS에 개인 북마크 아카이브 설치하기

링크를 저장하는 것은 쉽습니다. 하지만 6개월 뒤 다시 찾는 일은 훨씬 어렵습니다. 특히 페이지가 변경되거나 사라졌거나 수백 개의 북마크 사이에 묻힌 경우에는 더욱 그렇습니다.

Karakeep은 URL뿐 아니라 페이지 내용, 미리보기, 메모, 이미지, PDF까지 저장합니다. 아카이브를 텍스트로 검색하고 목록별로 정리하며 AI로 자동 태그를 붙일 수도 있습니다. 서비스는 자신의 VPS에서 실행되며 언어 모델 연결은 선택 사항입니다.

아래에서는 Karakeep의 기능과 서버 요구 사항, Ubuntu 24.04에서 Docker Compose로 설치하고 HTTPS와 백업을 설정하는 방법을 살펴봅니다.

일곱 단계로 Karakeep 설치하기

1. Linux VPS를 만들고 keep.example.com 같은 하위 도메인을 연결합니다.
2. Docker Engine과 Docker Compose를 설치합니다.
3. 공식 docker-compose.yml을 다운로드합니다.
4. 시크릿을 생성하고 Karakeep, Chrome, Meilisearch를 실행합니다.
5. 내부 포트 3000을 닫고 Caddy를 통해 HTTPS를 연결합니다.
6. 첫 번째 계정을 만든 다음 공개 회원가입을 비활성화합니다.
7. 브라우저 확장 프로그램이나 모바일 앱을 설치하고 북마크를 가져옵니다.

서비스를 실행하는 데 AI 키는 필요하지 않습니다. 키가 없어도 페이지 저장, 목록, 메모, OCR, 전문 검색은 계속 작동합니다. 자동 태그와 요약만 생성되지 않습니다.

Karakeep이란

Karakeep은 링크, 텍스트 메모, 이미지, PDF를 하나의 라이브러리에 저장하는 오픈 소스 셀프 호스팅 애플리케이션입니다. 이전 프로젝트 이름은 Hoarder였습니다.

이름은 아랍어 karakeeb에서 왔습니다. 겉보기에는 어수선하지만 숨은 가치가 있을 수 있는 흩어진 물건을 뜻합니다. 유용한 자료는 많지만 필요한 것을 찾기 어려운 일반적인 북마크 모음을 정확히 표현하는 이름입니다.

링크를 추가하면 Karakeep이 제목과 설명을 가져오고 읽기 쉬운 본문을 추출하며 미리보기를 만들고 필요할 경우 페이지의 로컬 사본을 저장합니다.

기능	브라우저 북마크	Karakeep
저장되는 내용	URL과 제목	본문, 미리보기, 메모, 첨부 파일
검색	제목과 주소 기준	내용, 태그, 메모 기준
페이지가 사라진 경우	작동하지 않는 URL만 남음	본문, 스크린샷 또는 전체 아카이브가 남음
정리 방식	폴더	태그, 수동 목록, 스마트 목록
접근 방법	브라우저 내부	웹, 확장 프로그램, iOS, Android
서버	브라우저 프로필 또는 브라우저 클라우드	자신의 VPS 또는 홈 서버

Karakeep의 주요 기능

링크, 메모, 이미지, PDF

각 항목은 링크, 텍스트 메모 또는 업로드한 파일이 될 수 있습니다. OCR이 이미지와 PDF에서 텍스트를 추출하므로 이런 파일도 검색 대상에 포함됩니다. 자료에 메모, 인용문 또는 추가 파일을 첨부할 수도 있습니다.

내용 검색

Meilisearch는 저장된 본문, 메모, 메타데이터를 색인합니다. 정확한 제목을 기억할 필요 없이 문구나 주제만 입력해도 됩니다. 임베딩을 설정하면 의미를 기준으로 찾는 시맨틱 검색도 사용할 수 있습니다.

스마트 목록과 공동 목록

하나의 항목을 복제하지 않고 여러 목록에 동시에 넣을 수 있습니다. 목록은 비공개로 유지하거나 링크로 공유하거나 다른 사용자와 함께 편집할 수 있습니다.

스마트 목록은 저장된 검색 조건이며 자동으로 갱신됩니다. 예를 들어 지난 일주일 동안 추가된 ai 태그 자료를 모두 표시할 수 있습니다.

페이지 아카이빙

기본적으로 Karakeep은 추출한 본문과 화면에 보이는 페이지 영역의 스크린샷을 저장합니다. 전체 페이지 스냅샷, PDF 또는 독립 실행형 HTML 아카이브를 추가로 활성화할 수도 있습니다. 이렇게 하면 죽은 링크로부터 라이브러리를 보호할 수 있지만 디스크 사용량은 늘어납니다.

로그인이 필요한 페이지, 복잡한 봇 차단 기능이 적용된 페이지, 대화형 애플리케이션은 완전히 저장되지 않을 수 있습니다. 중요한 자료는 PDF나 파일로 별도 업로드하는 것이 좋습니다.

선택형 AI 태깅

Karakeep은 외부 OpenAI 호환 API 또는 로컬 Ollama 모델을 통해 태그와 짧은 요약을 생성할 수 있습니다. AI를 사용하지 않아도 완전한 북마크 관리자로 계속 작동합니다.

로컬 모델은 자료를 외부 제공업체로 보내지 않지만 훨씬 많은 RAM이 필요합니다. 그래서 Ollama를 Karakeep 본체와 분리해 배치하는 경우가 많습니다.

Karakeep 서버 요구 사항

공식 문서는 CPU와 RAM의 고정된 최저 사양을 제시하지 않습니다. 전체 설치에는 세 개의 컨테이너가 포함됩니다.

• Karakeep은 데이터베이스를 저장하고 인터페이스를 제공합니다.
• 헤드리스 Chrome은 페이지를 열고 JavaScript를 실행하며 스크린샷을 만듭니다.
• Meilisearch는 라이브러리를 색인합니다.

로컬 LLM 없이 한 명이 사용할 때의 실용적인 구성은 다음과 같습니다.

• 2 vCPU;
• 2GB RAM;
• 20~30GB SSD 또는 NVMe;
• Ubuntu 24.04 LTS;
• 공인 IP와 도메인.

여러 사용자, 대규모 가져오기, 많은 RSS 피드와 PDF를 처리한다면 4GB RAM이 더 편안합니다. 필요한 디스크 크기는 아카이빙 방식에 따라 달라집니다. 텍스트는 공간을 거의 차지하지 않지만 전체 스크린샷, PDF, 동영상은 라이브러리 용량을 빠르게 늘릴 수 있습니다.

VPS에 Karakeep을 설치하는 방법

이 예시에서는 Ubuntu 24.04와 keep.example.com 하위 도메인을 사용합니다.

1. DNS와 방화벽 설정하기

서버 IP 주소를 가리키는 DNS A 레코드를 만든 다음 SSH로 접속합니다.

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

새 연결이 정상적으로 작동하는지 확인하기 전에는 현재 SSH 세션을 닫지 마십시오.

2. Docker 설치하기

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
docker compose version

3. Karakeep 설정 다운로드하기

mkdir -p /opt/karakeep
cd /opt/karakeep

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

서로 다른 시크릿 두 개를 생성합니다.

openssl rand -base64 36
openssl rand -base64 36 | tr -dc 'A-Za-z0-9'

/opt/karakeep/.env를 만듭니다.

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=첫번째_시크릿을_입력하세요
MEILI_MASTER_KEY=두번째_시크릿을_입력하세요
NEXTAUTH_URL=https://keep.example.com
DISABLE_SIGNUPS=false
DB_WAL_MODE=true
RATE_LIMITING_ENABLED=true

.env를 공개하지 마십시오. 첫 번째 시크릿은 인증 토큰에 서명하고 두 번째 시크릿은 Meilisearch를 보호합니다.

4. 내부 포트 닫기

docker-compose.yml에서 다음 내용을:

ports:
  - 3000:3000

다음과 같이 바꿉니다.

ports:
  - 127.0.0.1:3000:3000

이제 포트 3000에 인터넷에서 직접 접근할 수 없습니다.

5. 컨테이너 실행하기

cd /opt/karakeep
docker compose up -d
docker compose ps

web, chrome, meilisearch 서비스가 실행 중이어야 합니다. 로그는 다음 명령으로 확인합니다.

docker compose logs --tail=200

6. HTTPS 연결하기

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
keep.example.com {
    reverse_proxy 127.0.0.1:3000
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

DNS가 설정되어 있고 포트 80과 443이 열려 있다면 Caddy가 TLS 인증서를 자동으로 발급받습니다. 이후 https://keep.example.com을 여십시오.

7. 관리자 생성 후 회원가입 닫기

처음 가입한 사용자가 자동으로 관리자가 됩니다. 계정을 만든 뒤 .env에 다음 값을 설정합니다.

DISABLE_SIGNUPS=true

변경 사항을 적용합니다.

cd /opt/karakeep
docker compose up -d

관리자는 이후에도 다른 계정을 수동으로 만들 수 있습니다.

가져오기, 확장 프로그램, 모바일 앱

Karakeep은 Chrome, Firefox, Safari용 확장 프로그램과 iOS 및 Android 앱을 제공합니다. 휴대전화에서는 시스템의 공유 메뉴를 통해 링크를 아카이브로 보낼 수 있습니다.

기존 북마크는 브라우저의 표준 HTML 파일, Pocket, Omnivore 및 기타 지원 서비스에서 가져올 수 있습니다. 큰 아카이브는 여러 번에 나눠 추가하는 편이 좋습니다. 서버가 페이지를 열고 본문을 추출하고 스크린샷을 만들고 검색 색인을 구축해야 하기 때문입니다.

AI와 전체 페이지 아카이빙 활성화하기

OpenAI를 사용하려면 .env에 다음을 추가합니다.

OPENAI_API_KEY=사용자_API_키

다른 OpenAI 호환 서비스는 OPENAI_BASE_URL이 추가로 필요할 수 있습니다. 로컬 모델에는 컨테이너에서 접근 가능한 주소를 OLLAMA_BASE_URL로 지정합니다.

페이지의 완전한 로컬 사본은 별도로 활성화합니다.

CRAWLER_FULL_PAGE_ARCHIVE=true

CRAWLER_FULL_PAGE_SCREENSHOT=true와 CRAWLER_STORE_PDF=true도 사용할 수 있습니다. 필요하지 않다면 모든 방식을 동시에 켜지 마십시오. 디스크 사용량이 눈에 띄게 증가합니다. .env를 변경한 뒤 docker compose up -d를 실행합니다.

보안, 업데이트, 백업

Karakeep 크롤러는 사용자가 저장한 주소를 서버 네트워크에서 엽니다. 따라서 공개 회원가입을 열어 두지 말고 신뢰할 수 있는 사람에게만 접근 권한을 부여하십시오. 기본 SSRF 보호가 있지만 공개 서비스의 경우 공식 프로젝트는 브라우저를 격리하거나 제한된 프록시를 통해 트래픽을 보내도록 권장합니다.

또한 HTTPS와 강력한 비밀번호를 사용하고 포트 3000을 공개하지 않으며 컨테이너를 정기적으로 업데이트하십시오.

cd /opt/karakeep
docker compose up --pull always -d

기본 데이터베이스와 저장한 자료는 data라는 Docker 볼륨에 있습니다. 복사하기 전에 컨테이너를 중지합니다.

mkdir -p /var/backups/karakeep
cd /opt/karakeep
docker compose stop

docker run --rm \
  -v karakeep_data:/source:ro \
  -v /var/backups/karakeep:/backup \
  alpine sh -c 'tar czf /backup/data-$(date +%F).tar.gz -C /source .'

cp .env docker-compose.yml /var/backups/karakeep/
docker compose start

karakeep_data라는 이름은 프로젝트 디렉터리가 /opt/karakeep인 경우를 가정합니다. docker volume ls로 확인할 수 있습니다. Meilisearch 검색 색인은 다시 만들 수 있지만 큰 라이브러리라면 karakeep_meilisearch 볼륨도 백업해 두는 것이 좋습니다.

/var/backups/karakeep의 아카이브를 다른 서버, NAS 또는 오브젝트 스토리지로 전송하십시오. 같은 VPS에 있는 사본은 디스크 장애나 가상 머신 삭제로부터 보호하지 못합니다.

Karakeep에 적합한 VPS 선택하기

Ollama를 사용하지 않는 개인 라이브러리에는 2 vCPU, 2GB RAM, 20~30GB NVMe를 갖춘 Linux VPS가 적합합니다. 대규모 가져오기, 여러 사용자, 전체 아카이빙을 위해서는 4GB RAM과 더 큰 디스크를 선택하십시오.

Karakeep은 tropic.host의 VPS에서 실행할 수 있습니다. 고정 IP는 도메인 연결을 간단하게 만들고 NVMe는 SQLite, 검색 색인, 많은 작은 파일을 처리하는 데 유용합니다. 아카이브가 커지면 리소스를 늘릴 수 있습니다.

로컬 Ollama 리소스는 별도로 계산하십시오. 작은 언어 모델도 Karakeep의 전체 기본 스택보다 더 많은 메모리를 요구할 수 있습니다.

결론

Karakeep은 흩어진 링크를 검색 가능한 개인 라이브러리로 바꿉니다. 페이지, 메모, 이미지, PDF를 저장하고 OCR, 목록, 확장 프로그램, 모바일 앱, 선택형 AI 태깅을 지원합니다.

시작에는 소형 VPS, Docker Compose, 도메인, HTTPS만 있으면 됩니다. 설치 후에는 회원가입을 닫고 디스크 사용량을 관리하며 외부 백업을 보관하십시오.

FAQ

Karakeep은 무료인가요?

셀프 호스팅 버전은 오픈 소스이며 필수 구독이 없습니다. VPS, 도메인, 백업 스토리지와 필요할 경우 외부 AI API 비용을 지불하면 됩니다.

Karakeep을 사용하려면 API 키가 필요한가요?

아닙니다. AI 없이도 자료 저장과 색인, 목록, 메모, OCR, 전문 검색이 작동합니다. 모델은 자동 태그, 요약 및 관련 기능에 필요합니다.

Karakeep에는 RAM이 얼마나 필요한가요?

Ollama 없이 한 명이 사용할 때의 실용적인 시작점은 2GB RAM입니다. 대규모 가져오기, 여러 사용자, 활발한 처리에는 4GB가 더 편리합니다.

브라우저나 Pocket에서 북마크를 가져올 수 있나요?

네. 브라우저의 표준 북마크 HTML 파일, Pocket, Omnivore 및 여러 다른 형식을 지원합니다. 가져온 뒤 Karakeep이 페이지를 처리하고 검색에 추가합니다.

원본 사이트가 사라져도 글이 남아 있나요?

Karakeep은 추출한 본문과 스크린샷을 저장하며 전체 아카이빙을 켜면 로컬 사본이나 PDF도 보관합니다. 로그인이 필요한 페이지와 복잡한 웹 애플리케이션은 일부만 저장될 수 있습니다.