Hlídač ČÚZK

Vzhled

Open source · self-hosted

Hlídač ČÚZK

Sledování parcel, staveb, jednotek a řízení v katastru nemovitostí a upozornění na změny — na vašem vlastním serveru.

Nainstalovat GitHub

AGPL-3.0-only · Docker image pro amd64 i arm64 · ghcr.io/petrleocompel/hlidac-cuzk

Co umí

Změny, které u nemovitosti opravdu počítají

Hlídač pravidelně kontroluje veřejná data ČÚZK a upozorní vás dřív, než změnu sami objevíte v nahlížení do katastru.

  • Parcely, stavby, jednotky a práva stavby

    Každý registr katastru se sleduje jako samostatný objekt s vlastním snímkem, historií, intervalem a pravidly upozornění. Detail nabídne i navázané objekty.

  • Přidání podle adresy

    Adresní místa našeptává RÚIAN. Přesná shoda vede přes kód adresního místa ke stavbě, kterou Hlídač nabídne spolu s jednotkami a parcelami.

  • Sledování řízení

    Nová řízení a plomby, změny stavu, provedené operace i stav úhrady. Řízení se dosleduje i po odebrání plomby, takže víte, jak skutečně dopadlo.

  • Historie změn před a po

    Každá událost ukládá původní i novou hodnotu (Výměra: 976 → 980 m²) a snímek, ze kterého vznikla. Historii lze filtrovat a exportovat do CSV či JSON.

  • Upozornění podle vašich pravidel

    Gotify, Slack, Discord, ntfy a e-mail (SMTP). Výběr událostí a kanálů pro každé sledování, tiché hodiny, denní a týdenní souhrny a spolehlivá fronta s opakováním.

  • Katastrální mapa

    Mapa KN s ortofotem, definičními body a přesnou geometrií parcel z INSPIRE CP. Z mapy lze vybrat parcelu nebo sousední parcely a po ověření je přidat.

  • Portfolio a štítky

    Soukromé štítky a poznámky, vyhledávání bez diakritiky, filtry podle KÚ, LV a stavu, přehled podle LV a hromadné pozastavení či změna intervalu. Import z CSV/JSON.

  • SSO a soukromá registrace

    Přihlášení přes OIDC (Authentik, Keycloak…) i heslem. Výchozí instance je soukromá: účty zakládá správce, případně je možné zvát pozvánkami.

  • Denní rozpočet ČÚZK API

    Web, worker i CLI sdílejí denní limit 500 pokusů. Administrace ukazuje spotřebu, chyby a odhad plánovaných volání, sdílená data se stahují jen jednou.

  • Šifrované zálohy s resticem

    Volitelné plánované zálohy databáze i konfigurace do vzdáleného úložiště (S3, SFTP, REST) a ověřená obnova do prázdné databáze.

  • Multiarch Docker image

    Image pro amd64 i arm64 v GHCR s SLSA provenance a SBOM. Web, worker i migrace běží pod UID 1000 s read-only souborovým systémem.

  • Metriky pro Prometheus

    Endpoint /api/metrics chráněný tokenem vystavuje rozpočet API, stav účtu ČÚZK a stav workeru. Připravená pravidla upozorní na výpadek kontrol.

Rychlá instalace

Docker Compose na vlastním serveru

Stručný výtah z návodu k instalaci. Před ostrým provozem si přečtěte celý návod — hlavně nastavení HTTPS proxy, záloh a postup aktualizace.

  1. Stažení a vygenerování konfigurace

    env:init vytvoří deploy/.env s unikátními klíči a právy 0600.

    bash
    git clone https://github.com/petrleocompel/hlidac-cuzk.git
cd hlidac-cuzk
npm install --global corepack  # Node 25+ už Corepack nepřibaluje
corepack enable
pnpm install --frozen-lockfile
pnpm env:init deploy/.env

  2. Doplnění údajů a připnutí image

    V deploy/.env doplňte ADMIN_EMAIL, CUZK_API_KEY, APP_HOST a PUBLIC_URL. V GitHub Releases vyberte verzi X.Y.Z, stáhněte image a zjistěte jeho digest:

    bash
    docker pull ghcr.io/petrleocompel/hlidac-cuzk:X.Y.Z
docker image inspect ghcr.io/petrleocompel/hlidac-cuzk:X.Y.Z --format '{{json .RepoDigests}}'

    Do deploy/.env uložte HLIDAC_CUZK_IMAGE=ghcr.io/petrleocompel/hlidac-cuzk@sha256:… s celým skutečným digestem. Nepřipínejte latest ani edge.

  3. Spuštění

    Příkazy se spouštějí v adresáři deploy/. Overlay selfhost publikuje aplikaci jen na 127.0.0.1:3000 pro TLS proxy na stejném hostiteli.

    bash
    cd deploy
docker compose -f docker-compose.yml -f docker-compose.selfhost.yml -p hlidac_cuzk config --quiet
docker compose -f docker-compose.yml -f docker-compose.selfhost.yml -p hlidac_cuzk up -d --wait

  4. Ověření

    Diagnostika bez spotřeby ČÚZK API, poté zkontrolujte /readyz a přihlášení správce.

    bash
    docker compose -f docker-compose.yml -f docker-compose.selfhost.yml -p hlidac_cuzk \
  run --rm --no-deps app pnpm run doctor
Celý návod k instalaciSelf-hosting guide (English)

Jak to funguje

Aplikace, worker a PostgreSQL

Všechny části běží z jednoho Docker image na vašem serveru. Ven se instance připojuje jen k ČÚZK, k vámi zvoleným notifikačním službám a případně k poskytovateli SSO — přehled síťových závislostí.

  1. Aplikace

    Webové rozhraní pro přidávání sledování, historii, mapu a administraci. Přihlášení heslem nebo přes SSO (OIDC); za HTTPS reverzní proxy.

  2. Worker

    Každých pět minut vybere sledování, která jsou na řadě (výchozí interval je jednou denně), stáhne data z REST API katastru a porovná je s posledním snímkem. Každou minutu doručuje upozornění z fronty a každých šest hodin kontroluje stav účtu ČÚZK.

  3. PostgreSQL 16

    Uchovává snímky, historii změn, frontu notifikací i počítadlo denního rozpočtu API. Může běžet v Compose, nebo jako externí databáze.

Potřebujete vlastní API klíč ČÚZK. Hlídač čte data z REST API katastru nemovitostí api-kn.cuzk.gov.cz; klíč je zdarma a získáte ho registrací přes Identitu občana — návod. Instalace hlídá denní limit 500 pokusů. Projekt není oficiální službou ČÚZK.