TL;DR

  • Kalkee는 Google Calendar 또는 CalDAV와 동기화하며, 키보드 우선 탐색과 사용자 지정 기능을 제공하는 빠르고 간결한 캘린더 웹 앱임.
  • 주간·월간·여러 날 보기, 단축키 재설정, 테마 설정, 브라우저 내 미리 보기 기능을 제공함.
  • 브라우저 클라이언트는 의존성이 없으며, Docker 또는 네이티브 Node.js 환경에서 실행 가능함.
  • Google Calendar는 OAuth로 연결하고, CalDAV는 서버 또는 캘린더 URL과 계정 정보로 연결하며, 이벤트를 양방향 동기화함.
  • 제공자 인증 정보는 동기화에만 필요하며, 세션은 설정에 따라 AES-256-GCM으로 암호화해 저장함.

Kalkee

  • 빠르고 간결하며 사용자 지정이 가능한 키보드 우선 캘린더 웹 앱임.
  • 재설정 가능한 단축키와 직관적인 탐색을 제공하며, Google Calendar 또는 CalDAV와 동기화함.
  • 테마와 캘린더 보기 예시로 Ochre Forest 주간 보기, Midnight 월간 보기, Ochre Forest 월간 보기가 제시됨.

기능

  • 주간·월간·여러 날 보기에서 키보드만으로 직관적으로 탐색함.
  • 의존성이 없는 브라우저 클라이언트임.
  • 전용 단축키 편집기에서 동작 키를 재설정함.
  • Google Calendar 및 CalDAV 이벤트를 양방향으로 동기화함.
  • 모양 설정과 사전 설정 테마를 사용자 지정함.
  • Docker 및 네이티브 Node.js 배포를 지원함.

로컬에서 실행

  • Node.js 20 이상이 필요하며, 제공자 인증 정보는 동기화에만 필요함.
  • .env.example을 .env로 복사하고, 의존성을 설치한 뒤 애플리케이션을 시작하는 방식으로 실행함.
  • 브라우저에서 http://localhost:3000 을 열면 되며, 연결된 제공자가 없으면 샘플 이벤트가 포함된 로컬 미리 보기 모드로 시작함.
  • CalDAV를 사용하거나 Google 클라이언트 시크릿과 별개의 키를 원한다면 세션 암호화 시크릿을 생성해 .env의 CALENDAR_SESSION_SECRET에 저장함.
  • 암호화 시크릿이 없어도 CalDAV는 작동하지만, 로그인은 서버를 재시작할 때까지만 유지됨.

Google Calendar

  • Google OAuth 웹 클라이언트를 만들고 Google Calendar API를 활성화함.
  • http://localhost:3000을 승인된 리디렉션 URI로 등록하고 .env에 GOOGLE_CLIENT_ID와 GOOGLE_CLIENT_SECRET을 설정함.
  • Kalkee를 재시작한 뒤 Google을 선택해 연결함.
  • 다른 호스트 이름이나 포트를 사용하는 경우 GOOGLE_REDIRECT_URI를 설정하고, 해당 HTTPS URI를 Google Cloud에 정확히 등록함.
  • 스킴, 호스트, 포트, 경로, 끝 슬래시가 모두 일치해야 함.

CalDAV

  • CalDAV를 선택하고 서버 또는 캘린더 URL, 사용자 이름, 비밀번호 또는 앱 비밀번호를 입력함.
  • Kalkee가 사용 가능한 이벤트 캘린더를 찾아 연결할 캘린더를 선택할 수 있게 함.
  • Nextcloud 컬렉션 URL의 예시는 https://cloud.example.com/remote.php/dav/calendars/username/calendar-name/ 임.
  • 현재 CalDAV 기본 인증(Basic authentication)을 사용하며, HTTPS 사용과 앱 전용 비밀번호 조합을 전제로 함.
  • 일반 HTTP는 localhost에서만 허용되며, 개발 환경에서 CALDAV_ALLOW_HTTP=1을 명시적으로 설정하면 예외적으로 사용할 수 있음.

Docker로 실행

  • .env.example을 .env로 복사하고 docker compose up --build -d로 애플리케이션을 실행함.
  • 앱은 http://localhost:3000 에서 이용 가능하며, 암호화된 캘린더 세션은 컨테이너 파일 시스템이 아니라 kalkee-data Docker 볼륨에 저장됨.
  • 다른 포트로 공개하려면 KALKEE_PORT를 설정하고, GOOGLE_REDIRECT_URI를 공개 주소로 설정해 Google에 등록함.
  • 포트 8080 사용 예시는 KALKEE_PORT=8080 docker compose up --build -d임.
  • 유용한 명령은 docker compose logs -f kalkee, docker compose restart kalkee, docker compose down임.

키보드 작업 흐름

  • 기본 키 바인딩은 다음과 같으며, 나열된 모든 키는 설정의 Settings → Shortcuts에서 변경 가능함.
  • 날짜와 시간 이동: H / J / K / L
  • 선택 확정 또는 열기: Enter
  • 이벤트 만들기: N
  • 이벤트 범위 표시: M
  • 이벤트 이동: G
  • 이벤트 시작·종료 시각 조정: S / E
  • 선택한 이벤트 삭제: Delete
  • 오늘로 이동: T
  • 이전·다음 기간: [ / ]
  • 주간·월간·일별 보기: W / V / D
  • 이벤트 검색: /
  • 설정: ,

데이터와 보안

  • 캘린더 이벤트는 연결된 제공자에 남음.
  • OAuth 토큰과 CalDAV 인증 정보는 Node.js 서버에 보관되며, 브라우저에는 HTTP 전용 세션 쿠키가 전달됨.
  • CALENDAR_SESSION_SECRET 또는 Google만 사용하는 구성의 GOOGLE_CLIENT_SECRET이 있으면 세션을 AES-256-GCM으로 암호화함.
  • 암호화된 세션은 무시 대상인 .calendar-sessions.enc 파일 또는 Docker의 /data/sessions.enc에 저장됨.
  • 캘린더 범위는 브라우저 메모리에 캐시되고 인접 기간은 미리 가져옴.
  • 로컬 미리 보기에서 수정한 내용은 브라우저 세션에 남으며 새로고침하면 초기화됨.

개발

  • npm run dev로 개발 서버를 실행하고, npm run check로 검사하며, npm run test:e2e로 엔드투엔드 테스트를 실행함.
  • 포함된 kalkee.service는 현재 체크아웃 경로를 위한 systemd 사용자 유닛 예시이며, 다른 위치에 설치할 때는 경로를 조정해야 함.
  • 취약점 신고 방법은 SECURITY.md에 안내됨.

라이선스

  • MIT 라이선스임.