📔 Complete part 2

docs/source/1_user/2_concepts/1_instances/index.rst

@@ -24,33 +24,3 @@ Istanze nell'interfaccia web
 L'interfaccia web di Sophon permette di **selezionare l'istanza** che si desidera usare inserendo il corrispondente URL.
 
 .. image:: choose.png
-
-
-Personalizzazione dell'istanza
-------------------------------
-
-Nel pannello di amministrazione di un'istanza Sophon è possibile personalizzare alcuni dettagli dell'istanza, quali:
-
-- il **nome** dell'istanza, che verrà visualizzato come titolo dell'interfaccia web;
-
-  .. image:: custom_title.png
-
-- la **descrizione** dell'istanza in `Markdown`_, visualizzata all'interno del riquadro "A proposito dell'istanza";
-
-  .. image:: custom_description.png
-
-- il **tema colori** dell'istanza, applicato all'interfaccia web una volta che l'istanza è stata selezionata.
-
-  .. image:: theme_sophon.png
-     :width: 240
-  .. image:: theme_royalblue.png
-     :width: 240
-  .. image:: theme_amber.png
-     :width: 240
-  .. image:: theme_paper.png
-     :width: 240
-  .. image:: theme_hacker.png
-     :width: 240
-
-
-.. _Markdown: https://it.wikipedia.org/wiki/Markdown

docs/source/1_user/2_concepts/4_researchprojects/index.rst

@@ -23,7 +23,7 @@ I progetti hanno tre diverse impostazioni di visibilità che regolano chi può v
    Progetto pubblico
       Il progetto è visibile a tutti.
 
-I progetti privati sono marcati con l'icona di un **luchetto chiuso 🔒**, i progetti interni con l'icona di un **università 🏦** e i progetti pubblici con l'icona di un **globo 🌐**.
+I progetti privati sono marcati con l'icona di un **lucchetto chiuso 🔒**, i progetti interni con l'icona di un **università 🏦** e i progetti pubblici con l'icona di un **globo 🌐**.
 
 .. image:: icons.png
 

docs/source/2_admin/2_administration/1_admin_panel.rst

@@ -0,0 +1,32 @@
+Pannello di amministrazione
+===========================
+
+Sophon include un pannello di amministrazione, accessibile premendo *Go to the admin page* sulla schermata di login, oppure visitando l'URL ``api.DOMINIO/admin``.
+
+.. image:: admin_where.png
+
+
+Effettuare l'accesso
+--------------------
+
+Per utilizzare il pannello di amministrazione è necessario inserire le credenziali di un :ref:`superutente`.
+
+.. image:: admin_login.png
+
+
+La schermata principale
+-----------------------
+
+Nella schermata principale del pannello di amministrazione è visibile l'elenco di tutti i tipi di entità gestite da Django, assieme ad uno storico delle ultime operazioni effettuate dal pannello su di esse.
+
+.. image:: admin_home.png
+
+È possibile cliccare sul collegamento *Add* di fianco ad un tipo di entità per **crearne** una nuova di quel tipo, oppure il collegamento *Change* per **visualizzare**, **modificare** ed **eliminare** tutte le entità già esistenti di quel tipo.
+
+
+La barra del titolo
+-------------------
+
+Tutte le pagine includono in cima la **barra del titolo**, che permette al :ref:`superutente` attualmente collegato di **cambiare la propria password** o effettuare la **disconnessione** dal pannello.
+
+.. image:: topright.png

docs/source/2_admin/2_administration/2_entities.rst

@@ -0,0 +1,112 @@
+Tipi di risorse
+===============
+
+Tokens
+------
+
+Contiene l'elenco di tutti i token di sessione usati per l'autenticazione tra l'API e l'interfaccia web di Sophon.
+
+È possibile modificarli per **cambiare l'utente connesso** ad una certa sessione, oppure eliminarli per **forzare la disconnessione** di determinate sessioni.
+
+.. note::
+
+   In seguito ad una disconnessione forzata, l'utente riscontrerà errori "non autorizzato" sull'interfaccia web fino ad un aggiornamento della pagina o logout manuale.
+
+.. image:: token_list.png
+   :scale: 50%
+
+.. image:: token_detail.png
+   :scale: 50%
+
+
+Users
+-----
+
+Contiene l'elenco di tutti gli utenti registrati su Sophon.
+
+In questa pagina è possibile la :ref:`creazione di nuovi utenti`, così come il **cambio di password**, l'**assegnazione di privilegi** di :ref:`superutente` e la **disattivazione degli utenti**.
+
+.. note::
+
+   I superutenti devono avere sia *staff status* sia *superuser status* attivi per poter utilizzare il pannello di amministrazione.
+
+.. image:: user_list.png
+   :scale: 50%
+
+.. image:: user_detail.png
+   :scale: 50%
+
+
+Research groups
+---------------
+
+Contiene l'elenco di tutti i gruppi di ricerca creati su Sophon.
+
+Dal pannello di amministrazione è possibile effettuare modifiche ed eliminazioni **ignorando i permessi normalmente richiesti** per farlo e **trasferire la proprietà** di un gruppo da un utente all'altro.
+
+.. image:: researchgroup_list.png
+   :scale: 50%
+
+.. image:: researchgroup_detail.png
+   :scale: 50%
+
+
+Sophon instance details
+-----------------------
+
+Contiene un'entità speciale che controlla l'**aspetto** dell':ref:`istanza`.
+
+Modificandola, è possibile personalizzare:
+
+- il **nome** dell':ref:`istanza`, che verrà visualizzato come titolo dell'interfaccia web;
+
+  .. image:: custom_title.png
+
+- la **descrizione** dell':ref:`istanza`, visualizzata all'interno del riquadro "A proposito dell'istanza";
+
+  .. image:: custom_description.png
+
+- il **tema colori** dell':ref:`istanza`, applicato all'interfaccia web una volta che un':ref:`istanza` è stata selezionata.
+
+  .. image:: theme_sophon.png
+     :width: 240
+  .. image:: theme_royalblue.png
+     :width: 240
+  .. image:: theme_amber.png
+     :width: 240
+  .. image:: theme_paper.png
+     :width: 240
+  .. image:: theme_hacker.png
+     :width: 240
+
+
+Notebooks
+---------
+
+Contiene l'elenco di tutti i :ref:`notebook` creati su Sophon.
+
+Oltre ad alterare le entità **ignorando i permessi**, è possibile vedere alcuni parametri tecnici, come l'ID del container Docker a cui è associato il notebook, oppure la porta o l'URL a cui è accessibile il notebook dal proxy.
+
+.. warning::
+
+   Modificare *slug*, *container ID*, *local port number* o *internal URL* mentre il :ref:`notebook` è avviato renderà potenzialmente la connessione e l'arresto del notebook!
+
+.. image:: notebook_list.png
+   :scale: 50%
+
+.. image:: notebook_detail.png
+   :scale: 50%
+
+
+Research projects
+-----------------
+
+Contiene l'elenco di tutti i progetti di ricerca creati su Sophon.
+
+Oltre ad alterare le entità **ignorando i permessi**, è possibile **trasferire un progetto** da un gruppo a un altro.
+
+.. image:: researchproject_list.png
+   :scale: 50%
+
+.. image:: researchproject_detail.png
+   :scale: 50%

docs/source/2_admin/2_administration/index.rst

@@ -0,0 +1,9 @@
+Amministrazione
+***************
+
+Questo capitolo fornisce informazioni su come amministrare un':ref:`istanza` Sophon.
+
+.. toctree::
+
+   1_admin_panel
+   2_entities

docs/source/2_admin/3_update/index.rst

@@ -0,0 +1,21 @@
+Aggiornamento
+*************
+
+Per aggiornare Sophon, è sufficiente usare `Docker Compose`_ per scaricare le immagini aggiornate e riavviare i container del software.
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose down
+   root:/dock/sophon# docker compose pull
+   root:/dock/sophon# docker compose up -d
+
+.. warning::
+
+   In seguito ad un aggiornamento o un riavvio, alcuni Notebook potrebbero essere **irraggiungibili dal proxy**.
+
+   In tal caso, sarà sufficiente **fermarli** e **riavviarli** dall'interfaccia web.
+
+   Non si verificherà alcuna perdita di dati!
+
+
+.. _Docker Compose: https://docs.docker.com/compose/

docs/source/2_admin/4_uninstallation/index.rst

@@ -0,0 +1,27 @@
+Disinstallazione
+****************
+
+Per rimuovere completamente Sophon, è necessario innanzitutto arrestare i container del software principale:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose down
+
+In seguito, è necessario arrestare tutti i container dei notebook ancora avviati:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker container ls
+   c160ea085fe1   steffo45/jupyterlab-docker-sophon         "tini -g -- start-no…"   23 hours ago   Up 23 hours              sophon-container-my-first-notebook
+   0892874ea0d5   ghcr.io/steffo99/sophon-jupyter           "tini -g -- start-no…"   3 minutes ago   Up 3 minutes (healthy)  sophon-container-normal-slug
+   root:/dock/sophon# docker container rm --force c160ea085fe1 0892874ea0d5
+
+Infine sarà possibile liberare lo spazio occupato dalle risorse Docker di Sophon:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose down -v
+   root:/dock/sophon# docker volume prune
+   root:/dock/sophon# docker container prune
+   root:/dock/sophon# docker network prune
+   root:/dock/sophon# docker image prune

docs/source/3_dev/2_differences/index.rst

@@ -0,0 +1,27 @@
+Differenze con altri progetti simili
+************************************
+
+Sophon a prima vista può sembrare simile ad altri progetti già esistenti, ma si differenzia in alcune particolarità del suo funzionamento.
+
+
+Differenze con JupyterHub
+=========================
+
+`JupyterHub`_ è un progetto con scopi molto simili a quelli di Sophon, ovvero di permettere a tanti utenti di utilizzare `Jupyter`_ su un server remoto, ma ha funzionalità di autorizzazione molto semplici e non ha supporto per :ref:`collaborazione` in tempo reale, in quanto i server `Jupyter`_ che istanzia sono single-user.
+
+È però più facile da scalare per grandi numeri di utenti, e ha più opzioni di deployment, a differenza di Sophon, che ne supporta una sola.
+
+.. _JupyterHub: https://jupyter.org/hub
+.. _Jupyter: https://jupyter.org/
+
+
+Differenze con Google Colab
+===========================
+
+`Google Colab`_ è un progetto che permette di effettuare ricerca su server `Jupyter`_ utilizzando le risorse della `Google Cloud Platform`_.
+
+A differenza di Sophon, è disponibile esclusivamente come `software-as-a-service`_, il che costringe agli utenti a trasmettere le loro informazioni ai server di Google, e non ha alcun tipo di supporto alla :ref:`collaborazione` in tempo reale.
+
+.. _Google Colab: https://colab.research.google.com/#
+.. _Google Cloud Platform: https://cloud.google.com/
+.. _software-as-a-service: https://it.wikipedia.org/wiki/Software_as_a_service

docs/source/index.rst

@@ -10,6 +10,7 @@ Si è cercato di mantenere il registro di ciascuna parte al livello tecnico del
 
 .. toctree::
    :caption: Manuale utente
+   :maxdepth: 2
 
    1_user/1_about/index
    1_user/2_concepts/index
@@ -18,13 +19,17 @@ Si è cercato di mantenere il registro di ciascuna parte al livello tecnico del
 
 .. toctree::
    :caption: Guida per l'amministratore
+   :maxdepth: 2
 
    2_admin/1_installation/index
    2_admin/2_administration/index
+   2_admin/3_update/index
+   2_admin/4_uninstallation/index
 
 
 .. toctree::
    :caption: Documentazione tecnica
+   :maxdepth: 2
 
    3_dev/1_license/index
    3_dev/2_differences/index