Risoluzione dei problemi

Problemi riscontrati eseguendo Ayakaleaf Pro con Docker Desktop su macOS e come verificarli.

​

L’inizializzazione non riesce con invalid command code

bin/init segnala sed: ... invalid command code quando trova il sed BSD di macOS. Metti GNU sed nel PATH come in 1. Scaricare il Toolkit e controlla sed --version.

Un’inizializzazione fallita può lasciare tutti e tre i file in config/ con un OVERLEAF_INVITE_TOKEN_SECRET vuoto. Rieseguire bin/init segnala quindi Config files already exist. Per una nuova installazione che non è mai stata avviata, sposta i tre file in una directory di backup ed esegui di nuovo bin/init. Per un’istanza esistente, conserva la sua configurazione e i suoi segreti e non eliminarne i file per far rieseguire bin/init.

​

MongoDB continua a riavviarsi

Leggi i log di MongoDB e la versione del kernel della VM di Docker:

bin/docker-compose logs --tail=100 mongo
docker info --format '{{.KernelVersion}}'

Se il log menziona l’incompatibilità con il kernel Linux, segui Controllare il kernel Linux della VM di Docker ed esegui di nuovo bin/up -d. Il solo codice di uscita 137 non dimostra che MongoDB abbia esaurito la memoria: controlla lo stato del container e i log. Per un problema più vecchio di MongoDB su Docker Desktop, vedi anche Risoluzione dei problemi.

​

Impossibile connettersi al daemon Docker

Avvia Docker Desktop e controlla il contesto Docker selezionato; vedi 0. Configurare Docker Desktop. Se docker info funziona ma le compilazioni non riescono a raggiungere Docker, controlla le impostazioni del socket in config/overleaf.rc e leggi i log di clsi. Una CLI di Docker funzionante sul Mac non dimostra che il mount del socket dell’applicazione sia corretto.

​

La pagina si apre, ma le compilazioni non riescono

Controlla che l’immagine TeX Live esista in locale e corrisponda all’architettura del motore Docker:

docker image inspect ghcr.io/ayaka-notes/texlive-full:2026.1 \
  --format '{{.Os}}/{{.Architecture}}'
bin/logs -f clsi

Su Apple silicon, l’immagine dovrebbe essere linux/arm64. Controlla che SERVER_PRO e SIBLING_CONTAINERS_ENABLED siano entrambi true, quindi applica le modifiche con bin/up -d. Se i log segnalano una directory di compilazione mancante, controlla la condivisione dei file di Docker Desktop e la posizione di OVERLEAF_DATA_PATH. Non disattivare le sandboxed compiles per nascondere un errore di mount.

​

Not a directory, oppure manca un bind mount

Un file dell’host montato da un override potrebbe essere stato eliminato, oppure Docker potrebbe aver creato una directory dove dovrebbe trovarsi il file. Controlla il percorso di origine sull’host e se il mount si aspetta un file o una directory. Ripristina il file di configurazione prima di ricreare il container. Un’installazione sotto /tmp può incorrere in questo problema dopo che macOS rimuove i file temporanei.

​

Conflitti di porta o di nome dei container

Se la porta 8080 è in uso, scegli un’altra porta in config/overleaf.rc, imposta OVERLEAF_SITE_URL di conseguenza ed esegui di nuovo bin/up -d.

Il Toolkit assegna ai suoi container nomi fissi come sharelatex, mongo e redis. Cambiare solo PROJECT_NAME non rende indipendenti due installazioni del Toolkit. Prima di avviare una seconda istanza, controlla docker ps -a e usa altri nomi di container in un override di Compose, un’altra porta e directory dei dati separate. Non rimuovere i container o i dati di una distribuzione esistente per risolvere un conflitto di nomi.

​

L’istanza non è raggiungibile dopo un po’ di tempo

Probabilmente il Mac è andato in sospensione, oppure Docker Desktop è stato chiuso. Vedi Mantenere l’istanza disponibile.

​

bin/doctor dice che non è Linux, o chiede un login a Quay

Entrambi gli avvisi sono previsti su macOS con l’immagine pubblica; vedi 2. Familiarizzare con il Toolkit. Controlla invece il download delle immagini, lo stato dei servizi e i risultati delle compilazioni, e non ignorare gli altri errori del report.