Vikunja: Todoist/TickTick 대안 오픈소스 할 일 관리 앱 Docker 설치 가이드 ⋆ Blog * JackerLab

개요

Vikunja는 EU에서 개발 및 호스팅되는 오픈소스 할 일 관리 애플리케이션입니다. AGPLv3 라이선스로 배포되며, Todoist, TickTick, Microsoft To-Do의 셀프호스팅 대안입니다. 개인 할 일 목록부터 팀 프로젝트 관리까지 유연하게 활용 가능하며, 프라이버시를 중시하는 사용자에게 적합합니다.

Vikunja의 핵심 철학

Vikunja는 “프라이버시와 데이터 소유권”을 최우선으로, 사용자의 할 일 목록이나 메타데이터를 절대 판매하지 않습니다. 오픈소스이므로 코드를 직접 검토할 수 있으며, Raspberry Pi에서도 실행 가능할 만큼 가볍습니다.

주요 특징

기능	설명
프로젝트 관리	계층형 프로젝트/서브프로젝트
다중 뷰	List, Kanban, Gantt, Table 뷰
할 일 관리	하위 작업, 우선순위, 마감일
반복 작업	일간/주간/월간 반복 설정
라벨	색상 태그로 분류
알림	마감일 리마인더
팀 협업	프로젝트 공유, 담당자 할당
첨부 파일	파일 업로드
댓글	작업별 토론
Quick Add Magic	자연어로 빠른 작업 추가
CalDAV	외부 캘린더 앱 연동
가져오기	Todoist, Trello, Microsoft To-Do
앱 지원	웹, 데스크톱, 모바일

Quick Add Magic 기능

자연어로 작업을 빠르게 추가:

입력 예시	결과
`내일 보고서 작성`	마감일: 내일
`매주 월요일 회의 준비`	반복: 매주 월요일
`#업무 프레젠테이션 준비`	라벨: 업무
`@김철수 코드 리뷰`	담당자: 김철수
`!1 긴급 버그 수정`	우선순위: 높음

할 일 앱 비교

기능	Vikunja	Todoist	TickTick	MS To-Do
오픈소스	✅	❌	❌	❌
셀프호스팅	✅	❌	❌	❌
무료 프로젝트	무제한	5개	9개	무제한
Kanban 뷰	✅	유료	✅	❌
Gantt 차트	✅	❌	유료	❌
반복 작업	✅	✅	✅	✅
팀 협업	✅	유료	유료	제한적
CalDAV	✅	❌	❌	❌
첨부 파일	✅	유료	유료	✅
데이터 소유권	✅	❌	❌	❌

시스템 요구 사항

항목	최소 사양	권장 사양
RAM	256MB	512MB 이상
CPU	1 코어	2 코어
저장소	1GB	5GB 이상
Docker	20.10+	최신 버전

Vikunja는 매우 가벼워서 Raspberry Pi에서도 원활하게 실행됩니다.

Docker Compose 설치

방법 1: 간단 설치 (SQLite)

mkdir -p ~/vikunja && cd ~/vikunja
mkdir -p files db
sudo chown -R 1000:1000 files db

docker-compose.yml:

version: "3.8"

services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    ports:
      - "3456:3456"
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://localhost:3456
      VIKUNJA_SERVICE_TIMEZONE: Asia/Seoul
    volumes:
      - ./files:/app/vikunja/files
      - ./db:/db

방법 2: PostgreSQL 구성 (프로덕션 권장)

.env 파일:

# 도메인 설정
VIKUNJA_SERVICE_PUBLICURL=https://vikunja.yourdomain.com
VIKUNJA_SERVICE_TIMEZONE=Asia/Seoul

# PostgreSQL
POSTGRES_USER=vikunja
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=vikunja

# 이메일 설정 (선택사항)
VIKUNJA_MAILER_ENABLED=true
VIKUNJA_MAILER_HOST=smtp.example.com
VIKUNJA_MAILER_PORT=587
VIKUNJA_MAILER_USERNAME=your-email@example.com
VIKUNJA_MAILER_PASSWORD=your-email-password
VIKUNJA_MAILER_FROMEMAIL=vikunja@example.com

# 사용자 등록
VIKUNJA_SERVICE_ENABLEREGISTRATION=true

docker-compose.yml:

version: "3.8"

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

  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    ports:
      - "3456:3456"
    environment:
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: vikunja-db
      VIKUNJA_DATABASE_DATABASE: ${POSTGRES_DB}
      VIKUNJA_DATABASE_USER: ${POSTGRES_USER}
      VIKUNJA_DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      VIKUNJA_SERVICE_PUBLICURL: ${VIKUNJA_SERVICE_PUBLICURL}
      VIKUNJA_SERVICE_TIMEZONE: ${VIKUNJA_SERVICE_TIMEZONE}
      VIKUNJA_SERVICE_ENABLEREGISTRATION: ${VIKUNJA_SERVICE_ENABLEREGISTRATION:-true}
      VIKUNJA_MAILER_ENABLED: ${VIKUNJA_MAILER_ENABLED:-false}
      VIKUNJA_MAILER_HOST: ${VIKUNJA_MAILER_HOST:-}
      VIKUNJA_MAILER_PORT: ${VIKUNJA_MAILER_PORT:-}
      VIKUNJA_MAILER_USERNAME: ${VIKUNJA_MAILER_USERNAME:-}
      VIKUNJA_MAILER_PASSWORD: ${VIKUNJA_MAILER_PASSWORD:-}
      VIKUNJA_MAILER_FROMEMAIL: ${VIKUNJA_MAILER_FROMEMAIL:-}
    volumes:
      - vikunja-files:/app/vikunja/files
    depends_on:
      vikunja-db:
        condition: service_healthy
    networks:
      - vikunja-network

volumes:
  vikunja-db-data:
  vikunja-files:

networks:
  vikunja-network:
    driver: bridge

Traefik 리버스 프록시 설정

version: "3.8"

services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    environment:
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: vikunja-db
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: your_secure_password
      VIKUNJA_SERVICE_PUBLICURL: https://vikunja.yourdomain.com
    volumes:
      - vikunja-files:/app/vikunja/files
    networks:
      - vikunja-network
      - traefik-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vikunja.rule=Host(`vikunja.yourdomain.com`)"
      - "traefik.http.routers.vikunja.entrypoints=websecure"
      - "traefik.http.routers.vikunja.tls.certresolver=myresolver"
      - "traefik.http.services.vikunja.loadbalancer.server.port=3456"

실행

docker-compose up -d

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

# 상태 확인
docker-compose ps

초기 설정

1) 웹 접속

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

2) 계정 생성

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

3) 첫 프로젝트 생성

좌측 + New project 클릭
프로젝트 이름 입력
색상 선택 (선택사항)

CLI로 사용자 생성

Docker 환경에서 CLI로 사용자 생성:

docker exec vikunja /app/vikunja/vikunja user create \
  -e user@example.com \
  -p 'YourPassword!' \
  -u username

주요 기능 활용

뷰 타입 전환

뷰	용도	전환 방법
List	클래식 할 일 목록	기본 뷰
Kanban	상태별 카드 관리	프로젝트 > 뷰 전환
Gantt	타임라인 시각화	프로젝트 > 뷰 전환
Table	상세 속성 편집	프로젝트 > 뷰 전환

할 일 속성

할 일 항목:
├── 제목 (필수)
├── 설명 (마크다운 지원)
├── 마감일
├── 우선순위 (1-5)
├── 라벨 (다중 선택)
├── 담당자 (팀 협업 시)
├── 첨부 파일
├── 하위 작업
├── 반복 설정
├── 알림
└── 관계 (다른 할 일과 연결)

프로젝트 공유

프로젝트 설정 > Share
공유 방법 선택:
- User: 특정 사용자에게 공유
- Team: 팀에 공유
- Link: 공개 링크 생성 (읽기/쓰기 권한 선택)

필터 활용

프로젝트 > Filter 버튼:
- 마감일 기준
- 우선순위 기준
- 라벨 기준
- 담당자 기준
- 완료 상태

CalDAV 연동

외부 캘린더 앱(Thunderbird, Apple Calendar 등)과 연동:

CalDAV URL: https://vikunja.yourdomain.com/dav/
사용자명: vikunja 사용자명
비밀번호: vikunja 비밀번호

데이터 가져오기

Todoist에서 가져오기

Todoist > 설정 > 백업 > 데이터 내보내기
Vikunja > 설정 > Import > Todoist
ZIP 파일 업로드

Trello에서 가져오기

Trello 보드 > 메뉴 > Export to JSON
Vikunja > 설정 > Import > Trello
JSON 파일 업로드

Microsoft To-Do에서 가져오기

Vikunja > 설정 > Import > Microsoft To-Do
Microsoft 계정 연결
가져올 리스트 선택

알림 설정

이메일 알림

환경 변수로 SMTP 설정:

VIKUNJA_MAILER_ENABLED=true
VIKUNJA_MAILER_HOST=smtp.gmail.com
VIKUNJA_MAILER_PORT=587
VIKUNJA_MAILER_USERNAME=your-email@gmail.com
VIKUNJA_MAILER_PASSWORD=your-app-password
VIKUNJA_MAILER_FROMEMAIL=vikunja@yourdomain.com

CalDAV 앱을 통한 알림

CalDAV를 지원하는 앱(Tasks.org, DAVx5)을 사용하면 모바일 알림을 받을 수 있습니다.

트러블슈팅

CORS 오류

VIKUNJA_SERVICE_PUBLICURL이 실제 접속 URL과 일치하는지 확인:

# 올바른 설정
VIKUNJA_SERVICE_PUBLICURL=https://vikunja.yourdomain.com

# CORS 비활성화 (개발용)
VIKUNJA_CORS_ENABLE=false

데이터베이스 연결 실패

# PostgreSQL 연결 테스트
docker-compose exec vikunja-db psql -U vikunja -d vikunja -c "SELECT 1"

# Vikunja 로그 확인
docker-compose logs vikunja | grep -i error

파일 업로드 실패

# 파일 디렉토리 권한 확인
docker exec vikunja ls -la /app/vikunja/files

# 권한 수정 (호스트에서)
sudo chown -R 1000:1000 ./files

마이그레이션 실행

docker exec vikunja /app/vikunja/vikunja migrate

백업 및 복원

SQLite 백업

# 데이터베이스 + 파일 백업
docker run --rm \
  -v vikunja_vikunja-files:/files \
  -v $(pwd):/backup \
  alpine tar czf /backup/vikunja_backup_$(date +%Y%m%d).tar.gz /files

PostgreSQL 백업

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

# 파일 백업
docker run --rm -v vikunja_vikunja-files:/data -v $(pwd):/backup alpine tar czf /backup/files_$(date +%Y%m%d).tar.gz /data

전체 백업 스크립트

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

# PostgreSQL 백업
docker-compose exec -T vikunja-db pg_dump -U vikunja vikunja > $BACKUP_DIR/database.sql

# 파일 백업
docker run --rm -v vikunja_vikunja-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 vikunja

모바일/데스크톱 앱

플랫폼	앱
Web	브라우저에서 직접 접속
Desktop	공식 데스크톱 앱 (Electron)
Android	공식 앱 또는 CalDAV 클라이언트
iOS	CalDAV 클라이언트 (Reminders, Fantastical)

개요