Cinema Watch

Cacce ai biglietti dei cinema italiani, con avvisi su Telegram e la pianta della sala.

Cosa fa

• Cacce: un film (anche non ancora in programmazione, cercato per titolo), uno o più cinema, i formati di sala (IMAX, XL, Infinity Vision…) e le date, con filtri facoltativi per orario (anche diverso per ogni giorno della settimana), giorni della settimana e lingua.
• Avvisi su Telegram: nuovi spettacoli, posti liberati, ultimi posti, spettacoli annullati o spostati, con la pianta della sala e i migliori posti liberi.
• Zona buona: le file e i posti che vanno bene, relativi alla sala o fissati cliccando sulla pianta, con il numero di posti vicini richiesto.
• Pulsanti nel messaggio: Acquista, Apri sala, Aggiorna ora, Silenzia 24 h e Acquistato, con Riattiva e Ripristina per tornare indietro; /aggiorna rilegge tutte le cacce.
• Cinema: UCI Cinemas, i 35 The Space Cinema, circa 300 cinema che vendono con Webtic (Notorious, Cinelandia, Movie Planet e molti indipendenti) e i cinema 18Tickets, ordinabili per distanza da casa; un cinema 18Tickets che manca si aggiunge nelle Impostazioni.
• Web UI: cacce, programmazione, pagina dello spettacolo con la pianta dal vivo e l'andamento dei posti, ricerca di un film anche con un errore di battitura; si installa come app dietro HTTPS.

La pianta su Telegram, le cacce e i cinema per distanza da una casa d'esempio a Milano.

Stack

• Node 24 e TypeScript
• Hono, con JSX lato server
• Tailwind v4, compilato in fase di build
• resvg per i PNG delle piante
• zod per validare configurazione e risposte delle API
• dati in file JSON e JSONL, nessun database
• immagine ghcr.io/pilascat/cinema-watch per amd64 e arm64, circa 157 MB, utente 99:100, compatibile con --read-only; a riposo il processo usa circa 50 MiB di memoria propria (misurati su Unraid il 18/10/2026; docker stats mostra di più perché conta anche la cache dei file)

Avvio rapido

Su Unraid

1. Aprire la scheda Apps, cercare cinema-watch e premere Install.
2. Il template propone già la cartella dei dati /mnt/user/appdata/cinema-watch e PUID 99 / PGID 100: basta premere Apply.

I dettagli (percorso, proprietario, rete) sono in docs/operations.md.

Con Docker

docker run -d --name cinema-watch \
  -p 8790:8790 \
  -v /percorso/dati:/data \
  -e PUID=1000 -e PGID=1000 \
  --read-only --tmpfs /tmp \
  --security-opt=no-new-privileges \
  --restart unless-stopped \
  ghcr.io/pilascat/cinema-watch:latest

PUID e PGID sono l'utente e il gruppo a cui va la cartella dei dati (id li mostra; su Unraid 99 e 100). All'avvio il container dà loro la cartella e fa girare l'app con quell'utente, quindi non serve nessun chown a mano.

Con Docker Compose

Il file docker-compose.yml è un esempio con le stesse opzioni, con i dati in ./data:

mkdir cinema-watch && cd cinema-watch
wget https://raw.githubusercontent.com/PilaScat/cinema-watch/main/docker-compose.yml
docker compose up -d

Se id non dà 1000, prima dell'avvio vanno cambiati PUID e PGID nel file.

Primi passi

1. Aprire http://IP:8790.
2. In Impostazioni, sezione Telegram, inserire il token del bot e la chat principale (come ottenerli), salvare e premere Invia prova.
3. Premere Aggiungi caccia e compilare film, cinema, formati e date.
4. Facoltativo: in Impostazioni, sezione Casa e distanza, impostare la posizione di casa ("lat, lon" da Google Maps, oppure "Usa la mia posizione" aprendo l'app in HTTPS) e un raggio massimo. Cinema, ricerca e scelta dei cinema nelle cacce si ordinano allora per distanza.

Sviluppo in locale

npm ci
npm run build
DATA_DIR=./data node dist/server.js

I quattro controlli da far passare prima di consegnare:

npm test
npx tsc --noEmit
npm run lint
npm run build

Altri comandi:

• node dist/server.js --dry-run esegue un giro contro le API vere. Messaggi e piante finiscono in DATA_DIR/dry-run e non viene inviato nulla a Telegram.
• sh scripts/smoke.sh prova il container: immagine, avvio in sola lettura, PUID/PGID, route, permessi, arresto, giro a secco. Il dettaglio è in docs/operations.md.

Rilascio e deploy

Un rilascio è un tag annotato vAAAA.MM.N, che fa partire release.yml: verifica, scansione, immagini amd64 e arm64, attestazione e Release su GitHub. Su Unraid si installa con il template cinema-watch.xml del repo unraid-templates. Tutti i passaggi sono in docs/operations.md.

Variabili d'ambiente

Le Impostazioni mostrano quando token o chat arrivano dall'ambiente.

Limiti

• Funziona con UCI Cinemas, The Space Cinema e i cinema che vendono i biglietti con Webtic o 18Tickets; altri circuiti no.
• I cinema 18Tickets non hanno coordinate e vanno in fondo all'ordine per distanza.
• L'elenco dei cinema Webtic si aggiorna con un controllo settimanale: al primo avvio si completa in circa mezz'ora.
• Le API usate sono pubbliche ma non ufficiali e possono cambiare senza preavviso.
• I posti si leggono senza login.
• L'acquisto resta a mano: il login UCI ha Cloudflare e captcha, Webtic, The Space e 18Tickets chiedono l'account, e l'app non li tocca.

Documentazione

Contribuire

Bug e proposte si aprono come issue; le vulnerabilità si segnalano in privato come spiega SECURITY.md. Come preparare una pull request e quali controlli deve passare è in CONTRIBUTING.md.

Licenza e crediti

Licenza MIT, vedi LICENSE; le note delle parti di terzi sono in NOTICE. Autore: Filippo Scatigna (PilaScat).

• KiraPC/italian-cinema-mcp (MIT): da qui viene l'API della programmazione UCI.
• Font Bebas Neue e Barlow (OFL).
• Icone Lucide (ISC).

Non affiliato a UCI Cinemas, a Webtic né ai cinema elencati.