No description
  • TypeScript 96%
  • JavaScript 1.8%
  • Nix 1.2%
  • CSS 0.9%
  • Dockerfile 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 01:30:37 +01:00
.claude chore: install the TanStack Hotkeys agent skills 2026-11-10 00:20:18 +01:00
.forgejo/workflows test: add a browser end-to-end path against the built server 2026-11-09 22:35:25 +01:00
.trail docs(trail): record why an unwalkable series is shown at its start 2026-11-17 00:41:14 +01:00
apps refactor(store): name new collections by the shared CollectionListKind 2026-11-17 00:57:49 +01:00
docs Merge main into refactor/untangle 2026-11-17 01:07:54 +01:00
e2e refactor(e2e): take the dev service addresses from the module the API tests use 2026-11-17 00:57:49 +01:00
nix docs: layout, ADRs 0015-0019 and 0.2.0 notes after the refactor 2026-11-16 22:24:22 +01:00
packages/shared refactor: decide what an owner may do with a collection once, in shared 2026-11-17 00:57:42 +01:00
.dockerignore chore: remove Radicale from dev tooling and make compose work from nothing 2026-11-09 21:36:05 +01:00
.editorconfig chore: scaffold workspace, shared contract and dev Radicale 2026-11-07 12:48:59 +01:00
.env.example refactor: build the dev proxy from the server's own prefixes 2026-11-16 23:51:16 +01:00
.envrc chore: add Docker, compose profiles, Nix flake, Trail, CI and docs 2026-11-07 12:57:26 +01:00
.gitattributes chore: scaffold workspace, shared contract and dev Radicale 2026-11-07 12:48:59 +01:00
.gitignore test: add a browser end-to-end path against the built server 2026-11-09 22:35:25 +01:00
.nvmrc fix: run on Node 26 so concurrent photo requests stop crashing the API 2026-11-07 17:00:07 +01:00
AGENTS.md docs: layout, ADRs 0015-0019 and 0.2.0 notes after the refactor 2026-11-16 22:24:22 +01:00
biome.json refactor(api): enter ical.js through one patched module 2026-11-16 19:29:57 +01:00
CLAUDE.md chore: add Docker, compose profiles, Nix flake, Trail, CI and docs 2026-11-07 12:57:26 +01:00
compose.prod.yaml fix(deploy): bind dev Postgres and Valkey to loopback, cap Valkey memory 2026-11-13 13:24:13 +01:00
compose.yaml fix(deploy): bind dev Postgres and Valkey to loopback, cap Valkey memory 2026-11-13 13:24:13 +01:00
flake.lock chore(nix): drop trail-code from the dev shell 2026-11-14 02:39:07 +01:00
flake.nix chore(nix): drop trail-code from the dev shell 2026-11-14 02:39:07 +01:00
lefthook.yml chore: add Docker, compose profiles, Nix flake, Trail, CI and docs 2026-11-07 12:57:26 +01:00
LICENSE chore: license under GPL-3.0-or-later 2026-11-07 15:31:52 +01:00
opencode.json chore: add Docker, compose profiles, Nix flake, Trail, CI and docs 2026-11-07 12:57:26 +01:00
package-lock.json refactor(api): one definition for paths, refusals and image caching 2026-11-16 21:45:52 +01:00
package.json test: add a browser end-to-end path against the built server 2026-11-09 22:35:25 +01:00
README.md refactor: build the dev proxy from the server's own prefixes 2026-11-16 23:51:16 +01:00
skills-lock.json chore: install the TanStack Hotkeys agent skills 2026-11-10 00:20:18 +01:00
tsconfig.base.json chore: scaffold workspace, shared contract and dev Radicale 2026-11-07 12:48:59 +01:00

kally

A self-hosted calendar, contacts and tasks server with a web app. kally is a multi-user CalDAV and CardDAV server in its own right: phones, tablets and desktop apps (DAVx5, Apple Calendar and Contacts, Thunderbird) sync with it directly, and the web app reads and writes the same data. Everything lives in Postgres, so there is one thing to back up.

Status: 0.2.0, in development. Upgrading from 0.1.0 is a breaking change; read the 0.2.0 release notes first.

Features

  • Calendar tab (the default) with month, week and day views, recurring events and per-event time zones.
  • Contacts tab with groups, photos and birthdays, which also show on the calendar. DAV clients and the MCP server get them as a read-only "Birthdays" calendar built from the contacts.
  • Tasks tab for CalDAV tasks (VTODO) with subtasks; tasks with a due date show on the calendar too, where they can be marked done, and the calendar's create dialog makes either an event or a task.
  • A CalDAV and CardDAV server under /dav, with /.well-known/caldav and /.well-known/carddav for client discovery, sync tokens and ETags.
  • Sharing: give another user read or read-write access to a calendar, task list or address book. It appears in their account in every client, with no invitation step.
  • Google calendars: link any number of Google accounts and their calendars show up as Name (account@gmail.com), in the web app and in every DAV client. Edit and share them like any other calendar; changes sync with Google both ways. kally never deletes a calendar in Google: delete it in Google Calendar, or unlink the account to remove all of them from kally. Needs a Google OAuth client (see Deployment).
  • Local password accounts, single sign-on through any number of OpenID Connect providers, or both. Local login can be turned off.
  • Per-device app passwords for DAV clients, shown once and revocable one by one.
  • Import and export of .ics and .vcf files from Settings.
  • The web app in English, Catalan, Spanish, French and German.
  • An MCP server at /mcp so AI agents can work with your calendars, contacts and tasks. Agents sign in with OAuth and can be disconnected in Settings. It needs PUBLIC_URL.
  • Admin pages and a kally-admin command to create, disable and reset accounts.

Not in 0.2.0: scheduling and invitations (iMIP, calendar-auto-schedule), groups of users, SAML, quotas. See Architecture for what the DAV server does and does not do.

Stack

  • TypeScript, npm workspaces, Node 26
  • apps/web: React, Vite, Tailwind CSS, daisyUI, Radix UI, TanStack Query, Router and Hotkeys, FullCalendar
  • apps/api: Fastify, one process serving the JSON API, the DAV server and the built web app; Drizzle over pg, ioredis, openid-client
  • packages/shared: Zod schemas and types used by both sides
  • Postgres 18 as the store, Valkey as a cache that is safe to flush
  • Biome (lint and format), Vitest, lefthook, Nix flake for the dev shell, the package and a NixOS module

Quick start

Needs Docker with Compose v2.24 or newer. This builds the production image and runs it with Postgres and Valkey on http://localhost:8080.

cp .env.example .env
sed -i.bak "s/^SESSION_SECRET=.*/SESSION_SECRET=$(openssl rand -hex 32)/" .env && rm .env.bak
docker compose --profile app up --build -d --wait
printf '%s' 'a long password' | docker compose --profile app exec -T app \
  kally-admin create-user admin --admin --password-stdin

kally will not start with the placeholder SESSION_SECRET that compose falls back to, so the second line matters.

Open http://localhost:8080 and sign in as admin. The app profile runs the migrations before kally starts; kally never migrates on its own.

To run it for real, behind TLS on a server, see Deployment: compose.prod.yaml for Docker and a module for NixOS.

Connect a phone or desktop app

DAV clients cannot sign in through a browser, and they never get your account password. In the web app open Settings, then Connections, and create an app password for the device. It is shown once. Then give the client:

Field Value
Server https://cal.example.com/dav/ (the host name alone also works, see below)
Username Your kally username
Password The app password, which looks like kally_abcdefgh_...
  • DAVx5 (Android): add an account, choose "Login with URL and user name", and enter the three values above.
  • Apple devices: Settings, Calendar (or Contacts), Accounts, Add Account, Other, then Add CalDAV (or CardDAV) Account.
  • Thunderbird: New Calendar, "On the Network", CalDAV; for contacts add a CardDAV address book.

Clients that discover a server from its host name follow /.well-known/caldav and /.well-known/carddav to /dav/; a reverse proxy has to pass those paths through, see Deployment. Changing the account password revokes every app password, so devices need a new one afterwards.

Subscribe to a calendar as an .ics feed

Apps that only read a published .ics URL (a wall display such as TRMNL, a dashboard, a read-only subscription) can fetch a calendar as one iCalendar file from its feed URL, https://<host>/dav/f/<username>/<calendar id>. In the web app, Settings, then Connections, lists the feed URL of every calendar you see, shared ones and Birthdays included, with a button to copy it. The URL keeps working when the calendar is renamed.

Give the app its own app password so you can revoke it alone, and send it as a Basic Authorization header:

curl -u alice:kally_abcdefgh_... https://cal.example.com/dav/f/alice/0193f1c2-...

For an app that takes raw headers, the value is Basic followed by the base64 of username:app-password. Responses carry an ETag, so a poller that sends If-None-Match gets a 304 until the calendar changes. A GET on a calendar's CalDAV URL returns the same file, as Radicale did.

Other ways to run it for development

Each path ends with the app on http://localhost:5173 and the accounts alice and bob (the password equals the username), seeded with sample data. These accounts are for local development only.

Docker

Needs Docker with Compose v2.24 or newer. Nothing else.

cp .env.example .env
sed -i.bak "s/^SESSION_SECRET=.*/SESSION_SECRET=$(openssl rand -hex 32)/" .env && rm .env.bak
docker compose --profile all up --build -d
docker compose exec api npm run seed

Open http://localhost:5173 and sign in as alice / alice.

Local npm

Needs Node 26 (see .nvmrc) and Docker for Postgres and Valkey.

cp .env.example .env
sed -i.bak "s/^SESSION_SECRET=.*/SESSION_SECRET=$(openssl rand -hex 32)/" .env && rm .env.bak
npm ci
docker compose --profile db up -d --wait
npm run db:migrate -w apps/api
npm run seed
npm run dev

Open http://localhost:5173 and sign in as alice / alice.

Nix

Needs Nix with flakes enabled. The dev shell provides Node 26, Docker Compose, Postgres 18, Valkey, Biome, lefthook and the browsers the end-to-end test uses.

nix develop            # or: direnv allow
cp .env.example .env
sed -i.bak "s/^SESSION_SECRET=.*/SESSION_SECRET=$(openssl rand -hex 32)/" .env && rm .env.bak
npm ci
docker compose --profile db up -d --wait
npm run db:migrate -w apps/api
npm run seed
npm run dev

Open http://localhost:5173 and sign in as alice / alice.

Environment variables

Copy .env.example to .env; the file documents every variable. The API reads the first group below. nix/module.nix has an option for each of them except NODE_ENV and WEB_DIST_DIR, which the module and the package set themselves.

Name What it is for Example
NODE_ENV Runtime mode development
HOST API bind address 0.0.0.0
PORT API port; the web app, JSON API and DAV server share it 8080
LOG_LEVEL API log level info
DATABASE_URL Postgres 18 connection string. Required postgres://kally:kally@localhost:5433/kally
DATABASE_POOL_MAX Largest number of Postgres connections per API process 10
VALKEY_URL Valkey connection string. Required; kally only slows down while it is empty or down redis://localhost:6380
SESSION_SECRET 32 random bytes as 64 hex chars. Keys the session cookie, stored Google tokens and the app password cache; rotating it logs everyone out and stops Google sync until the accounts are linked again. Required output of openssl rand -hex 32
SESSION_MAX_AGE_SECONDS How long a login stays valid 604800
COOKIE_SECURE Mark the session cookie Secure (defaults to true when NODE_ENV=production) false
TRUST_PROXY Trust X-Forwarded-* headers; set true behind a reverse proxy false
WEB_DIST_DIR When set, the API also serves the built web app from this directory; the image sets it unset
PUBLIC_URL The origin users reach kally at, no path; needed by OIDC, Google and MCP, and the DAV address Settings shows https://cal.example.com
LOCAL_LOGIN_ENABLED Allow username and password login on the web true
OIDC_PROVIDERS Comma-separated single sign-on provider ids company
OIDC_<ID>_ISSUER The provider's issuer URL, one set of four per id; https:// in production https://id.example.com/realms/main
OIDC_<ID>_CLIENT_ID Client id registered at the provider kally
OIDC_<ID>_CLIENT_SECRET Client secret registered at the provider secret
OIDC_<ID>_NAME Name on the login button Company SSO
GOOGLE_CLIENT_ID OAuth client id that lets users link Google accounts; needs PUBLIC_URL 1234-abcd.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET Secret of that OAuth client secret
GOOGLE_SYNC_INTERVAL_SECONDS How often each linked Google account is pulled 300
API_URL Where the Vite dev server proxies /api, /dav, /mcp and /.well-known to http://localhost:8080
KALLY_IMAGE compose.prod.yaml only: the image to run. Required kally:0.2.0
POSTGRES_PASSWORD compose.prod.yaml only: password of the Postgres kally role. Required output of openssl rand -hex 24
KALLY_PORT compose.prod.yaml only: loopback port kally is published on 8080
COMPOSE_DATABASE_URL compose.yaml only: Postgres address for migrate, api and app postgres://kally:kally@host.docker.internal:5433/kally
COMPOSE_VALKEY_URL compose.yaml only: Valkey address for api and app redis://host.docker.internal:6380
COMPOSE_API_URL compose.yaml only: API address for the web service http://host.docker.internal:8080
COMPOSE_POSTGRES_PORT compose.yaml only: host port for Postgres, bound to 127.0.0.1 5433
COMPOSE_VALKEY_PORT compose.yaml only: host port for Valkey, bound to 127.0.0.1 6380
COMPOSE_API_PORT compose.yaml only: host port for the API and the app image 8080
COMPOSE_WEB_PORT compose.yaml only: host port for the web dev server 5173
TEST_DATABASE_URL API tests only: Postgres to create test databases in postgres://kally:kally@localhost:5433/kally
TEST_VALKEY_URL API tests only: Valkey for test key prefixes redis://localhost:6380

Commands

Command What it does
npm run dev API and web dev servers together (API on 8080, web on 5173)
npm run build Build shared, web and API (apps/web/dist, apps/api/dist)
npm start Run the built API (node apps/api/dist/main.js)
npm test All workspace tests; the API tests need Postgres and Valkey
npm run typecheck Typecheck every workspace
npm run lint biome check .
npm run format biome format --write .
npm run format:check biome format .
npm run db:migrate -w apps/api Apply pending migrations (kally-migrate in the image and Nix package)
npm run seed Create accounts and sample data for alice and bob
npm run admin -w apps/api -- <command> kally-admin: create, reset, disable and list accounts
nix build .#kally Build the Nix package (result/bin/kally, kally-migrate, kally-admin)
nix flake check Build the NixOS module's VM test (Linux with KVM)
docker compose --profile all up Postgres, Valkey, migrations, API and web dev server in Docker
docker compose --profile app up --build Production-like single image with Postgres and Valkey

Layout

.
+- apps/
|  +- api/              Fastify service, Drizzle migrations, Dockerfile (dev and runtime targets)
|  +- web/              React SPA (Vite), Dockerfile (dev target)
+- packages/
|  +- shared/           Zod schemas and types shared by api and web
+- docs/                installation, development, deployment, architecture, decisions, releases
+- compose.yaml         dev services behind profiles
+- compose.prod.yaml    example deployment of the app image
+- nix/                 Nix package, NixOS module and its VM test
+- flake.nix            dev shell, packages.kally, nixosModules.kally
+- AGENTS.md            instructions for coding agents (CLAUDE.md links here)

Docs

License

kally is free software under the GNU General Public License, version 3 or (at your option) any later version. See LICENSE.