Linkwarden Docker 설치 가이드: 협업 북마크 관리자 자체 호스팅

---

Linkwarden은 협업 기능을 갖춘 현대적인 북마크 관리자입니다. 단순히 링크를 저장하는 것을 넘어, 각 북마크의 스크린샷, PDF, HTML 아카이브를 자동 생성하여 원본 페이지가 사라져도 콘텐츠를 영구 보존합니다. 팀 협업, 컬렉션 공유, 태그 관리, 전체 텍스트 검색까지 지원하며, AI 기반 자동 태깅도 가능합니다. GitHub Stars 9K+로 빠르게 성장 중입니다.

Linkwarden 주요 특징

Linkwarden은 개인과 팀 모두를 위한 강력한 북마크 솔루션입니다.

아카이브 기능

• 스크린샷: 각 페이지의 자동 스크린샷 저장
• PDF 저장: 페이지를 PDF로 자동 변환
• HTML 아카이브: 단일 HTML 파일로 저장
• 링크 로트 방지: 원본 삭제되어도 콘텐츠 유지

협업 기능

• 컬렉션 (폴더) 구조
• 팀원 초대 및 권한 관리
• 컬렉션별 공유 설정
• 퍼블릭 링크 공유

편의 기능

• 전체 텍스트 검색 (Meilisearch)
• 태그 시스템
• 리더 뷰 (광고 제거)
• 브라우저 확장 (Firefox, Chrome)
• PWA 지원 (모바일 앱처럼 설치)
• REST API
• RSS 피드 (컬렉션별)
• AI 자동 태깅 (Ollama/OpenAI)

사전 요구 사항

• Docker 및 Docker Compose 설치
• 최소 2GB RAM (4GB 권장)
• 10GB 이상 저장 공간 (아카이브용)
• 도메인 (외부 접근 시)

Docker Compose로 Linkwarden 설치

기본 설치

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    container_name: linkwarden-db
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  linkwarden:
    image: ghcr.io/linkwarden/linkwarden:latest
    container_name: linkwarden
    restart: unless-stopped
    depends_on:
      - postgres
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/postgres
      - NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:3000}
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
    volumes:
      - ./data:/data/data

환경 변수 파일

# .env
# PostgreSQL 비밀번호
POSTGRES_PASSWORD=your_secure_postgres_password

# NextAuth 설정
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=$(openssl rand -base64 32)

# Meilisearch (선택)
# MEILI_MASTER_KEY=your_meili_master_key

시크릿 키 생성:

# NEXTAUTH_SECRET 생성
openssl rand -base64 32

설치 및 실행

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

# 공식 파일 다운로드 (선택)
curl -O https://raw.githubusercontent.com/linkwarden/linkwarden/main/docker-compose.yml
curl -L https://raw.githubusercontent.com/linkwarden/linkwarden/main/.env.sample -o ".env"

# 또는 위의 docker-compose.yml 및 .env 직접 생성

# .env 파일 수정 (필수!)
nano .env

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

# 로그 확인
docker compose logs -f linkwarden

# 브라우저에서 접속
# http://localhost:3000
# Sign Up으로 첫 사용자 생성

초기 설정

1. 첫 사용자 생성

1. http://localhost:3000 접속
2. “Sign Up” 클릭
3. 이름, 이메일, 비밀번호 입력 (8자 이상)
4. 계정 생성 완료

2. 회원가입 비활성화 (선택)

첫 사용자 생성 후 추가 가입을 막으려면:

# docker-compose.yml
services:
  linkwarden:
    environment:
      - DISABLE_REGISTRATION=true

# 변경 적용
docker compose up -d

고급 설정

프로덕션 환경 (Meilisearch 포함)

전체 텍스트 검색을 위해 Meilisearch 추가:

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    container_name: linkwarden-db
    restart: always
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

  meilisearch:
    image: getmeili/meilisearch:v1.12
    container_name: linkwarden-search
    restart: always
    environment:
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
    volumes:
      - ./meili_data:/meili_data

  linkwarden:
    image: ghcr.io/linkwarden/linkwarden:latest
    container_name: linkwarden
    restart: always
    depends_on:
      postgres:
        condition: service_healthy
      meilisearch:
        condition: service_started
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/postgres
      - NEXTAUTH_URL=${NEXTAUTH_URL}
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - MEILI_HOST=http://meilisearch:7700
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
      - DISABLE_REGISTRATION=${DISABLE_REGISTRATION:-false}
    volumes:
      - ./data:/data/data

# .env 추가
MEILI_MASTER_KEY=your_secure_meili_master_key

AI 자동 태깅 (OpenAI)

# docker-compose.yml
services:
  linkwarden:
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENAI_MODEL=gpt-4o

AI 자동 태깅 (Ollama – 로컬)

# docker-compose.yml
services:
  ollama:
    image: ollama/ollama
    container_name: linkwarden-ollama
    volumes:
      - ./ollama:/root/.ollama
    # GPU 사용 시
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - capabilities: [gpu]

  linkwarden:
    environment:
      - OLLAMA_HOST=http://ollama:11434
      - OLLAMA_MODEL=phi3:mini-4k

Traefik 연동

# docker-compose.yml
services:
  linkwarden:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.linkwarden.rule=Host(`bookmarks.yourdomain.com`)"
      - "traefik.http.routers.linkwarden.entrypoints=websecure"
      - "traefik.http.routers.linkwarden.tls.certresolver=letsencrypt"
      - "traefik.http.services.linkwarden.loadbalancer.server.port=3000"
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

Nginx Proxy Manager 연동

Nginx Proxy Manager 설정:

• Forward Hostname: linkwarden (컨테이너 이름)
• Forward Port: 3000
• WebSocket 지원 활성화 필수!

브라우저 확장 설정

1. Chrome/Firefox 확장 스토어에서 “Linkwarden” 검색
2. 설치 후 확장 아이콘 클릭
3. 설정:
   • Server URL: https://bookmarks.yourdomain.com
   • 로그인
4. 웹 페이지에서 확장 클릭하여 북마크 추가

관리 명령어

# 로그 확인
docker compose logs -f linkwarden

# 데이터베이스 백업
docker exec linkwarden-db pg_dump -U postgres postgres | gzip > backup_$(date +%Y%m%d).sql.gz

# 아카이브 파일 백업
tar -czf linkwarden_data_$(date +%Y%m%d).tar.gz ./data

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

# 재시작
docker compose restart linkwarden

환경 변수

변수	설명	필수
DATABASE_URL	PostgreSQL 연결 문자열	✅
NEXTAUTH_URL	외부 접근 URL	✅
NEXTAUTH_SECRET	세션 암호화 키	✅
POSTGRES_PASSWORD	DB 비밀번호	✅
MEILI_HOST	Meilisearch URL	❌
MEILI_MASTER_KEY	Meilisearch 키	❌
DISABLE_REGISTRATION	회원가입 비활성화	❌
OPENAI_API_KEY	OpenAI API 키	❌
OLLAMA_HOST	Ollama 서버 URL	❌

문제 해결

검색이 작동하지 않음

Meilisearch 설정 확인:

# Meilisearch 상태 확인
docker compose logs meilisearch

# MEILI_HOST, MEILI_MASTER_KEY 환경변수 확인

리버스 프록시 뒤에서 로그인 실패

NEXTAUTH_URL이 실제 외부 URL과 일치하는지 확인:

# .env
NEXTAUTH_URL=https://bookmarks.yourdomain.com

스토리지 증가

스크린샷과 PDF가 누적되면 용량이 증가합니다. S3 호환 스토리지로 변경 가능:

environment:
  - STORAGE_FOLDER=s3://bucket-name
  - S3_ACCESS_KEY=xxx
  - S3_SECRET_KEY=xxx

마무리

Linkwarden은 단순한 북마크 관리를 넘어 웹 페이지 아카이빙과 협업까지 지원하는 올인원 솔루션입니다. 스크린샷, PDF, HTML 아카이브로 링크 로트를 방지하고, 팀과 함께 컬렉션을 관리할 수 있습니다. Meilisearch 통합으로 빠른 전체 텍스트 검색이 가능하며, AI 자동 태깅으로 정리의 수고를 덜 수 있습니다.

---

참고 링크

• 공식 사이트: https://linkwarden.app
• GitHub: https://github.com/linkwarden/linkwarden
• 문서: https://docs.linkwarden.app
• Docker Hub: https://ghcr.io/linkwarden/linkwarden

---