WeKan: 완전 오픈소스 Trello 대안 칸반 보드 Docker 설치 가이드 ⋆ Blog * JackerLab

개요

WeKan(구 LibreBoard)은 MIT 라이선스로 배포되는 완전 오픈소스 칸반 보드 애플리케이션입니다. 전 세계 대부분의 국가에서 사용되며, 최대 사용자는 30,000명 규모의 기업에서 활용하고 있습니다. 105개 이상의 언어로 번역되어 글로벌 팀에서도 활용 가능하며, Meteor 프레임워크로 구축되어 실시간 동기화를 지원합니다.

WeKan의 핵심 철학

WeKan은 “완전한 오픈소스와 데이터 주권”을 최우선으로, 사용자가 자신의 데이터를 완벽하게 통제할 수 있도록 설계되었습니다. Trello의 유료화 제한(2024년 4월부터 무료 사용자 10명 제한)에 대한 대안으로 많은 팀이 WeKan으로 전환하고 있습니다.

주요 특징

기능	설명
칸반 보드	드래그 앤 드롭 카드 관리
Swimlanes	가로 행으로 작업 분류
실시간 동기화	모든 사용자에게 즉시 반영
커스텀 필드	사용자 정의 속성 추가
체크리스트	하위 작업 관리
라벨	색상 태그로 분류
마감일	기한 설정 및 알림
첨부 파일	파일 업로드
댓글	카드별 토론
활동 로그	상세한 변경 이력
권한 관리	보드/사용자별 접근 제어
API	REST API 지원
Webhook	외부 서비스 연동
Trello 가져오기	Trello JSON 직접 임포트

Trello vs WeKan 비교

기능	WeKan	Trello (무료)	Trello (유료)
오픈소스	✅	❌	❌
셀프호스팅	✅	❌	❌
무제한 보드	✅	10개	✅
무제한 멤버	✅	10명	✅
무제한 파워업	✅	1개	✅
커스텀 필드	✅	❌	✅
체크리스트	✅	✅	✅
첨부 용량	무제한*	10MB	250MB
Swimlanes	✅	❌	❌
API	✅	✅	✅
데이터 소유권	✅	❌	❌

*서버 저장소에 따라 다름

시스템 요구 사항

항목	최소 사양	권장 사양 (수천 사용자)
RAM	1GB	4GB+
CPU	1 코어	2+ 코어
저장소	5GB	20GB+
MongoDB	5.0+	5.0+
Docker	20.10+	최신 버전

Docker Compose 설치

기본 설치

mkdir -p ~/wekan && cd ~/wekan

.env 파일:

# WeKan 설정
ROOT_URL=http://localhost:8080
MONGO_URL=mongodb://wekan-db:27017/wekan

# 이메일 설정 (선택사항)
MAIL_URL=smtp://user:pass@smtp.example.com:587/
MAIL_FROM=WeKan <wekan@example.com>

# 기능 설정
WITH_API=true
RICHER_CARD_COMMENT_EDITOR=true
BROWSER_POLICY_ENABLED=true

# 사용자 등록 (false = 관리자만 사용자 생성 가능)
ACCOUNTS_LOCKOUT_KNOWN_USERS_FAILURES_BEFORE=3

docker-compose.yml:

version: "3.8"

services:
  wekan-db:
    image: mongo:5.0
    container_name: wekan-db
    restart: unless-stopped
    command: mongod --logpath /dev/null --oplogSize 128 --quiet
    volumes:
      - wekan-db-data:/data/db
    networks:
      - wekan-network
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5

  wekan:
    image: quay.io/wekan/wekan:latest
    container_name: wekan
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      MONGO_URL: ${MONGO_URL}
      ROOT_URL: ${ROOT_URL}
      WITH_API: ${WITH_API:-true}
      RICHER_CARD_COMMENT_EDITOR: ${RICHER_CARD_COMMENT_EDITOR:-true}
      BROWSER_POLICY_ENABLED: ${BROWSER_POLICY_ENABLED:-true}
      WRITABLE_PATH: /data
    volumes:
      - wekan-files:/data
    depends_on:
      wekan-db:
        condition: service_healthy
    networks:
      - wekan-network
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "10"

volumes:
  wekan-db-data:
  wekan-files:

networks:
  wekan-network:
    driver: bridge

Traefik 리버스 프록시 설정

version: "3.8"

services:
  wekan-db:
    image: mongo:5.0
    container_name: wekan-db
    restart: unless-stopped
    command: mongod --logpath /dev/null --oplogSize 128 --quiet
    volumes:
      - wekan-db-data:/data/db
    networks:
      - wekan-network

  wekan:
    image: quay.io/wekan/wekan:latest
    container_name: wekan
    restart: unless-stopped
    environment:
      MONGO_URL: mongodb://wekan-db:27017/wekan
      ROOT_URL: https://wekan.yourdomain.com
      WITH_API: "true"
      WRITABLE_PATH: /data
    volumes:
      - wekan-files:/data
    depends_on:
      - wekan-db
    networks:
      - wekan-network
      - traefik-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.wekan.rule=Host(`wekan.yourdomain.com`)"
      - "traefik.http.routers.wekan.entrypoints=websecure"
      - "traefik.http.routers.wekan.tls.certresolver=myresolver"
      - "traefik.http.services.wekan.loadbalancer.server.port=8080"

volumes:
  wekan-db-data:
  wekan-files:

networks:
  wekan-network:
    driver: bridge
  traefik-network:
    external: true

Caddy 리버스 프록시 설정

Caddyfile:

wekan.yourdomain.com {
    reverse_proxy wekan:8080
}

실행

docker-compose up -d

# 로그 확인
docker-compose logs -f wekan

# 상태 확인
docker-compose ps

초기 설정

1) 웹 접속

브라우저에서 http://localhost:8080으로 접속합니다.

2) 첫 사용자 등록

첫 번째 등록 사용자가 자동으로 관리자 권한을 받습니다.

Register 클릭
이메일, 사용자명, 비밀번호 입력
계정 생성 완료

3) 관리자 설정

관리자 패널 접근: 우측 상단 프로필 > Admin Panel

설정 가능 항목:

사용자 관리 (추가/제거/권한)
글로벌 설정
등록 허용/차단
이메일 설정

Trello에서 마이그레이션

1) Trello 데이터 내보내기

Trello 보드 > 메뉴 > More > Print and Export > Export to JSON
JSON 파일 다운로드

2) 첨부 파일 다운로드 (선택사항)

Trello Attachments Downloader 사용:

# Trello 첨부 파일 일괄 다운로드
python trello-attachments-downloader.py your-trello-export.json

3) WeKan으로 가져오기

WeKan 보드 목록 > Import 버튼
Trello 선택
JSON 파일 업로드
가져오기 완료

주요 기능 활용

보드 구조

Board (보드)
├── List 1 (리스트)
│   ├── Card A (카드)
│   │   ├── Description (설명)
│   │   ├── Checklist (체크리스트)
│   │   ├── Labels (라벨)
│   │   ├── Due Date (마감일)
│   │   └── Attachments (첨부)
│   └── Card B
├── List 2
└── Swimlane (스윔레인으로 구분)

Swimlanes 활용

Swimlanes는 보드를 가로 행으로 나누어 작업을 그룹화합니다:

           | To Do | In Progress | Done |
---------- |-------|-------------|------|
Frontend   | [A]   | [B]         |      |
Backend    | [C]   |             | [D]  |
Design     |       | [E]         | [F]  |

설정 방법:

보드 설정 > Swimlanes
Add Swimlane 클릭
이름 입력 (예: Frontend, Backend, Design)

권한 관리

역할	권한
Admin	모든 권한, 보드 삭제
Normal	카드 생성/수정, 리스트 관리
Comment only	댓글만 가능
Read only	읽기만 가능
No comments	댓글 제외 모든 기능

Webhook 설정

외부 서비스 연동:

# 보드 설정 > Outgoing Webhooks
URL: https://your-webhook-endpoint.com/hook
# 이벤트 발생 시 POST 요청 전송

API 활용

# API 활성화 확인 (WITH_API=true)

# 로그인하여 토큰 받기
curl -X POST http://localhost:8080/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"yourpassword"}'

# 보드 목록 조회
curl http://localhost:8080/api/boards \
  -H "Authorization: Bearer YOUR_TOKEN"

트러블슈팅

MongoDB 연결 실패

# MongoDB 상태 확인
docker-compose exec wekan-db mongosh --eval "db.adminCommand('ping')"

# MongoDB 로그 확인
docker-compose logs wekan-db

보드 로딩 안됨

# WeKan 로그 확인
docker-compose logs wekan | grep -i error

# MongoDB 데이터 확인
docker-compose exec wekan-db mongosh wekan --eval "db.boards.count()"

실시간 동기화 안됨

WebSocket 연결 확인
리버스 프록시 WebSocket 설정 확인
ROOT_URL 설정이 실제 접속 URL과 일치하는지 확인

성능 최적화

# 대규모 사용자를 위한 설정
services:
  wekan:
    environment:
      # 캐싱 최적화
      MONGO_POOL_SIZE: 10
      # 이미지 압축
      MAX_IMAGE_PIXEL: 1024
      IMAGE_COMPRESS_RATIO: 80

백업 및 복원

MongoDB 백업

# 백업
docker-compose exec wekan-db mongodump --db wekan --out /dump
docker cp wekan-db:/dump ./backup_$(date +%Y%m%d)

# 복원
docker cp ./backup_20240101 wekan-db:/dump
docker-compose exec wekan-db mongorestore --db wekan /dump/wekan

전체 백업 스크립트

#!/bin/bash
BACKUP_DIR="/backups/wekan/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# MongoDB 덤프
docker-compose exec -T wekan-db mongodump --db wekan --archive > $BACKUP_DIR/wekan.archive

# 파일 볼륨 백업
docker run --rm -v wekan_wekan-files:/data -v $BACKUP_DIR:/backup alpine tar czf /backup/files.tar.gz /data

echo "Backup completed: $BACKUP_DIR"

업그레이드

# 백업 먼저 수행
./backup.sh

# 최신 이미지 가져오기
docker-compose pull

# 재시작
docker-compose down
docker-compose up -d

# 로그 확인
docker-compose logs -f wekan

주의: WeKan은 최신 버전만 지원됩니다. 보안을 위해 항상 최신 버전으로 업데이트하세요.

개요