Skip to content

ClueCDC v0.2.0

ClueCDC v0.2.0 adds local account authentication and a complete built-in authorization model for operating the CDC control plane. It also aligns the UI, API, documentation, and database metadata around those access boundaries.

This is a 0.x release. Review the authentication and upgrade notes before deploying it over an existing v0.1.0 installation.

Authentication highlights

  • Local email/password authentication with Argon2id password hashes.
  • Opaque server-side browser sessions delivered through an HttpOnly, SameSite=Lax cookie; production cookies also use Secure.
  • Expiring, single-use invitation links whose raw tokens are never stored.
  • A minimum password length of 8 characters for invited users and CLI-created administrators.
  • Login rate limiting, generic credential-failure responses, immediate logout, and session invalidation when an account is disabled.
  • Authentication, invitation, activation, role, status, deletion, login, and logout activity recorded in the audit trail without credentials or raw tokens.

ClueCDC does not send invitation email in this release. An Admin must copy and share the generated invite link securely.

Roles and permissions

Authorization is enforced by the API. The web application also hides pages, navigation, actions, and detail tabs outside the signed-in user's permissions.

Capability Viewer Ops Admin
View Overview, Pipelines, and Deliveries Yes Yes Yes
View Sources and Destinations No Yes Yes
Create, update, operate, and delete Pipelines No Yes Yes
Create, update, operate, and delete Deliveries No Yes Yes
Create, update, test, or delete Sources and Destinations No No Yes
Open or mutate Kafka/Connect infrastructure No No Yes
Access alerts, errors, audit, and system settings No No Yes
Invite, enable, disable, change roles, or delete users No No Yes

Ops receives limited read-only Kafka/Connect API access required to select existing clusters in the pipeline wizard. Standalone infrastructure pages and all infrastructure mutations remain Admin-only.

User administration

Admins can invite users, assign Viewer/Ops/Admin roles, enable or disable accounts, and permanently delete another user. Disabling a user invalidates all of their sessions. Deletion removes the account's active sessions and pending invite while retaining sanitized audit history.

Safety checks prevent an Admin from disabling or deleting their own current account and prevent deletion of the last active Admin.

Development account

The loopback-only development Compose stack creates this public demo account after migrations:

Email:    admin@cluecdc.local
Password: cluecdc-admin

Creation is idempotent and never resets an existing account. Do not expose this account to a network or promote its metadata database to production. Production startup rejects BOOTSTRAP_DEFAULT_ADMIN=true.

Production administrator

Production requires session authentication and an explicitly created Admin:

docker compose exec cluecdc-api \
  python -m app.cli create-admin --email admin@example.com

Set BOOTSTRAP_DEFAULT_ADMIN=false, use a unique 32-or-more-character SESSION_SECRET, and configure an HTTPS PUBLIC_URL before exposing the UI.

Database migrations

v0.2.0 adds metadata for users, sessions, and invitations. It also normalizes the unique indexes for user emails and hashed session/invite tokens so alembic check is clean against PostgreSQL.

Back up the metadata database and encryption key, then apply migrations before starting the new API and worker:

docker compose run --rm cluecdc-api alembic upgrade head
docker compose run --rm cluecdc-api alembic check

The default-account bootstrap runs after migrations in the development Compose startup path. Production operators should create the first Admin interactively.

Upgrade notes from v0.1.0

v0.1.0 production deployments commonly used static bearer-token authentication. Production now requires AUTH_MODE=session; legacy token and developer modes remain compatibility options for non-production environments.

Before upgrading:

  1. Back up metadata PostgreSQL and SECRET_ENCRYPTION_KEY.
  2. Set AUTH_MODE=session, BOOTSTRAP_DEFAULT_ADMIN=false, a unique SESSION_SECRET, and an HTTPS PUBLIC_URL.
  3. Apply all Alembic migrations and confirm alembic check reports no drift.
  4. Create the first named Admin through the interactive CLI.
  5. Sign in through /login, then invite Ops and Viewer accounts as needed.
  6. Review role changes: Viewer is limited to Overview/Pipelines/Deliveries, and Ops can mutate Pipelines/Deliveries but only view Sources/Destinations.

Docker images

The v0.2.0 tag-triggered workflow publishes:

  • ghcr.io/cluedata/cluecdc-web:0.2.0, :0.2, and :latest
  • ghcr.io/cluedata/cluecdc-api:0.2.0, :0.2, and :latest
  • ghcr.io/cluedata/cluecdc-connect:0.2.0, :0.2, and :latest

Pin 0.2.0 or an image digest in shared environments. Immutable release tags must never be rebuilt with different contents.

Known limitations

  • SSO, OAuth/OIDC, LDAP, SAML, groups, and custom roles are not implemented.
  • Invitation delivery is manual; ClueCDC does not send email.
  • The supplied Compose topology and public development Admin are for local use.
  • TLS, Kafka authentication/ACL provisioning, external secrets, backups, and high availability remain deployment responsibilities.

Full changelog

See CHANGELOG.md for the complete 0.2.0 change list.