---
name: env-connectivity
description: Modello di configurazione env/connettività di EyeDoor dopo la rimozione di mDNS. Usa quando il task tocca .env.dev, .env.local, docker-compose dev, MQTT_BROKER, HOME_HUB_BASE_URL o variabili di rete tra hub e citofoni.
---

# Configurazione e connettività EyeDoor (post-mDNS)

Il progetto ha rimosso mDNS (rete universitaria con mDNS bloccato) e ha
consolidato la configurazione in un unico ambiente reale, non più
multi-branch. Vedi `PROGRESS.md` (header "STATO CORRENTE" + cronaca Fasi
A–F) per il razionale completo; questa skill è il riferimento operativo.

## Modello attuale

Per ciascuno dei due stack (hub in `env/`, citofono in
`clients/fake-intercoms/env/`):

- `.env.dev` — **versionato**, contiene tutto tranne i valori di rete
  (password placeholder `dev`/`dev`, porte, path, timeout, topic MQTT).
- `.env.local` — **gitignored**, contiene solo i valori che cambiano con la
  rete fisica (IP statico del hub, feed camera). Vedi memoria
  `env-local-secrets` per la disciplina su questi file.
- `.env.local.example` — versionato, template del precedente.

`HOME_HUB_BASE_URL` e `MQTT_BROKER` sono **obbligatorie e fail-fast**: un
clone pulito senza `.env.local` deve fallire con un messaggio chiaro; con
`.env.local` compilato deve avviarsi.

## Trappole note di Docker Compose

- L'interpolazione `${VAR}` nel file `docker-compose.dev.yml` vede **solo**
  il `--env-file` passato da CLI, non l'`env_file:` dichiarato dentro i
  singoli servizi.
- Il blocco `environment:` di un servizio ha **precedenza** su `env_file:`.
  Lasciare le variabili di rete nel blocco `environment:` scarterebbe
  silenziosamente i valori validi di `.env.local`.
- I path `env_file` si comportano in modo non ovvio tra `-f`/`extends`/
  `include` — verificare quale file viene effettivamente letto prima di
  assumere che una modifica a un `.env.*` abbia effetto.

## Variabili da non confondere

- `MQTT_PUBLIC_HOST`/`MQTT_PUBLIC_PORT` sono state **rimosse** (erano
  l'annuncio broker hub→citofono, causa di un bug di precedenza).
- `MQTT_HOST_PORT`/`MQTT_INTERNAL_PORT` sono tutt'altro — configurano
  l'ascolto reale del broker Mosquitto, non toccarle per errore.
- Principio di design applicato più volte nel refactoring: il hub non
  impone al citofono un indirizzo che il citofono può già configurare
  localmente.

## Aree da NON toccare

Vedi memoria `local-areas-do-not-touch`: hostname `.local` del citofono
generato dal serial (fallback IP-based, innocuo) e
`HOME_HUB_FRIENDLY_HOSTNAME` con l'allowlist Vite (controllo in ingresso,
non target di connessione).

## Dove approfondire

- `docs/development_and_release/env_config_audit_2026-07-20.md` — audit pre-refactoring.
- `docs/development_and_release/env_versioning_2026-07-20.md` — introduzione del modello attuale.
- `docs/development_and_release/batch4_mqtt_broker_precedence_2026-07-20.md` — rimozione precedenza hub→citofono.
- `docs/development_and_release/mdns_local_hostname_audit_2026-07-20.md` — audit aree `.local`.