Oikos/Guide
INSTALLAZIONE

Da zero a Oikos
in pochi minuti.

Oikos si installa come applicazione di Home Assistant oppure, se usi Home Assistant in Docker, come container. Niente YAML da scrivere, niente reverse proxy: in entrambi i casi basta un riavvio di Home Assistant.

Cosa serve

Home Assistant
Versione 2024.1 o successiva. Con Home Assistant OS o Supervised installi l’applicazione (qui sotto); con Home Assistant Container usi il container Docker (più in basso).
Hardware
Processori amd64, aarch64, armv7, armhf e i386. Circa 200 MB di RAM liberi: va bene anche un Raspberry Pi.
Un account Oikos
Ti serve per la licenza. I primi 15 giorni sono di prova gratuita, senza carta di credito.

Installa l’applicazione

Per Home Assistant OS e Supervised. Se usi Docker, salta a Installazione con Docker.

Il modo più rapido è il pulsante qui sotto: apre il tuo Home Assistant con il repository di Oikos già compilato.

Aggiungi a Home Assistant

Se preferisci farlo a mano:

  1. 1

    Aggiungi il repository

    In Home Assistant apri Impostazioni → Applicazioni → Store applicazioni, poi il menu ⋮ → Repository. Incolla https://github.com/Bobsilvio/oikos e conferma.

  2. 2

    Installa Oikos

    Ricarica lo store, cerca «Oikos» e premi Installa. Non ci sono dipendenze da aggiungere.

  3. 3

    Avvialo

    Premi Avvia. Al primo avvio Oikos aggiunge da solo la sua voce nella barra laterale di Home Assistant.

  4. 4

    Riavvia Home Assistant una volta

    Serve solo la prima volta, perché la voce «Oikos» compaia nella barra laterale. Dopo il riavvio aprila: sei dentro.

Perché il riavvio?

Oikos si registra come pannello di Home Assistant scrivendo una riga in configuration.yaml. Home Assistant legge quel file solo all’avvio. Se il file usa già panel_custom: !include, Oikos aggiunge la sua sezione senza toccare il resto.

Primo avvio e licenza

Aprendo Oikos la prima volta compare la schermata di accesso, con tre schede:

Registrati
Crei l’account con la tua email. Parte subito la prova gratuita di 15 giorni.
Accedi
Se hai già un account, entri con email e password.
Chiave
Se hai già una chiave di licenza (SS-…), la incolli direttamente.

La licenza vale per una installazione di Home Assistant e si salva nell’applicazione: tutti i browser e i dispositivi della casa la usano senza chiederla di nuovo. Abbonamento, fatture e cambio di piano stanno nel portale, raggiungibile anche da menu ⋮ → Licenza.

Dopo l’accesso una procedura guidata ti aiuta a creare la prima dashboard: scegli le pagine, i sensori di energia e le card da cui partire. Tutto si cambia anche dopo.

Installazione con Docker

Con Home Assistant Container (Docker, senza Supervisor) non ci sono applicazioni da installare: Oikos gira come un container a parte, accanto a quello di Home Assistant. Pannello, card, licenza e assistente sono gli stessi dell’applicazione.

Cosa serve
Docker con Docker Compose, Home Assistant 2024.1 o successivo, e il percorso della cartella config di Home Assistant sul tuo server.
Come funziona
Oikos e Home Assistant condividono la stessa cartella config. Al primo avvio Oikos ci copia il pannello e aggiunge a configuration.yaml la voce nella barra laterale e un piccolo ponte (oikos_proxy) attraverso cui Home Assistant parla con Oikos. Così funziona anche da fuori casa, con Nabu Casa o il tuo dominio, senza reverse proxy.
  1. 1

    Crea il file docker-compose.yml

    In una cartella a tua scelta, con questo contenuto. Cambia le due righe segnate.

    services:
  oikos:
    image: ghcr.io/bobsilvio/oikos:standalone
    container_name: oikos
    restart: unless-stopped
    ports:
      - "3564:3564"
    volumes:
      - /percorso/al/config/homeassistant:/config   # ← lo STESSO /config di HA
    environment:
      OIKOS_STANDALONE: "1"
      OIKOS_HA_URL: "http://192.168.1.50:8123"        # ← indirizzo locale di HA
  2. 2

    Avvia il container

    Dalla stessa cartella: docker compose up -d. Nel registro (docker logs oikos) vedi il pannello copiato e il ponte pronto.

  3. 3

    Riavvia Home Assistant una volta

    Serve per caricare la voce nella barra laterale e il ponte appena aggiunti. Prima di modificare configuration.yaml Oikos ne salva una copia.

  4. 4

    Apri Oikos

    Dalla barra laterale di Home Assistant. Da qui in poi è come l’applicazione: registrazione o accesso, prova gratuita, procedura guidata.

Le impostazioni del container

OIKOS_STANDALONE
Sempre "1": dice a Oikos che gira fuori dal Supervisor.
OIKOS_HA_URL
Obbligatorio. Indirizzo locale di Home Assistant, con la porta (di solito 8123). Oikos lo usa per verificare chi accede: senza, rifiuta tutte le richieste.
/config
La cartella config di Home Assistant, la stessa montata nel suo container. Non una copia: Oikos deve scriverci il pannello e leggere l’identità dell’installazione per la licenza.
3564
La porta su cui Home Assistant raggiunge Oikos. Di solito basta pubblicarla così: Oikos ricava l’indirizzo da OIKOS_HA_URL. Non va aperta su internet.
OIKOS_INTERNAL_URL
Facoltativo. Se Home Assistant e Oikos stanno sulla stessa rete Docker, impostalo a http://oikos:3564 e puoi togliere la sezione ports. Serve anche se l’indirizzo ricavato in automatico è sbagliato.

Aggiornare

L’immagine si aggiorna come ogni container: docker compose pull e poi docker compose up -d. Al riavvio Oikos copia il pannello nuovo; ricarica la pagina nel browser. Di solito non serve riavviare Home Assistant: se un aggiornamento cambia il ponte, il registro delle modifiche lo dice.

Dopo il riavvio di Home Assistant non vedo Oikos.

Controlla che la cartella montata sia davvero il /config di Home Assistant: deve contenere configuration.yaml. Nel registro del container Oikos dice se ha aggiunto le voci o se non è riuscito a scriverle.

Il pannello si apre ma resta in caricamento, o dice che il server non risponde.

Home Assistant non raggiunge la porta 3564. Verifica OIKOS_HA_URL, che la porta sia pubblicata e che il firewall del server non la blocchi. Se i container sono sulla stessa rete Docker usa OIKOS_INTERNAL_URL.

Mi rifiuta l’accesso dopo un aggiornamento.

Da qualche versione OIKOS_HA_URL è obbligatorio: aggiungilo al file compose e riavvia il container.

Aggiornare e disinstallare

Gli aggiornamenti arrivano come per ogni applicazione: quando Home Assistant segnala una nuova versione, premi Aggiorna. Le novità di ogni versione sono nel registro delle modifiche dell’applicazione. Dopo l’aggiornamento ricarica la pagina di Oikos.

Per togliere Oikos del tutto usa prima Impostazioni → Disinstallazione dentro Oikos: rimuove dashboard, card installate, immagini, package e la voce nella barra laterale. Poi disinstalla l’applicazione e riavvia Home Assistant. La licenza resta tua e la puoi riusare.

Se qualcosa non va

Ho installato Oikos ma non lo vedo nella barra laterale.

Riavvia Home Assistant: la voce compare solo dopo il primo riavvio. Se ancora manca, apri il registro dell’applicazione Oikos: se non è riuscito a scrivere configuration.yaml lo dice lì.

Ho aggiornato, ma vedo ancora la versione vecchia.

Ricarica la pagina di Oikos. Nell’app di Home Assistant chiudila e riaprila.

Mi chiede la licenza anche se l’ho già inserita.

Controlla che l’applicazione sia avviata: è lei a tenere la chiave per tutti i dispositivi. Se il problema resta, scrivici da menu ⋮ → Supporto.

Ora configurala →