Installare il tuo server Noodle

Il server di Noodle tiene allineati i tuoi dispositivi: l'app per Mac, il telefono e qualunque browser vedono le stesse pagine, aggiornate mentre scrivi. Sullo stesso indirizzo serve anche Noodle nel browser, fa i backup da solo e, se vuoi, collega gli assistenti IA come Claude. Gira in Docker su una macchina tua: i dati restano lì e non passano da nessun servizio esterno.

Serve una macchina sempre accesa con Docker e Docker Compose: un mini PC, un NAS che supporta Docker, una macchina virtuale di casa o un server in affitto (VPS). Basta 1 GB di RAM e qualche GB di disco, più lo spazio per allegati e backup.

01Prima di iniziare

Cosa serve

• Una macchina sempre accesa con Docker e Docker Compose v2 (il comando è docker compose, con lo spazio). Se Docker manca, installalo con la procedura ufficiale per il tuo sistema.
• Il pacchetto del server, cioè il file noodle-server-<versione>.zip della pagina Download. Contiene la cartella noodle-server/ con server/, apps/web/, shared/, deploy/ e il file ISTRUZIONI.md, scritto per un assistente IA ma leggibile da chiunque. L'app per Mac può salvare lo stesso pacchetto: al primo avvio, "Il mio server" > "Devo installarlo" > "Salva il pacchetto...".
• Facoltativo ma consigliato: un indirizzo in HTTPS, con un dominio o con Tailscale. In rete locale Noodle funziona anche senza, ma nel browser lo sblocco con impronta e volto (passkey) e le notifiche push richiedono HTTPS.

Cinque domande da porsi

1. Dove gira il server? Un computer di casa, un NAS o una VPS. Docker è già installato?
2. Da dove lo userai? Solo in casa, anche fuori casa tramite Tailscale o una VPN, oppure da internet con un dominio.
3. Hai già un proxy con HTTPS (Nginx Proxy Manager, Caddy, Traefik) o un dominio?
4. Vuoi collegare assistenti IA come Claude o Codex? Si può decidere anche dopo.
5. Dove copierai i backup fuori dalla macchina: un NAS, un disco esterno, un servizio cloud?

Le risposte decidono solo le sezioni 6, 7 e 8. L'installazione di base è la stessa per tutti.

02Due modi per installarlo

Puoi farti guidare da un assistente IA che lavora nel terminale, oppure seguire questa pagina a mano. Il risultato è lo stesso.

Voglio installare il server di Noodle. Questa cartella (noodle-server) è il pacchetto scaricato dal sito.
Il server deve girare su: [per esempio "questo computer", "il mini PC di casa, raggiungibile con ssh utente@192.168.1.10", "il mio NAS"].

Leggi per intero ISTRUZIONI.md e seguilo fase per fase, dall'inizio alla fine:
- prima fammi le domande iniziali, una alla volta, e spiegami in parole semplici cosa stai per fare;
- se l'immagine pronta non si scarica, usa subito la strada B (dal sorgente, docker compose up -d --build dalla cartella deploy);
- prima di cambiare qualcosa che esiste già sulla macchina (firewall, proxy, altri container) mostrami cosa farai e aspetta il mio via;
- dopo ogni fase esegui il controllo indicato e vai avanti solo se riesce; se non riesce, cerca la causa nei log prima di riprovare;
- genera i token direttamente dentro il file .env, senza mostrarli in chat e senza copiarli in altri file; dimmi solo come leggerli, così li salvo nel mio gestore di password.

Per i dettagli di Docker, Dockge e Nginx Proxy Manager usa deploy/README.md; deploy/MCP.md solo se decido di collegare gli assistenti.
Alla fine fammi un riepilogo: indirizzo con cui aprire Noodle, dove sono i dati e i backup, come si aggiorna, e i controlli finali di sicurezza verificati uno per uno.

03Installazione

Oggi la strada è il pacchetto scaricabile, da cui Docker costruisce l'immagine sulla tua macchina. Più sotto c'è la strada con l'immagine pronta, che servirà quando l'immagine sarà pubblicata su un registro.

Dal pacchetto scaricabile

Copia lo zip sulla macchina del server. Dal tuo computer, per esempio:

$ scp ~/Downloads/noodle-server-*.zip utente@192.168.1.10:~

Poi, sulla macchina del server, estrai il pacchetto in /opt e prepara la configurazione:

$ sudo unzip ~/noodle-server-*.zip -d /opt
$ sudo chown -R "$USER": /opt/noodle-server
$ cd /opt/noodle-server/deploy
$ cp .env.example .env && chmod 600 .env
$ openssl rand -base64 32
# copia il risultato in NOODLE_TOKEN, poi compila il resto (tabella qui sotto)
$ nano .env

Se unzip manca, installalo (sudo apt install unzip su Debian e Ubuntu).

Le variabili del file .env

Il file .env.example le spiega tutte. Per partire bastano queste:

Il resto ha valori predefiniti sensati: allegati fino a 200 MB, un backup ogni 6 ore con gli ultimi 30 tenuti, più uno al giorno per 30 giorni. Le variabili SMTP_* servono solo se vuoi che il server mandi email (inviti, password dimenticata); senza, i link d'invito si copiano a mano.

Avvio

$ mkdir -p data && sudo chown 1000:1000 data
$ docker compose up -d --build
# la prima volta costruisce l'immagine: qualche minuto
$ docker compose logs -f
# Ctrl+C per uscire dai log (il server continua a girare)

Al primo avvio di una versione nuova il server può impiegare qualche minuto a preparare i dati: è normale, e Docker lo considera in salute solo dopo.

$ curl http://127.0.0.1:4455/api/health

Con Dockge

Se gestisci i container con Dockge: crea uno stack noodle, incolla il contenuto di deploy/docker-compose.yml e nella sezione .env il contenuto di .env.example, compilato come sopra. NOODLE_SRC deve essere il percorso assoluto della cartella del pacchetto (per esempio /opt/noodle-server), perché lo stack di Dockge sta in un'altra cartella. Prepara la cartella dei dati dello stack, poi premi Distribuisci:

$ sudo mkdir -p /opt/stacks/noodle/data
$ sudo chown 1000:1000 /opt/stacks/noodle/data

Con l'immagine pronta

Quando l'immagine sarà pubblicata su un registro, o se qualcuno ti ha già dato l'immagine, non serve costruire nulla: basta la sottocartella deploy/immagine/ del pacchetto. Copiala sulla macchina, per esempio in /opt/noodle, e lancia lo script:

$ cd /opt/noodle
$ sh installa.sh

Lo script crea il .env con un token amministratore e un token per il gateway generati a caso, stampa una sola volta il token amministratore (salvalo subito nel gestore di password), scarica l'immagine, avvia il server e aspetta che risponda. Rilanciarlo è sicuro: non tocca un .env esistente né i dati. Se l'immagine non si scarica ma è già presente sulla macchina, usa quella; altrimenti si ferma e rimanda alla strada dal pacchetto.

Con questa strada i dati stanno nel volume Docker noodle-data. Se preferisci una cartella normale, più comoda da copiare, imposta NOODLE_DATA nel .env prima del primo avvio (la cartella deve essere scrivibile da uid 1000). Poi controlla PUBLIC_URL e TZ e, dopo ogni modifica al .env, esegui docker compose up -d.

04Primo account

1. Dal browser apri http://192.168.1.10:4455/, con l'indirizzo della tua macchina. Compare la schermata "Crea il tuo account".
2. Inserisci il "Token amministratore" (quello di NOODLE_TOKEN), un nome utente e una password di almeno 10 caratteri: una frase lunga va benissimo. Questo primo account è l'amministratore.
3. Subito dopo, in Impostazioni > "Sicurezza", attiva un secondo fattore: Face ID o Touch ID nelle app, una passkey nel browser in HTTPS, oppure un'app di autenticazione con codici di 6 cifre. Senza secondo fattore non si possono collegare assistenti né proteggere note.
4. Salva i 10 codici di recupero nel gestore di password. Ognuno vale una volta sola e ti fa entrare senza telefono.
5. Gli altri account li crei tu in Impostazioni > "Amministrazione", con un invito o con una password provvisoria che ognuno cambia al primo accesso.

Il token amministratore non serve per l'uso di tutti i giorni: dopo il primo account si entra con utente e password. Resta utile per il pannello /admin/, quindi conservalo.

05Collegare le app

Browser

Apri l'indirizzo del server e accedi: Noodle nel browser è servito dal server stesso, che risulta già impostato. Le pagine restano anche nel browser e si allineano quando torna la connessione.

iPhone e Android

In Safari apri l'indirizzo del server, poi Condividi > "Aggiungi alla schermata Home": Noodle si apre come un'app. Su Android, Chrome propone "Installa app" solo se l'indirizzo è in HTTPS. Quando sarà disponibile l'app per iPhone, la prima volta iOS chiederà il permesso di accedere alla rete locale: va consentito, altrimenti l'app non vede un server di casa.

App per Mac

Al primo avvio scegli "Il mio server" e scrivi l'indirizzo; se l'app è già in uso, vai in Impostazioni > "Dati" > "Collega un server". L'indirizzo va scritto con il prefisso del websocket:

• ws://192.168.1.10:4455 in rete locale, senza HTTPS;
• wss://noodle.tuodominio.it con HTTPS.

Poi "Accedi" con utente e password. In Impostazioni > "Avanzate", "Verifica connessione" dice se il server risponde. Le pagine create prima sul Mac senza server salgono da sole sul server al primo accesso.

06Raggiungerlo da fuori casa

Scegli in base alla seconda domanda della sezione 1. Se hai dubbi, Tailscale è la strada più sicura con meno lavoro.

$ sudo tailscale serve --bg 4455

client_max_body_size 210m;
proxy_request_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

noodle.tuodominio.it {
    reverse_proxy 127.0.0.1:4455
}

07Assistenti via MCP

Questa parte è facoltativa. Il gateway MCP è un container separato che porta le tue pagine e il Brain dentro Claude.ai, Claude Code, Codex e gli altri assistenti che parlano MCP. Ogni assistente vede solo quello che gli concedi, vault per vault, in sola lettura o anche in scrittura.

Come è protetto

• Il gateway non monta i dati del server, non riceve il token amministratore e parla con il server solo da un ingresso interno, con un token di servizio dai permessi limitati.
• Gira in un container indurito: file system in sola lettura, nessun privilegio, memoria e processi limitati, nessun accesso alla rete esterna.
• Nessuna password passa dal gateway: ogni collegamento si approva nell'app Noodle, con la verifica in due passaggi.
• Un assistente non modifica i database, non elimina nulla definitivamente (sposta nel cestino), non crea più di 200 pagine al giorno. La revoca vale entro mezzo minuto.

Accenderlo

Nel .env imposta:

COMPOSE_PROFILES=mcp
MCP_SERVICE_TOKEN=
MCP_PUBLIC_URL=https://mcp.tuodominio.it

In MCP_SERVICE_TOKEN va una stringa casuale, che ottieni con openssl rand -hex 32 (con la strada dell'immagine pronta lo script l'ha già generata). MCP_PUBLIC_URL è l'indirizzo pubblico in HTTPS del gateway, senza barra finale e senza /mcp: lo scegli nel passo successivo. Poi riavvia lo stack:

$ docker compose up -d --build
# con l'immagine pronta basta: docker compose up -d
$ curl -s http://127.0.0.1:4456/.well-known/oauth-authorization-server

L'ultimo comando deve rispondere con un JSON. Il gateway ascolta solo su 127.0.0.1:4456: la rete locale non lo vede.

Renderlo raggiungibile

Gli assistenti nel cloud devono raggiungere il gateway da internet in HTTPS, sulla porta 443 (altre porte, come la 8443, possono non funzionare). Serve qualcosa sull'host che inoltri a 127.0.0.1:4456:

• Tailscale Funnel: sudo tailscale funnel --bg 4456 pubblica il gateway su https://<macchina>.<tailnet>.ts.net. Dopo l'accensione il certificato può richiedere un minuto: aspetta prima di provare.
• Caddy sull'host, con un sottodominio dedicato:

  mcp.tuodominio.it {
      reverse_proxy 127.0.0.1:4456
  }

  Copia

Scrivi l'indirizzo ottenuto in MCP_PUBLIC_URL ed esegui di nuovo docker compose up -d. Poi, da fuori casa, apri nel browser l'indirizzo del gateway seguito da questo percorso:

https://mcp.tuodominio.it/.well-known/oauth-authorization-server

Collegare gli assistenti

• Claude.ai: Impostazioni > Connettori > "Aggiungi connettore personalizzato", con l'indirizzo che Noodle mostra in Impostazioni > "Assistenti AI" (è MCP_PUBLIC_URL seguito da /mcp). Si apre una pagina con un codice di abbinamento, per esempio K7QM-4F2T. In Noodle, Impostazioni > "Assistenti AI", compare la richiesta con lo stesso codice: scegli cosa potrà vedere e premi "Approva". Approva solo se hai appena avviato tu il collegamento e il codice coincide.
• Claude Code: in Impostazioni > "Assistenti AI" > "Crea chiave" ottieni una chiave, visibile una volta sola, e il comando da incollare nel terminale:

  $ claude mcp add --transport http noodle https://mcp.tuodominio.it/mcp --header "Authorization: Bearer <chiave>"

  Copia
  In alternativa Claude Code si collega senza chiave, con la stessa approvazione a codice di Claude.ai.
• Codex e gli altri client MCP: stesso indirizzo e stessa chiave; i dettagli sono nella pagina Integrazioni.

Non incollare mai la chiave in note, chat o repository: chi la possiede legge e modifica quello che le è concesso.

08Backup e ripristino

Backup automatici

Il server fa un backup ogni 6 ore (BACKUP_INTERVAL_HOURS) e ne tiene gli ultimi 30, più uno al giorno per 30 giorni. Ogni archivio .tar.gz contiene il database, gli allegati e un export leggibile delle pagine. Si trovano in:

• deploy/data/backups/ con la strada dal pacchetto;
• nel volume Docker noodle-data, oppure nella cartella backups/ di NOODLE_DATA, con l'immagine pronta.

Una copia fuori dalla macchina

Un backup che sta sullo stesso disco del server non protegge da un guasto del disco. La cartella dei backup è un normale percorso dell'host: copiala altrove con un job pianificato. Per esempio, con crontab -e, ogni notte alle 3 verso un NAS montato:

0 3 * * * rsync -a /opt/noodle-server/deploy/data/backups/ /mnt/nas/noodle-backup/

Al posto di rsync va bene rclone verso un servizio cloud. In alternativa il server può eseguire un comando dopo ogni backup con BACKUP_HOOK: gli esempi sono in .env.example.

Il pannello di amministrazione

All'indirizzo /admin/ del server (per esempio https://noodle.tuodominio.it/admin/) trovi lo stato del server, lo spazio usato, gli ultimi accessi e i backup, con i pulsanti per crearne uno subito, scaricarli e ripristinarli. Chiede il token amministratore e lo tiene solo nella scheda aperta.

Ripristino

Dal pannello, "Ripristina" accanto al backup scelto. Prima del ripristino il server crea da solo un backup pre-restore, così puoi tornare indietro. Per ripristinare un archivio che non è nella lista, per esempio su una macchina nuova, copialo nella cartella dei backup con il suo nome originale (noodle-AAAAMMGG-HHMMSS-motivo.tar.gz) e ricarica il pannello.

09Aggiornare

Prima di aggiornare conviene un "Crea backup ora" dal pannello /admin/. I dati non vengono toccati dall'aggiornamento; fermando il container il server salva tutti i documenti aperti.

Dal pacchetto

Scarica il nuovo noodle-server-<versione>.zip, copialo sulla macchina, estrailo in una cartella temporanea e copia i file sopra la vecchia installazione. Il pacchetto non contiene né .env né data, quindi configurazione e dati restano dove sono.

$ rm -rf /tmp/noodle-nuovo && unzip ~/noodle-server-*.zip -d /tmp/noodle-nuovo
$ cp -R /tmp/noodle-nuovo/noodle-server/. /opt/noodle-server/
$ cd /opt/noodle-server/deploy
$ docker compose up -d --build

Con Dockge, dopo aver copiato i file, premi Aggiorna sullo stack per ricostruire l'immagine.

Con l'immagine pronta

$ cd /opt/noodle
$ docker compose pull && docker compose up -d

Se nel .env hai fissato una versione con NOODLE_VERSION, cambia prima il numero.

Al primo avvio di una versione nuova il server può impiegare qualche minuto a preparare i dati. Il controllo è lo stesso dell'installazione: curl http://127.0.0.1:4455/api/health deve mostrare la versione nuova.

10Controlli finali di sicurezza

Spunta ogni voce dopo averla verificata. Le caselle restano salvate in questo browser.

11Problemi comuni

Il primo posto dove guardare è sempre il log, dalla cartella del compose:

$ docker compose ps
$ docker compose logs --tail=100