- TypeScript 96%
- JavaScript 1.8%
- Nix 1.2%
- CSS 0.9%
- Dockerfile 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .claude | ||
| .forgejo/workflows | ||
| .trail | ||
| apps | ||
| docs | ||
| e2e | ||
| nix | ||
| packages/shared | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .envrc | ||
| .gitattributes | ||
| .gitignore | ||
| .nvmrc | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| compose.prod.yaml | ||
| compose.yaml | ||
| flake.lock | ||
| flake.nix | ||
| lefthook.yml | ||
| LICENSE | ||
| opencode.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| skills-lock.json | ||
| tsconfig.base.json | ||
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/caldavand/.well-known/carddavfor 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
.icsand.vcffiles from Settings. - The web app in English, Catalan, Spanish, French and German.
- An MCP server at
/mcpso AI agents can work with your calendars, contacts and tasks. Agents sign in with OAuth and can be disconnected in Settings. It needsPUBLIC_URL. - Admin pages and a
kally-admincommand 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, FullCalendarapps/api: Fastify, one process serving the JSON API, the DAV server and the built web app; Drizzle overpg,ioredis,openid-clientpackages/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
- Installation
- Development
- Deployment
- Architecture
- Decisions and release notes
- Privacy policy and
terms of service of
calendar.cumsek.com, served at
/privacyand/termsnext to a public home page at/home; another private install can start from them
License
kally is free software under the GNU General Public License, version 3 or (at your option) any later version. See LICENSE.