GitHub - pike00/Kindred: Self-hosted personal CRM — contacts, interactions, reminders, gifts, debts, journaling with CardDAV sync and full-text search

A self-hosted personal CRM for tracking your relationships — contacts, interactions, reminders, gifts, debts, journal entries — with CardDAV sync, full-text search, and a React frontend. Built on the FastAPI full-stack template and deployed to a homelab via Docker Compose behind Traefik.

Why Kindred?

We meet so many people, but keeping track of those connections isn't always easy. Kindred is built to help you stay in touch, remember the little things, and cultivate meaningful relationships. Whether you want to recall a past interaction, track a gift idea, or just get a reminder to text an old friend, Kindred provides a private, self-hosted space to keep your personal network organized without compromising your data privacy.

Quick Start

Get up and running in under 30 seconds using Docker:

docker compose up -d --build

That's it! Your Kindred instance and all necessary services (PostgreSQL, Meilisearch, Redis) will spin up automatically.

Features Showcase

Demo & Screenshots

Captured against the seeded fake-data fixture (just seed-fixed), 1440×900.

Dashboard — stats, "losing touch" queue, and recent interactions:

Contacts list — last-contact decay indicator, tags, and company/role:

Contact detail — timeline of interactions, notes, gifts, and life events with a relationships sidebar:

Interactions feed grouped by date with channel badges:

Reminders:

Calendar — birthdays and life-event anniversaries surfaced per day:

Journal — freeform daily entries with optional mood:

Tags:

Tech Stack

Comparison to other tools

Kindred vs. Monica

Monica is a fantastic and feature-rich personal CRM. However, it can feel heavy to host and navigate. Kindred aims for a lighter, faster, and more modern experience with a streamlined React frontend, native mobile-friendly UI, and fewer external dependencies.

Kindred vs. Notion / Obsidian

While note-taking tools are extremely flexible, they lack the structured reminders, CardDAV syncing, and specialized relationship views (like decaying contact indicators or dedicated interaction timelines) that a purpose-built CRM like Kindred provides out of the box.

Technical Documentation

Detailed Features

Shipped (frontend + backend)

• Contacts — CRUD, favorites, archive, tagging, groups, list/detail views, inline editing
• Interactions — Log calls, texts, emails, in-person meetings, notes per interaction
• Reminders — Scheduled reminders with date/time, per-contact linking
• Tags & Groups — Organize contacts, many-to-many relationships
• Journal — Freeform personal journaling with entries
• Gifts — Track gifts given/received per contact
• Debts — "I owe them" / "they owe me" tracking per contact
• Notes — Freeform notes attached to a contact
• Users & Admin — Signup, login, logout, password recovery, superuser-gated user management
• Dashboard — Stats, "losing touch" suggestions, recent interactions

Backend-only (no UI yet)

These routes are registered and tested at the API level, but have no frontend pages. Either build the UI or remove them when you decide the feature is out of scope.

• addresses, pets, relationships, contact_fields — read-only rendering on the contact detail page, no add/edit UI
• custom_fields — per-contact arbitrary fields
• life_events — birthdays, anniversaries, major events
• import_export — bulk contact import/export (CSV / vCard)
• webhooks — outbound webhook registrations

The Copier template's items module has been removed from the API router (the model + Alembic table remain for now — drop with a dedicated migration if/when desired).

Layout

backend/       FastAPI app, Alembic migrations, pytest suite, Radicale CardDAV bridge
frontend/      React app (Vite), generated OpenAPI client in src/client/
e2e/           Puppeteer end-to-end tests (bun run e2e/*.test.ts)
docs/          architecture.md, DB_SCHEMA.md, HANDOFF.md
compose.yml    Homelab production stack (kindrednet networks, Meilisearch, Redis, ARQ worker)
compose.dev.yml Dev-against-homelab overlay (bind-mounted source, --reload, frontend dev server)
.env           Runtime env vars (gitignored)
.env.sops      Production secrets, encrypted with sops + age

Running the stack

Production (homelab default):

docker compose up -d --build

Dev against the homelab (bind-mounted source, live reload):

docker compose -f compose.dev.yml up -d --build

First boot runs Alembic migrations and creates the admin user from FIRST_SUPERUSER / FIRST_SUPERUSER_PASSWORD in .env.

Testing

Backend (inside the running stack):

docker compose exec backend bash scripts/tests-start.sh

End-to-end (Puppeteer, requires a running stack):

corepack enable
pnpm install
pnpm run e2e

Secrets

Production secrets live in .env.sops, encrypted with age. Rotate with:

EDITOR=vim sops .env.sops

Note: because .env.sops uses the .sops extension (not a format sops auto-detects), you may need --input-type dotenv --output-type dotenv, or temporarily copy to a *.env path for editing.

After rotating FIRST_SUPERUSER_PASSWORD, the change only takes effect on fresh deployments. Existing homelab databases retain the old superuser password until you manually update it (or delete and recreate the user via initial_data.py).

Release & deploy

The release flow is fully local (no GitHub Actions). Run on ares:

just release patch              # cut: cliff CHANGELOG + LLM notes + tag + push + GH release
just build v0.1.0             # build Dockerfile.prod, push to ghcr.io/pike00/kindred
just deploy v0.1.0                # delegate to homelab apps/kindred/justfile (pg_dump + roll + healthcheck)
# or all three at once:
just ship patch

What each step does:

• just release LEVEL runs release-kit cut: preflights (clean tree on main, in sync with origin), regenerates the unreleased section of CHANGELOG.md via git-cliff, drafts the GH release body via LiteLLM (deepseek-v4-pro-cloud), opens $EDITOR for review, commits CHANGELOG.md, tags + pushes + creates the GH release.
• just build TAG builds Dockerfile.prod with a local buildx cache and pushes :<tag> and :sha-<short> to ghcr.io/pike00/kindred (the running container brand; the repo is personal-crm). Requires GHCR auth in ~/.docker/config.json (gh token with write:packages).
• just deploy TAG delegates to ~/Documents/Homelab/apps/kindred/justfile, which does the mandatory pg-dump-before-bump, rolls the container, and runs the post-deploy healthcheck.

CHANGELOG.md is generated by git-cliff per cliff.toml; do not hand-edit it. Preview the next release section with just changelog-preview or just notes-dry-run.

Deployment tiers

Three isolated environments. Each has its own credentials, database, and Docker volumes — nothing is shared across tiers.

Hard isolation enforced by

• Distinct Postgres credentials per tier — secrets live only in their own .env.sops
• Distinct Docker volumes (kindred_db_data for prod, project-local dev-db for dev) — no external: true cross-references between tiers
• Distinct Docker networks — pikenet-internal-kindred for prod, default bridge for dev
• Distinct database names — prod is kindred, dev is crm
• Traefik label pinning — prod compose has the domain hard-coded, dev compose has its own hard-coded dev hostname; neither uses a ${DOMAIN} variable that could claim the other's hostname

Origin

This project was scaffolded from the FastAPI full-stack template via Copier. The backend/README.md and frontend/README.md files are still mostly upstream template content — treat them as reference, not project-specific docs.

License

Kindred is source-available under the Elastic License 2.0 (ELv2).

You can: self-host for personal use, fork, modify, contribute, and run it for your own contacts.

You cannot: offer Kindred as a hosted or managed service to third parties without a commercial license. If you want to build a hosted personal CRM product on top of Kindred, get in touch.

The FastAPI full-stack template scaffold is MIT-licensed (Sebastián Ramírez); attribution is preserved in the LICENSE file.