From ffb4cab002545318d6013902f147a69a2a27bb61 Mon Sep 17 00:00:00 2001 From: Stefano Pigozzi Date: Wed, 24 Nov 2021 10:35:21 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=93=20Review=20and=20improve=20all=20c?= =?UTF-8?q?hapters=20so=20far?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- thesis/source/docs/1_sinossi/index.rst | 7 +- thesis/source/docs/2_introduzione/index.rst | 14 +- thesis/source/docs/3_presentazione/index.rst | 38 +-- thesis/source/docs/4_progetto/index.rst | 302 +++++++++--------- .../source/docs/5_implementazione/index.rst | 126 ++++---- thesis/source/refs.bib | 10 +- 6 files changed, 243 insertions(+), 254 deletions(-) diff --git a/thesis/source/docs/1_sinossi/index.rst b/thesis/source/docs/1_sinossi/index.rst index 190bcb9..bfdc450 100644 --- a/thesis/source/docs/1_sinossi/index.rst +++ b/thesis/source/docs/1_sinossi/index.rst @@ -1,10 +1,11 @@ .. index:: - single: sinossi - single: abstract + pair: tesi; sinossi Sinossi ******* La tesi descrive lo sviluppo di **Sophon**, software che permette a gruppi di ricerca di collaborare in sicurezza da remoto all'interno di ambienti `Jupyter` eseguiti sui server della loro organizzazione. -.. image:: screenshot.png +.. figure:: screenshot.png + + Cattura schermo dell'interfaccia grafica di Sophon. diff --git a/thesis/source/docs/2_introduzione/index.rst b/thesis/source/docs/2_introduzione/index.rst index 6049d9f..f64cafc 100644 --- a/thesis/source/docs/2_introduzione/index.rst +++ b/thesis/source/docs/2_introduzione/index.rst @@ -1,9 +1,9 @@ .. index:: - single: introduzione + pair: tesi; introduzione -************ -Introduzione -************ +********************** +Introduzione alla tesi +********************** Nel mondo della ricerca universitaria, è frequente la collaborazione tra più colleghi su uno stesso progetto, condividendo dati e materiale al fine di ottenere risultati più efficientemente. @@ -19,7 +19,7 @@ Jupyter però ha alcuni problemi: è complesso da installare e mantenere, e non .. index:: - single: obiettivo della tesi + pair: tesi; obiettivo Obiettivo della tesi ==================== @@ -28,7 +28,7 @@ L'obiettivo di questa tesi è quello di descrivere lo sviluppo dell'applicativo .. index:: - single: struttura della tesi + pair: tesi; struttura Struttura della tesi ==================== @@ -40,7 +40,7 @@ Struttura della tesi La tesi è strutturata nel seguente modo: #. nel primo capitolo, :ref:`Sinossi`, viene descritto molto brevemente il progetto realizzato; -#. nel secondo capitolo, :ref:`Introduzione`, viene introdotto il contesto della tesi, la tesi stessa e i suoi contenuti; +#. nel secondo capitolo, :ref:`Introduzione alla tesi`, viene introdotto il contesto della tesi, la tesi stessa e i suoi contenuti; #. nel terzo capitolo, :ref:`Ricerca collaborativa`, viene presentata in dettaglio la situazione attuale della ricerca collaborativa; #. nel quarto capitolo, :ref:`Progettazione`, viene descritta la progettazione avvenuta, entrando nei dettagli dei requisiti, della suddivisione in moduli e delle astrazioni create; #. nel quinto capitolo, :ref:`Implementazione`, vengono trattate le specifiche tecniche implementative del progetto; diff --git a/thesis/source/docs/3_presentazione/index.rst b/thesis/source/docs/3_presentazione/index.rst index 00ff549..3753622 100644 --- a/thesis/source/docs/3_presentazione/index.rst +++ b/thesis/source/docs/3_presentazione/index.rst @@ -11,8 +11,7 @@ Mentre in passato a tale scopo venivano utilizzati quaderni di carta (detti anch .. index:: - single: composizione tipografica - single: sistemi di composizione tipografica + pair: sistemi; composizione tipografica Sistemi di composizione tipografica =================================== @@ -34,7 +33,7 @@ Un esempio di documento LaTeX :cite:`overleaf:learn30mins` è il seguente: .. index:: - single: editor WYSIWYG + pair: editor; WYSIWYG Editor WYSIWYG ============== @@ -53,7 +52,7 @@ Alcuni esempi moderni di editor :abbr:`WYSIWYG (What You See Is What You Get)` s .. index:: - single: editor WYSIWYG; web-based + pair: editor; web-based Web-based editor ================ @@ -72,8 +71,8 @@ Il più importante di questi editor è `Google Docs `_ .. index:: - single: notebook computazionale - single: celle + single: notebook; computazionali + pair: notebook; celle Notebook computazionali ======================= @@ -109,16 +108,16 @@ Prende ispirazione dai `web-based editor `, permettendo agli u .. index:: - single: Jupyter; parti di + pair: Jupyter; componenti -Parti di Jupyter ----------------- +Componenti di Jupyter +--------------------- -Jupyter è composto da 3 parti: un `kernel `, un `server ` e un `client `. +Jupyter è composto da 3 componenti: un `kernel `, un `server ` e un `client `. .. index:: - single: Jupyter; kernel + pair: Jupyter; kernel single: IPython Kernel Jupyter @@ -130,7 +129,7 @@ Per ogni linguaggio di programmazione che si desidera utilizzare nel notebook è .. index:: - single: Jupyter; server + pair: Jupyter; server Server Jupyter ^^^^^^^^^^^^^^ @@ -141,9 +140,9 @@ Il server ufficiale di Jupyter è `Jupyter Server ` e `client ` separati, è possi È possibile selezionare la macchina su cui eseguire il server in tre modi diversi, elencati nelle prossime sezioni, ciascuno con alcuni vantaggi e svantaggi. -.. index:: - single: Jupyter; hosting locale - Hosting locale ^^^^^^^^^^^^^^ @@ -180,7 +176,6 @@ In base al proprio sistema operativo, però, potrebbe risultare difficile da ins .. index:: - single: Jupyter; come software-as-a-service single: Google Colaboratory single: SageMaker Notebook @@ -197,8 +192,7 @@ In genere, però, Jupyter sulle piattaforme :abbr:`SaaS (Software as a Service)` .. index:: - single: Jupyter; hosting on-premises - single: Jupyter; Hub + single: Jupyter; JupyterHub Hosting on-premises ^^^^^^^^^^^^^^^^^^^ diff --git a/thesis/source/docs/4_progetto/index.rst b/thesis/source/docs/4_progetto/index.rst index 6fa681a..4b75ec5 100644 --- a/thesis/source/docs/4_progetto/index.rst +++ b/thesis/source/docs/4_progetto/index.rst @@ -1,18 +1,18 @@ .. index:: - single: progettazione + pair: Sophon; progettazione -************* -Progettazione -************* +*********************** +Progettazione di Sophon +*********************** Vista la situazione della `ricerca collaborativa `, si è ritenuto potesse essere utile sviluppare un'alternativa al `progetto JupyterHub `. .. index:: - single: requisiti + pair: Sophon; requisiti del progetto -Requisiti -========= +Requisiti del progetto +====================== Si è stabilito che per essere un'alternativa valida, il progetto dovesse avere i seguenti requisiti: @@ -28,8 +28,7 @@ Seguono descrizioni dettagliate dei requisiti elencati. .. index:: - single: requisiti; estendibilità - single: estendibilità + pair: requisiti; estendibilità Estendibilità ------------- @@ -42,8 +41,7 @@ Infine, il software deve esporre un'**interfaccia alla quale altri software este .. index:: - single: requisiti; sicurezza - single: sicurezza + pair: requisiti; sicurezza Sicurezza --------- @@ -58,8 +56,7 @@ Non si reputa nemmeno importante limitare le risorse utilizzate dai `notebook `, si è scelto .. index:: pair: modulo; backend -Progetto del Modulo backend ---------------------------- +Modulo backend +-------------- Il modulo backend consiste in una web :abbr:`API (application programming interface)` che si interfaccia con il database e i moduli Jupyter, permettendo un accesso controllato alle risorse del software. @@ -214,17 +205,17 @@ Poetry è in grado di risolvere automaticamente alberi complessi di dipendenze, .. index:: single: Django - single: Django; applicazione - single: Django; view - single: Django; function-based view - single: Django; class-based view + pair: Django; app + pair: Django; view + pair: Django; function-based view + pair: Django; class-based view Django ^^^^^^ `Django `_ è un framework Python per lo sviluppo di siti web dinamici. -Fornisce una suite di strumenti che assistono nella creazione di siti di medie dimensioni, come un :abbr:`ORM (object-relational model)` per i database, una pagina di amministrazione integrata per la gestione dei contenuti del sito e un sistema di moduli scollegabili detti "applicazioni". +Fornisce una suite di strumenti che assistono nella creazione di siti di medie dimensioni, come un :abbr:`ORM (object-relational model)` per i database, una pagina di amministrazione integrata per la gestione dei contenuti del sito e un sistema di moduli scollegabili detti "app". Le pagine restituite vengono definite attraverso funzioni, dette *function-based views*, o attraverso classi, dette *class-based views*, che ricevono in input la richiesta effettuata dall'utente ed restituscono in output la risposta HTTP da inoltrargli. @@ -233,9 +224,9 @@ Le pagine restituite vengono definite attraverso funzioni, dette *function-based .. index:: single: Django REST Framework - single: Django REST Framework; function-based API view - single: Django REST Framework; class-based API view - single: Django REST Framework; viewset + pair: Django REST Framework; function-based API view + pair: Django REST Framework; class-based API view + pair: Django REST Framework; viewset Django REST Framework ^^^^^^^^^^^^^^^^^^^^^ @@ -371,8 +362,8 @@ Non essendo immediatamente utilizzabile all'interno delle pagine web, deve esser .. index:: single: React - single: React; componente - single: React; hook + pair: React; componente + pair: React; hook React ^^^^^ @@ -411,7 +402,7 @@ FontAwesome .. index:: single: Bluelib - single: Bluelib; tema + pair: Bluelib; tema Bluelib ^^^^^^^ @@ -424,16 +415,25 @@ Si basa sul concetto di **pannelli**, sezioni di pagina separate dal resto trami Fa ampio uso delle `CSS Custom Properties `_, permettendo lo sviluppo di vari *temi* con aspetto differente. -.. image:: bluelib_paper.png - :scale: 25% -.. image:: bluelib_royalblue.png - :scale: 25% -.. image:: bluelib_sophon.png - :scale: 25% -.. image:: bluelib_hacker.png - :scale: 25% -.. image:: bluelib_amber.png - :scale: 25% +.. figure:: bluelib_royalblue.png + + Il tema "Royal Blue" di Bluelib, da cui ha origine il nome. + +.. figure:: bluelib_paper.png + + Il tema "Sheet of Paper" di Bluelib, pensato per la stampa su carta. + +.. figure:: bluelib_sophon.png + + Il tema "Sophon" di Bluelib, creato appositamente per questo progetto. + +.. figure:: bluelib_hacker.png + + Il tema "Hacker Terminal" di Bluelib, creato per testare la visualizzazione di caratteri monospace. + +.. figure:: bluelib_amber.png + + Il tema "Gestione Amber" di Bluelib, realizzato da Lorenzo Balugani. .. index:: @@ -483,9 +483,9 @@ In un'installazione predefinita di Sophon, il reverse proxying effettuato è dup .. index:: - single: Apache HTTP server + single: Apache; HTTP server single: httpd - single: apache2 + single: Apache; apache2 Apache HTTP server ^^^^^^^^^^^^^^^^^^ @@ -544,10 +544,8 @@ Docker .. index:: - single: image - single: immagine - single: Docker; image - single: Docker; immagine + pair: Docker; image + pair: Docker; immagine Immagini ^^^^^^^^ @@ -560,8 +558,7 @@ Possono essere comparate a immagini di macchine virtuali con tanti "punti di rip .. index:: - single: container - single: Docker; container + pair: Docker; container Container ^^^^^^^^^ @@ -572,8 +569,7 @@ Sono l'equivalente di un'intera macchina virtuale, che può essere avviata o arr .. index:: - single: network - single: Docker; network + pair: Docker; network Network ^^^^^^^ @@ -586,8 +582,7 @@ Sono una versione più potente dei moduli di rete per macchine virtuali. .. index:: - single: volume - single: Docker; volume + pair: Docker; volume Volumi ^^^^^^ @@ -600,7 +595,7 @@ Sono il parallelo delle immagini disco delle macchine virtuali. .. index:: - single: Docker; Engine + pair: Docker; Engine Docker Engine ------------- @@ -611,7 +606,7 @@ Astrae la piattaforma su cui viene eseguito, in modo che tutte le immagini possa .. index:: - single: Docker; Compose + pair: Docker; Compose Docker Compose -------------- @@ -653,20 +648,60 @@ Le applicazioni Compose sono definite all'interno di un file `YAML ` attorno a Sophon, si è deciso di pubblicare il progetto su `GitHub`, sotto la licenza `AGPL 3.0+`. + + +.. index:: + single: Git + pair: Git; repository + pair: Git; commit + +Git +--- + +`Git `_ è un software di controllo versione, ovvero un software in grado di tenere traccia di modifiche effettuate su file, in modo da mantenerne uno storico, e permettere a più autori di lavorare in parallelo su documenti. + +Inizialmente realizzato da Linus Torvalds per lo sviluppo del kernel Linux, ha preso velocemente piede in tutto il settore dello sviluppo software, diventando di fatto lo standard per lo sviluppo collaborativo di software. + +Le cartelle di file tracciate da Git sono dette *repository*, mentre un blocco atomico di modifiche è detto *commit*. + + +.. index:: + pair: Git; GitHub + +GitHub +------ + +`GitHub `_ è un servizio web di Microsoft per l'hosting e la pubblicazione di repository Git. + +Per ciascun repository sono messe a disposizione gratuitamente numerose funzionalità, quali un issue tracker, strumenti di code review e sistemi di automazione per lo sviluppo :cite:`github:features`. + + +.. index:: + pair: Sophon; entità + +Entità di Sophon +================ Al fine di definire più in dettaglio le operazioni che devono poter essere effettuate all'interno di Sophon, sono state definite delle *entità*, i tipi base con cui l'utente può interagire. .. index:: - single: istanza + pair: Sophon; istanza -Istanza -------- +Istanza in Sophon +----------------- Un'*istanza* rappresenta un'**installazione di Sophon** effettuata su un server di un'istituzione di ricerca, come ad esempio un'Università. @@ -683,10 +718,10 @@ Ciascuna istanza è accessibile tramite **uno specifico URL**, scelto dall'ammin .. index:: - single: utente + pair: Sophon; utente -Utente ------- +Utenti in Sophon +---------------- Un *utente* è una entità che interagisce con una specifica istanza Sophon: ad esempio, un utente potrebbe essere una persona fisica, oppure potrebbe essere un software di automazione che si interfaccia con Sophon. @@ -694,11 +729,9 @@ La tabella viene creata automaticamente da Django all'interno di ogni applicazio .. index:: - single: utente; super - single: utente; regolare - single: utente; ospite - single: superutente - single: ospite + pair: Sophon; superutente + pair: Sophon; ospite + pair: Sophon; livello di accesso Livelli di accesso ^^^^^^^^^^^^^^^^^^ @@ -716,10 +749,10 @@ Ospite .. index:: - single: credenziali di accesso - single: username - single: password - single: Single Sign-On + pair: Sophon; credenziali di accesso + pair: Sophon; username + pair: Sophon; password + pair: Sophon; Single Sign-On Credenziali di accesso ^^^^^^^^^^^^^^^^^^^^^^ @@ -730,27 +763,22 @@ Di default, le credenziali sono un **nome utente** e una **password**, ma è pos .. warning:: - Non avendo a disposizione sistemi di :abbr:`SSO (Single Sign-On)`, questa funzionalità non è stata testata. + Non avendo a disposizione sistemi di :abbr:`SSO (Single Sign-On)`, questa funzionalità non è stata testata, e potrebbe non funzionare. .. index:: - single: gruppo di ricerca + pair: Sophon; gruppo -Gruppo di ricerca ------------------ +Gruppi di ricerca in Sophon +--------------------------- Un *gruppo di ricerca* rappresenta un insieme di utenti che collaborano su uno o più progetti. -.. index:: - single: gruppo di ricerca; aperto - single: gruppo di ricerca; modalità manuale - single: gruppo di ricerca; membri - Membri e modalità di accesso ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Gli utenti dell':ref:`istanza` possono diventare *membri* dei gruppi di ricerca, con una delle seguenti modalità selezionate nelle impostazioni del gruppo: +Gli utenti dell'`istanza ` possono diventare *membri* dei gruppi di ricerca, con una delle seguenti modalità selezionate nelle impostazioni del gruppo: - se il gruppo è *aperto*, allora qualsiasi utente potrà diventarne membro semplicemente **facendo richiesta** attraverso l'interfaccia web; - se il gruppo è in *modalità manuale*, allora nessun utente potrà richiedere di unirsi, e i membri saranno **selezionati manualmente** dal creatore del gruppo. @@ -758,29 +786,20 @@ Gli utenti dell':ref:`istanza` possono diventare *membri* dei gruppi di ricerca, In qualsiasi momento, i membri di un gruppo possono **lasciarlo** facendo apposita richiesta attraverso il frontend. -.. index:: - single: gruppo di ricerca; creazione - Creazione di nuovi gruppi ^^^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi :ref:`utente` può **creare** gruppi di ricerca dall'interfaccia web. +Qualsiasi `utente ` può **creare** gruppi di ricerca dall'interfaccia web. -.. index:: - single: gruppo di ricerca; modifica - Modifica di gruppi ^^^^^^^^^^^^^^^^^^ -Il creatore di un gruppo di ricerca è l'unico :ref:`utente` che può cambiarne **nome**, **descrizione**, **membri** e **modalità di accesso**. +Il creatore di un gruppo di ricerca è l'unico `utente ` che può cambiarne **nome**, **descrizione**, **membri** e **modalità di accesso**. Lo *slug*, l'identificatore univoco del gruppo, non è modificabile successivamente alla creazione, in quanto verrà utilizzato all'interno degli URL, che devono essere immutabili. -.. index:: - single: gruppo di ricerca; eliminazione - Eliminazione di gruppi ^^^^^^^^^^^^^^^^^^^^^^ @@ -792,19 +811,16 @@ Il creatore di un gruppo è l'unico utente in grado di **cancellare** il gruppo .. index:: - single: progetto di ricerca + pair: Sophon; progetto -Progetto di ricerca -------------------- +Progetti di ricerca in Sophon +----------------------------- -Un *progetto di ricerca* rappresenta una **collezione di oggetti** relativa a un singolo argomento mantenuta da un :ref:`gruppo di ricerca`. +Un *progetto di ricerca* rappresenta una **collezione di oggetti** relativa a un singolo argomento mantenuta da un `gruppo di ricerca `. .. index:: - single: progetto di ricerca; visibilità - single: progetto di ricerca; privato - single: progetto di ricerca; interno - single: progetto di ricerca; pubblico + single: Sophon; visibilità del progetto Visibilità dei progetti ^^^^^^^^^^^^^^^^^^^^^^^ @@ -812,44 +828,35 @@ Visibilità dei progetti I progetti hanno tre diverse impostazioni di visibilità che regolano chi può visualizzarne i contenuti: Progetto privato - Il progetto è visibile solo ai membri del gruppo a cui appartiene il progetto. + Il progetto è visibile **solo ai membri del gruppo** a cui appartiene il progetto. Progetto interno - Il progetto è visibile solo agli :term:`utenti` dell'istanza, e non agli :term:`ospiti`. + Il progetto è visibile **solo agli utenti** dell'istanza, e non agli ospiti. Progetto pubblico - Il progetto è visibile a tutti. + Il progetto è visibile **a tutti**. -.. index:: - single: progetto di ricerca; creazione - Creazione di nuovi progetti ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi *membro* di un :ref:`gruppo di ricerca` può creare nuovi progetti. +Qualsiasi *membro* di un `gruppo di ricerca ` può creare nuovi progetti. -.. index:: - single: progetto di ricerca; modifica - Modifica di progetti ^^^^^^^^^^^^^^^^^^^^ -Qualsiasi *membro* di un :ref:`gruppo di ricerca` può modificare **nome**, **descrizione** dei progetti al suo interno. +Qualsiasi *membro* di un `gruppo di ricerca ` può modificare **nome**, **descrizione** dei progetti al suo interno. Solo il *creatore del gruppo* può modificarne la **visibilità**, o **trasferire il progetto ad un altro gruppo**. Lo *slug*, l'identificatore univoco del progetto, non è modificabile successivamente alla creazione, in quanto è utilizzato all'interno degli URL, che devono essere immutabili. -.. index:: - single: progetto di ricerca; eliminazione - Eliminazione di progetti ^^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi *membro* di un :ref:`gruppo di ricerca` può eliminare i progetti al suo interno. +Qualsiasi *membro* di un `gruppo di ricerca ` può eliminare i progetti al suo interno. .. danger:: @@ -857,7 +864,7 @@ Qualsiasi *membro* di un :ref:`gruppo di ricerca` può eliminare i progetti al s .. index:: - single: notebook (entità) + pair: Sophon; notebook Notebook -------- @@ -865,18 +872,12 @@ Notebook Un *notebook* rappresenta una **postazione di lavoro** che può essere allegata ad un :ref:`progetto di ricerca`. -.. index:: - single: notebook (entità); creazione - Creazione di nuovi notebook ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi **membro** di un :ref:`gruppo di ricerca` può creare nuovi notebook all'interno di uno dei progetti del gruppo a cui appartiene. +Qualsiasi **membro** di un `gruppo di ricerca ` può creare nuovi notebook all'interno di uno dei progetti del gruppo a cui appartiene. -.. index:: - single: notebook (entità); slug riservati - Slug riservati ^^^^^^^^^^^^^^ @@ -889,13 +890,11 @@ Un notebook non può avere come *slug* uno dei seguenti valori, in quanto riserv * ``static`` * ``src`` -In più, uno slug di un notebook non può iniziare o terminare con un trattino ``-``, in quanto risulterebbe in un URL non valido. +In più, uno slug di un notebook non può iniziare o terminare con un trattino ``-``, in quanto risulterebbe in un sottodominio non valido. .. index:: - single: notebook (entità); stato - single: notebook (entità); avviato - single: notebook (entità); fermo + pair: Sophon; stato del notebook Stato del notebook ^^^^^^^^^^^^^^^^^^ @@ -911,17 +910,17 @@ Alla creazione, un notebook è *fermo*. Avviare un notebook """"""""""""""""""" -Un **membro** del :ref:`gruppo di ricerca` a cui appartiene il notebook può richiedere al server l'avvio di quest'ultimo, in modo da poterlo utilizzare successivamente. +Un **membro** del `gruppo di ricerca ` a cui appartiene il notebook può richiedere al server l'avvio di quest'ultimo, in modo da poterlo utilizzare successivamente. Fermare un notebook """"""""""""""""""" -Un **membro** del :ref:`gruppo di ricerca` a cui appartiene il notebook può richiedere al server l'arresto di quest'ultimo, salvando i dati e interrompendo la sessione di lavoro attualmente in corso. +Un **membro** del `gruppo di ricerca ` a cui appartiene il notebook può richiedere al server l'arresto di quest'ultimo, salvando i dati e interrompendo la sessione di lavoro attualmente in corso. .. index:: - single: notebook (entità); immagine + pair: Sophon; immagine Immagine del notebook ^^^^^^^^^^^^^^^^^^^^^ @@ -933,24 +932,21 @@ Di default, l'immagine deve essere quella del `modulo Jupyter `. Le immagini ammesse devono esporre un server HTTP sulla porta 8080, su cui verrà fatto `reverse proxying ` dal `modulo proxy `. -.. index:: - single: notebook (entità); collegamento - Collegamento a un notebook ^^^^^^^^^^^^^^^^^^^^^^^^^^ -I **membri** del :ref:`gruppo di ricerca` a cui appartiene il notebook possono connettersi ad un notebook **avviato** attraverso un URL segreto comunicatogli dal `modulo backend `. +I **membri** del `gruppo di ricerca ` a cui appartiene il notebook possono connettersi ad un notebook **avviato** attraverso un URL segreto comunicatogli dal `modulo backend `. L'URL segreto è ottenuto inserendo come query parameter dell'URL del notebook il token di autenticazione di `Jupyter`. .. index:: - single: notebook (entità); blocco + pair: Sophon; notebook bloccato Blocco di un notebook ^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi **membro** del :ref:`gruppo di ricerca` a cui appartiene il notebook può *bloccarlo* per segnalare agli altri utenti che vi hanno accesso di non utilizzare quello specifico notebook. +Qualsiasi **membro** del `gruppo di ricerca ` a cui appartiene il notebook può *bloccarlo* per segnalare agli altri utenti che vi hanno accesso di non utilizzare quello specifico notebook. Bloccare un notebook **rimuove dall'interfaccia web** i bottoni di interazione con esso per tutti gli utenti, tranne quello che ha richiesto il blocco. @@ -958,33 +954,27 @@ Bloccare un notebook **rimuove dall'interfaccia web** i bottoni di interazione c Il blocco di un notebook **è solo estetico**, e non ha lo scopo di impedire agli utenti di interagire con il notebook, ma serve per indicare ai propri collaboratori che si stanno effettuando modifiche grandi che non permettono collaborazione sul notebook. -Un notebook bloccato può essere sbloccato da qualsiasi **membro** del :ref:`gruppo di ricerca`; il membro che ha richiesto il blocco potrà sbloccarlo **immediatamente**, mentre agli altri membri è richiesto di confermare l'azione. +Un notebook bloccato può essere sbloccato da qualsiasi **membro** del `gruppo di ricerca `; il membro che ha richiesto il blocco potrà sbloccarlo **immediatamente**, mentre agli altri membri è richiesto di confermare l'azione. -.. index:: - single: notebook (entità); modifica - Modifica di un notebook ^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi *membro* di un :ref:`gruppo di ricerca` può modificare **nome** e **immagine** dei notebook *fermi* al suo interno. +Qualsiasi *membro* di un `gruppo di ricerca ` può modificare **nome** e **immagine** dei notebook *fermi* al suo interno. I notebook *avviati* non possono essere modificati. Lo *slug*, l'identificatore univoco del notebook, non è modificabile successivamente alla creazione, in quanto è utilizzato all'interno degli URL, che devono essere immutabili. -.. index:: - single: notebook (entità); eliminazione - Eliminazione di un notebook ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Qualsiasi *membro* di un :ref:`gruppo di ricerca` può eliminare i notebook all'interno dei progetti del gruppo, a condizione che questi siano *fermi* e *non bloccati*. +Qualsiasi *membro* di un `gruppo di ricerca ` può eliminare i notebook all'interno dei progetti del gruppo, a condizione che questi siano *fermi* e *non bloccati*. .. index:: - single: database + pair: Sophon; database single: PostgreSQL Database diff --git a/thesis/source/docs/5_implementazione/index.rst b/thesis/source/docs/5_implementazione/index.rst index 5780420..2564c17 100644 --- a/thesis/source/docs/5_implementazione/index.rst +++ b/thesis/source/docs/5_implementazione/index.rst @@ -1,61 +1,32 @@ .. index:: - single: implementazione + pair: Sophon; realizzazione -*************** -Implementazione -*************** +*********************** +Realizzazione di Sophon +*********************** -Ultimato il progetto, si è passati alla sua implementazione su calcolatore. +Terminato il progetto, si è passati a realizzarne una versione funzionante su calcolatore. -.. todo:: Create index - -.. todo:: Fix references - -.. todo:: Add details - - -.. index:: - single: Git; repository - -Repository Git -============== - - - -.. index:: - single: Git - -Git ---- - - -GitHub ------- - -.. todo:: GitHub +.. todo:: Inserire nell'indice tutte le sezioni. .. index:: pair: implementazione; backend -Implementazione del modulo backend -================================== +Realizzazione del modulo backend +================================ .. default-domain:: py -.. todo:: Implementazione del modulo backend - - -Ambiente virtuale Python ------------------------- - -.. todo:: Ambiente virtuale Python +Il modulo backend è stato realizzato come un package `Python` denominato ``sophon``, e poi `containerizzato `, creando un'immagine `Docker` standalone. Il project Django ----------------- .. module:: sophon -Il project del modulo aggiunge alla struttura base autogenerata da Django alcune funzionalità utili all'intero backend. +Il package è stato creato utilizzando l'utility ``startproject`` di Django, la quale crea una cartella di script `Python` con i quali partire per lo sviluppo di una nuovo software web. + +La cartella generata è stata modificata significativamente: ne si è modificata la struttura in modo tale da trasformarla da un insieme di script a un vero e proprio modulo Python eseguibile e distribuibile, e si sono aggiunte nuove funzionalità di utilità generale all'applicazione, quali una `pagina di amministrazione personalizzata `, il `caricamento dinamico delle impostazioni ` e vari `miglioramenti all'autenticazione ` Pagina di amministrazione personalizzata @@ -91,11 +62,11 @@ Inoltre, il template predefinito viene sovrascritto da quello all'interno del fi `.SophonAdminSite` è selezionata come classe predefinita per il sito di amministrazione. -Impostazioni dinamiche -^^^^^^^^^^^^^^^^^^^^^^ +Caricamento dinamico delle impostazioni +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: sophon.settings -Il file di impostazioni viene modificato per **permettere la configurazione attraverso variabili di ambiente** invece che attraverso il file ``settings.py``, rendendo il deployment con Docker molto più semplice. +Il file di impostazioni viene modificato per **permettere la configurazione attraverso variabili di ambiente** invece che attraverso la modifica del file ``settings.py``, rendendo la `containerizzazione ` molto più semplice. .. code-block:: python @@ -117,8 +88,8 @@ Inoltre, viene configurato il modulo `logging` per emettere testo colorato di pi } -Autenticazione migliorata -^^^^^^^^^^^^^^^^^^^^^^^^^ +Miglioramenti all'autenticazione +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: sophon.auth1 La classe `rest_framework.authentication.TokenAuthentication` viene modificata per ottenere un comportamento conforme agli standard del web. @@ -127,7 +98,7 @@ La classe `rest_framework.authentication.TokenAuthentication` viene modificata p .. attribute:: keyword = "Bearer" - Si configura `rest_framework` per accettare header di autenticazione nella forma ``Bearer ``, invece che ``Token ``. + Si configura `rest_framework` per accettare header di autenticazione nella forma ``Bearer ``, invece che il default di `rest_framework` ``Token ``. .. module:: sophon.auth2 @@ -142,8 +113,6 @@ La view `rest_framework.authtoken.views.ObtainAuthToken` viene estesa per aggiun L'app Sophon Core ----------------- -.. default-domain:: py -.. default-role:: obj .. module:: sophon.core L'app `sophon.core` è l'app principale del progetto, e non può essere disattivata, in quanto dipendenza obbligatoria di tutte le altre app. @@ -164,7 +133,7 @@ Modello base astratto ^^^^^^^^^^^^^^^^^^^^^ .. module:: sophon.core.models -Viene estesa la classe astratta `django.db.models.Model` con funzioni per stabilire il livello di accesso di un utente all'oggetto e per generare automaticamente i `rest_framework.serializers.ModelSerializer` in base al livello di accesso. +Viene estesa la classe astratta `django.db.models.Model` con funzioni per stabilire il `livello di accesso` di un `utente ` all'oggetto e per generare automaticamente i `rest_framework.serializers.ModelSerializer` in base ad esso. .. class:: SophonModel(django.db.models.Model) @@ -204,7 +173,7 @@ Viene estesa la classe astratta `django.db.models.Model` con funzioni per stabil Modello di autorizzazione astratto ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Viene definito un nuovo modello astratto, basato su `SophonModel`, che permette di determinare i permessi dell'utente in base alla sua appartenenza al gruppo a cui è collegato l'oggetto implementatore. +Viene definito un nuovo modello astratto, basato su `SophonModel`, che permette di determinare i permessi dell'`utente ` in base alla sua appartenenza al gruppo a cui è collegato l'oggetto implementatore. .. class:: SophonGroupModel(SophonModel) @@ -228,33 +197,33 @@ Viene definito un nuovo modello astratto, basato su `SophonModel`, che permette .. class:: sophon.core.enums.SophonGroupAccess(enum.IntEnum) - Enumerazione che stabilisce il livello di autorità che un utente può avere all'interno di un gruppo. + Enumerazione che stabilisce il livello di autorità che un `utente ` può avere all'interno di un `gruppo di ricerca `. .. attribute:: NONE = 0 - Utente :ref:`ospite`. + Ospite. .. attribute:: REGISTERED = 10 - :ref:`Utente` registrato. + Utente registrato. .. attribute:: MEMBER = 50 - Membro del :ref:`gruppo di ricerca`. + Membro del gruppo al quale appartiene l'oggetto. .. attribute:: OWNER = 100 - Creatore del :ref:`gruppo di ricerca`. + Creatore del gruppo al quale appartiene l'oggetto. .. attribute:: SUPERUSER = 200 - :ref:`Superutente` con privilegi universali. + Superutente con privilegi universali. Modello dei dettagli dell'istanza ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Viene creato il modello che rappresenta i dettagli dell':ref:`istanza` Sophon. +Viene creato il modello che rappresenta i dettagli dell'`istanza di Sophon `. .. class:: SophonInstanceDetails(SophonModel) @@ -265,39 +234,60 @@ Viene creato il modello che rappresenta i dettagli dell':ref:`istanza` Sophon. L'istanza unica viene creata dalla migrazione ``0004_sophoninstancedetails.py``. .. attribute:: name: CharField + + Il titolo dell'istanza Sophon. + .. attribute:: description: TextField + + La descrizione dell'istanza Sophon, da visualizzare in un riquadro "A proposito dell'istanza". + .. attribute:: theme: CharField ["sophon", "paper", "royalblue", "hacker", "amber"] + Il tema `Bluelib` dell'istanza. + .. method:: version: str :property: - :returns: La versione installata del pacchetto `sophon`. - - .. seealso:: - - :ref:`Sophon instance details` nella guida per l'amministratore. + :returns: La versione installata del pacchetto :mod:`sophon`. Modello del gruppo di ricerca ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Viene creato il modello che rappresenta un :ref:`gruppo di ricerca`. +Viene creato il modello che rappresenta un :ref:`gruppo di ricerca `. .. class:: ResearchGroup(SophonGroupModel) .. attribute:: slug: SlugField + + L'identificatore del gruppo di ricerca. + .. attribute:: name: CharField + + Il nome del gruppo di ricerca. + .. attribute:: description: TextField + + La descrizione del gruppo di ricerca, da visualizzare in un riquadro "A proposito del gruppo". + .. attribute:: members: ManyToManyField → django.contrib.auth.models.User + + Elenco dei membri del gruppo. L'utente `.owner` è ignorato, in quanto è considerato sempre parte del gruppo. + .. attribute:: owner: ForeignKey → django.contrib.auth.models.User + + Il creatore e proprietario del gruppo, con privilegi amministrativi. + .. attribute:: access: CharField ["MANUAL", "OPEN"] + La `modalità di accesso ` del gruppo. + Estensione ai permessi di Django ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. module:: sophon.core.permissions -I permessi di `rest_framework` vengono estesi con due nuove classi che utilizzano il :ref:`modello di autorizzazione` precedentemente definito. +I permessi di `rest_framework` vengono estesi con due nuove classi che utilizzano il `modello di autorizzazione astratto ` precedentemente definito. .. class:: Edit(rest_framework.permissions.BasePermission) @@ -365,14 +355,20 @@ Vengono definiti tre viewset in grado di utilizzare i metodi aggiunti dalle clas .. deprecated:: 0.1 + Metodo di `rest_framework` rimosso da Sophon. + .. method:: perform_update(self, serializer) .. deprecated:: 0.1 + Metodo di `rest_framework` rimosso da Sophon. + .. method:: perform_destroy(self, serializer) .. deprecated:: 0.1 + Metodo di `rest_framework` rimosso da Sophon. + .. method:: hook_create(self, serializer) -> dict[str, typing.Any] Funzione chiamata durante l'esecuzione dell'azione di creazione oggetto ``create``. diff --git a/thesis/source/refs.bib b/thesis/source/refs.bib index f4017e1..49147e4 100644 --- a/thesis/source/refs.bib +++ b/thesis/source/refs.bib @@ -85,4 +85,12 @@ docker:volumes, title = {Use volumes}, howpublished = {https://web.archive.org/web/20211121172749/https://docs.docker.com/storage/volumes/}, note = {Accessed: 2021-11-21}, -} \ No newline at end of file +} + +@misc{ +github:features, + author = {GitHub}, + title = {Features}, + howpublished = {https://web.archive.org/web/20211124034005/https://github.com/features}, + note = {Accessed: 2021-11-24}, +}