CheckCheck

A collaborative, self-hostable, offline-capable checklist app. It ships as a single container: a web UI backed by a REST API. Make lists, check things off, organise with labels, and share individual cards with other people. Because it is local-first, the app keeps working while you are offline and syncs back up when the connection returns, and it installs as a PWA.

Status: Early Beta. Usable and self-hostable, but rough edges remain and things can still change. See Limitations before you rely on it.
(I just started driving it in real life)

Run it (Docker)

The published image is motey/checkcheck. It runs against PostgreSQL and needs three secrets from you: two long random strings and the first admin password. Save this as docker-compose.yml:

services:
  checkcheck:
    image: motey/checkcheck:latest
    restart: unless-stopped
    ports:
      - "8181:8181"
    depends_on:
      - db
    environment:
      SERVER_SESSION_SECRET: "replace-with-64+-random-chars"
      AUTH_JWT_SECRET: "replace-with-a-different-64+-random-string"
      ADMIN_USER_PW: "pick-a-strong-password"
      SQL_DATABASE_URL: "postgresql+asyncpg://checkcheck:secret@db:5432/checkcheck"
      SET_SESSION_COOKIE_SECURE: "false"   # only for plain-HTTP localhost; see below

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: checkcheck
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: checkcheck
    volumes:
      - checkcheck-db:/var/lib/postgresql/data

volumes:
  checkcheck-db:

Fill in the two secrets (openssl rand -hex 32 gives you one each), run docker compose up -d, then open http://localhost:8181 and log in as admin with the password you set.

SET_SESSION_COOKIE_SECURE: "false" is only there so login works over plain HTTP on localhost. Behind an HTTPS reverse proxy, drop that line (the default is true) and set SERVER_PROTOCOL=https and SERVER_HOSTNAME=your.domain. See docs/deployment.md for the production setup and reverse proxy notes.

Configuration

Every setting can come from an environment variable or a mounted config.yml (env wins). Two documents cover it:

• docs/configuration.md is the readable introduction: the handful of things you must set and the common scenarios.
• docs/CONFIG_REFERENCE.md is the exhaustive, generated reference for every field, and config.example.yml is a fillable template.

Limitations

CheckCheck is young. Know these before deploying:

• Not built for a large user base. It targets personal use and small, trusted groups, running on PostgreSQL (see docs/deployment.md).
• User management is delegated to an identity provider. Onboarding through an external OpenID Connect provider (Authentik, Keycloak, and so on) is the intended way to manage accounts. A single admin is bootstrapped from config, and optional self-registration exists (off by default). A built-in local user-management UI is not a goal right now but may come later.
• No email verification for self-registration. So it is off by default; enable it only on a trusted network or behind other anti-abuse controls, or use OIDC instead.
• Some features require connectivity by design. Sharing, invitations, notifications, and label create/rename/delete do not work offline and queue nothing while disconnected.
• The offline snapshot is stored unencrypted on the device. Treat shared or public machines accordingly.
• Pre-Alpha stability. Expect bugs and occasional breaking changes. Read docs/UPGRADING.md before upgrading and keep backups.

Documentation

Document	What it covers
docs/configuration.md	Readable intro to configuring an instance: precedence, required secrets, common scenarios, OIDC.
docs/CONFIG_REFERENCE.md	Generated reference for every config field (type, default, env var, description).
docs/deployment.md	Running with Docker and compose, PostgreSQL vs SQLite, reverse proxies, backups.
docs/administration.md	Day-to-day admin: the first admin, roles, adding users, sharing switches, the offline kill switch.
docs/UPGRADING.md	Per-release upgrade notes; pairs with CHANGELOG.md.
docs/SYNC_PROTOCOL.md	The local-first delta-sync contract, for developers and integrators.
docs/	Everything else: testing guides, the known-issues log, and historical plans.

Building from source

See docs/deployment.md for building the image yourself and CheckCheck/backend/README.md / CheckCheck/frontend/README.md for the component-level developer setup.

License

MIT, see LICENSE.