Sincronizzazione con Dropbox

Consenti agli utenti di sincronizzare i propri progetti con una cartella nel proprio Dropbox.

Questa funzionalità è sviluppata da ayaka-notes/ayakaleaf-pro. È stata introdotta nella v6.3.1 come anteprima e verrà rilasciata ufficialmente nella v6.4.0, quindi la sua configurazione e il suo comportamento potrebbero ancora cambiare. Se riscontri problemi, abbiamo bisogno del tuo feedback.

La sincronizzazione con Dropbox mantiene i progetti di un utente sincronizzati con il suo Dropbox, come su Overleaf Cloud: quando un utente collega il proprio account Dropbox, ciascuno dei suoi progetti compare come cartella in Apps/<your Dropbox app>/, le modifiche in Overleaf vengono inviate a Dropbox e quelle fatte in Dropbox tornano in Overleaf.

​

Configurare la sincronizzazione con Dropbox

Devi prima abilitare git-bridge: senza di esso, le impostazioni dell’account nascondono la sezione di sincronizzazione dei progetti.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crea un’app nella Dropbox App Console, dopo aver effettuato l’accesso con l’account Dropbox che sarà proprietario dell’app:

1. Fai clic su Create app, quindi compila la pagina:
   • 1. Choose an API: seleziona Scoped access.
   • 2. Choose the type of access you need: seleziona App folder, non Full Dropbox. Overleaf sincronizza solo all’interno della cartella dell’app.
   • 3. Name your app: inserisci un nome, ad esempio Overleaf. Deve essere univoco su Dropbox. I progetti di ogni utente compaiono in Apps/<name of your app>/ nel suo Dropbox, e questo nome corrisponde a DROPBOX_APP_NAME più avanti.
   • Fai clic su Create app. L’app si apre nella scheda Settings.
2. Nella scheda Permissions, sotto Files and folders, seleziona files.metadata.write, files.content.write e files.content.read. account_info.read e files.metadata.read vengono selezionati insieme a questi e non possono essere deselezionati. Non selezionare altri permessi.
3. Fai clic su Submit nella barra in fondo alla scheda Permissions. Senza Submit i permessi non vengono salvati, e Dropbox rifiuta di sincronizzare i file per gli utenti che collegano il proprio account.

Dropbox App Console: i permessi da selezionare, salvati con Submit

4. Nella scheda Settings, sotto OAuth 2, inserisci ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback in Redirect URIs, quindi fai clic su Add. Digitare l’URI non basta: viene salvato solo quando compare nell’elenco sopra il campo.

Dropbox App Console: inserisci l'URI di reindirizzamento, quindi fai clic su Add

5. Nella scheda Settings, sotto Webhooks, inserisci ${OVERLEAF_SITE_URL}/dropbox/webhook in Webhook URIs, quindi fai clic su Add anche qui. Dropbox lo chiama subito per verificarlo, quindi Overleaf deve essere già in esecuzione con le impostazioni seguenti ed essere raggiungibile da internet (vedi Webhook). Il suo stato mostra Enabled una volta superata la verifica.

Copia l’App key e l’App secret (fai clic su Show) dalla scheda Settings, quindi aggiungi le seguenti impostazioni ai file delle variabili d’ambiente di Overleaf. Puoi aggiungere il webhook (passo 5) dopo che Overleaf è in esecuzione con queste impostazioni.

config/variables.env

# used to encrypt the user's Dropbox refresh token.
# How to generate: `openssl rand -hex 32`
DROPBOX_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Dropbox Sync Settings
DROPBOX_ENABLED=true
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
# the name of your Dropbox app (step 1), which is the folder name in Apps/
DROPBOX_APP_NAME=Overleaf

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback
# Webhook is: ${OVERLEAF_SITE_URL}/dropbox/webhook
# (Optional) DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808

• Prima di configurare l’URI di reindirizzamento e il webhook, assicurati che OVERLEAF_SITE_URL sia impostato correttamente.
• Dropbox fissa i permessi di un token nel momento in cui l’utente collega il proprio account: inviare i permessi non modifica i token esistenti. Gli utenti che si sono collegati prima che i permessi venissero inviati, o prima che tu li modificassi, devono scollegare e ricollegare il proprio account Dropbox.
• Una nuova app è in stato Development. Se Development users nella scheda Settings mostra Only you, solo il tuo account Dropbox può essere collegato: fai clic su Enable additional users per consentire agli altri utenti di collegare il proprio. Verrà quindi mostrato quanti utenti si sono collegati, ad esempio 1 / 500: un’app in Development accetta al massimo 500 utenti. Per più utenti, fai clic su Apply for production e Dropbox esaminerà l’app.

Se ti trovi in una regione con accesso alla rete limitato, potrebbe essere necessario configurare un proxy per accedere a Dropbox. Imposta la seguente variabile d’ambiente: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. Deve essere un proxy di inoltro HTTP/HTTPS standard e non deve usare 127.0.0.1.

​

Creare gli indici del database

Esegui questa operazione una sola volta, prima che gli utenti colleghino i propri account Dropbox. Gli indici usati dalla sincronizzazione con Dropbox non vengono creati automaticamente, quindi senza di essi ogni ricerca della sincronizzazione scansiona l’intera collezione.

Se usi il Toolkit, esegui bin/mongo. Se usi Docker Compose, esegui docker compose exec mongo mongosh sharelatex. Poi incolla:

db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'dropbox.id': 1 },
  { name: 'overleaf.userId_1_dropbox.id_1', unique: true,
    partialFilterExpression: { 'dropbox.id': { $exists: true } } })
db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'overleaf.id': 1 },
  { name: 'overleaf.userId_1_overleaf.id_1', unique: true,
    partialFilterExpression: { 'overleaf.id': { $exists: true } } })
db.dropboxEntities.createIndex({ 'overleaf.userId': 1, 'dropbox.pathLower': 'hashed' })
db.dropboxProjects.createIndex({ userId: 1, projectId: 1 }, { name: 'projectId_userId_1', unique: true })
db.dropboxProjects.createIndex({ userId: 1, dropboxId: 1 }, { name: 'userId_dropboxId_1', unique: true })

Eseguirlo di nuovo non causa problemi: MongoDB salta gli indici già esistenti.

Non eseguire al suo posto le migrazioni dropboxEntities di tools/migrations: 20220825160708_recreate_dropboxEntities elimina la collezione, cancellando lo stato di sincronizzazione di tutti gli utenti.

​

Webhook

Dropbox notifica a Overleaf le modifiche in Dropbox tramite un webhook, così compaiono in Overleaf nel giro di pochi secondi. Il webhook punta all’indirizzo del tuo sito, ${OVERLEAF_SITE_URL}/dropbox/webhook, e non serve alcuna porta aggiuntiva, ma Dropbox deve poterlo raggiungere da internet. Quando lo aggiungi nella App Console, Dropbox lo verifica subito.

Senza webhook, ad esempio su un server che Dropbox non può raggiungere, le modifiche in Overleaf vengono comunque inviate a Dropbox, ma quelle fatte in Dropbox tornano solo quando un utente fa clic su sincronizza ora questo progetto nella finestra Dropbox dell’editor.

​

Come funziona la sincronizzazione

• Collegamento: quando un utente collega il proprio account Dropbox, i progetti di cui è proprietario vengono inviati a Dropbox. I progetti condivisi con lui compaiono in Dropbox alla loro modifica successiva.
• Da Overleaf a Dropbox: nuovi file, rinomine, spostamenti, eliminazioni e rinomine di progetti vengono inviati subito. Le modifiche nell’editor vengono inviate quando Overleaf le salva nel proprio storage, qualche minuto dopo che tutti hanno lasciato il progetto. Per inviarle prima, fai clic su sincronizza ora questo progetto nella finestra Dropbox dell’editor (una volta al minuto).
• Da Dropbox a Overleaf: file nuovi e modificati, nuove cartelle ed eliminazioni in una cartella di progetto vengono applicati al progetto. Una nuova cartella al primo livello della cartella dell’app diventa un nuovo progetto. Eliminare la cartella di un progetto in Dropbox contrassegna il progetto come eliminato in Overleaf.
• Conflitti: quando un file cambia contemporaneamente in entrambi i posti, prevale l’ultima modifica. Dropbox può conservare l’altra versione come copia in conflitto.
• Collaboratori: i collaboratori che collegano il proprio Dropbox ricevono i progetti condivisi con loro. Gli utenti in sola lettura e i revisori ricevono il progetto, ma le loro modifiche in Dropbox non vengono sincronizzate in Overleaf.
• File ignorati: i file che Overleaf non sincronizza, come l’output di compilazione (.aux, .log, …), .DS_Store o gli ambienti virtuali Python, restano solo in Dropbox.

​

Q&A

Perché un utente non riesce a collegare il proprio account Dropbox?

• Una cartella Dropbox che Overleaf non conosce ancora viene associata a un progetto in base al nome, quindi a un utente i cui progetti hanno lo stesso nome viene chiesto di rinominarli prima. I nomi vengono confrontati senza distinguere tra maiuscole e minuscole, e contano anche i progetti archiviati e quelli nel cestino.
• Un account Dropbox può essere collegato a un solo account Overleaf.

Perché un account Dropbox è stato scollegato?

Risposta: Overleaf scollega un account Dropbox quando Dropbox rifiuta il suo token (ad esempio dopo che l’utente ha rimosso l’app in Dropbox), quando il Dropbox è pieno o quando Dropbox ha sospeso l’account. Una notifica nell’elenco dei progetti indica all’utente quale di questi casi si è verificato, finché non ricollega l’account. L’utente può ricollegarlo una volta risolto il problema.

Posso rinominare la cartella di un progetto in Dropbox?

Risposta: Ti preghiamo di rinominare invece il progetto in Overleaf: anche la sua cartella in Dropbox viene rinominata. Per Overleaf, rinominare la cartella in Dropbox equivale a eliminare la cartella del progetto e crearne una nuova, quindi il vecchio progetto viene contrassegnato come eliminato e viene creato un nuovo progetto a partire dai file.

Perché alcune cartelle di progetto sono numerate, come «Thesis (1)»?

Risposta: Ogni progetto ha una propria cartella, anche quando due progetti hanno lo stesso nome. Dropbox non può contenere due cartelle con lo stesso nome, quindi aggiunge un numero alla cartella creata per seconda. Il numero dipende da quali nomi erano liberi in Dropbox in quel momento, non da quale progetto è più vecchio. Overleaf conosce la cartella di ogni progetto, quindi le modifiche non finiscono mai nella cartella di un altro progetto con lo stesso nome.

Anche un progetto caricato il cui nome è già in uso riceve in Overleaf un nome con un numero, ad esempio «Thesis (1)».

Cosa succede quando elimino la cartella di un progetto in Dropbox?

• Se nessun altro progetto ha il nome della cartella, il progetto viene contrassegnato come eliminato in Overleaf. I suoi file e la sua cronologia vengono conservati.
• Se più progetti hanno quel nome, Overleaf non può sapere a quale apparteneva la cartella. Scollega l’account Dropbox e mostra una notifica che chiede di rinominare i progetti. Assegna nomi distinti ai progetti prima di eliminarne le cartelle in Dropbox.
• Una cartella numerata, come «Thesis (1)», non corrisponde ad alcun nome di progetto, quindi eliminarla non modifica il progetto in Overleaf. Fai clic su sincronizza ora questo progetto nella finestra Dropbox dell’editor per inviare di nuovo il progetto a Dropbox.

Cosa succede in Dropbox quando elimino un progetto in Overleaf?

Risposta: Niente, la sua cartella resta in Dropbox. Elimina la cartella in Dropbox se non ti serve più.

Cosa succede alle modifiche in Dropbox mentre un progetto è archiviato o nel cestino?

Risposta: Non vengono applicate al progetto, e nemmeno il ripristino del progetto le importa. Dopo il ripristino, Overleaf smette di inviare le proprie modifiche ai file che nel frattempo sono stati modificati in Dropbox, quindi le due parti differiscono.

Per sincronizzare di nuovo un file di questo tipo, salvalo ancora una volta in Dropbox. Overleaf adotta allora la versione di Dropbox: le modifiche apportate al file in Overleaf dopo il ripristino vengono sostituite e restano nella cronologia del progetto. Ripristina un progetto prima di modificarlo in Dropbox.

Perché il link a Dropbox nell'editor apre la home page di Dropbox?

Risposta: Il link punta a Apps/<app folder>/<project> su dropbox.com, come su Overleaf Cloud. Quando Dropbox mostra la cartella Apps con un nome tradotto, ad esempio 应用 in cinese, il link non trova la cartella e Dropbox apre invece la sua home page. Apri la cartella del progetto dalla cartella Apps tradotta in Dropbox.

Perché in Dropbox mancano alcuni file di un progetto?

Risposta: Le modifiche apportate mentre il servizio di sincronizzazione non era in esecuzione, ad esempio durante un riavvio, non vengono inviate a Dropbox in seguito. Fai clic su sincronizza ora questo progetto nella finestra Dropbox dell’editor: invia di nuovo l’intero progetto.