diff --git a/docs/source/1_user/2_concepts/1_instances/index.rst b/docs/source/1_user/2_concepts/1_instances/index.rst index 4360efe..a6aa7fe 100644 --- a/docs/source/1_user/2_concepts/1_instances/index.rst +++ b/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 diff --git a/docs/source/1_user/2_concepts/4_researchprojects/index.rst b/docs/source/1_user/2_concepts/4_researchprojects/index.rst index b784224..f4b89a6 100644 --- a/docs/source/1_user/2_concepts/4_researchprojects/index.rst +++ b/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 diff --git a/docs/source/2_admin/2_administration/1_admin_panel.rst b/docs/source/2_admin/2_administration/1_admin_panel.rst new file mode 100644 index 0000000..5e67b83 --- /dev/null +++ b/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 diff --git a/docs/source/2_admin/2_administration/2_entities.rst b/docs/source/2_admin/2_administration/2_entities.rst new file mode 100644 index 0000000..e44b28c --- /dev/null +++ b/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% diff --git a/docs/source/2_admin/2_administration/admin_home.png b/docs/source/2_admin/2_administration/admin_home.png new file mode 100644 index 0000000..fd88187 --- /dev/null +++ b/docs/source/2_admin/2_administration/admin_home.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:489926d48ebe3e5cc917db3fc1527e34743f83774df34191e2a000d928759056 +size 69231 diff --git a/docs/source/2_admin/2_administration/admin_login.png b/docs/source/2_admin/2_administration/admin_login.png new file mode 100644 index 0000000..ece35e9 --- /dev/null +++ b/docs/source/2_admin/2_administration/admin_login.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1f1be89adc8338958bacff6ebe3c60170550bbe2978d2bf38376391e68bf84f0 +size 7842 diff --git a/docs/source/2_admin/2_administration/admin_where.png b/docs/source/2_admin/2_administration/admin_where.png new file mode 100644 index 0000000..6e8240f --- /dev/null +++ b/docs/source/2_admin/2_administration/admin_where.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cc776881546857ee1492b5db682772350d654d673bac544fde21e9b963b67c02 +size 26311 diff --git a/docs/source/1_user/2_concepts/1_instances/custom_description.png b/docs/source/2_admin/2_administration/custom_description.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/custom_description.png rename to docs/source/2_admin/2_administration/custom_description.png diff --git a/docs/source/1_user/2_concepts/1_instances/custom_title.png b/docs/source/2_admin/2_administration/custom_title.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/custom_title.png rename to docs/source/2_admin/2_administration/custom_title.png diff --git a/docs/source/2_admin/2_administration/index.rst b/docs/source/2_admin/2_administration/index.rst new file mode 100644 index 0000000..fdcb0d7 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/2_admin/2_administration/notebook_detail.png b/docs/source/2_admin/2_administration/notebook_detail.png new file mode 100644 index 0000000..1c2a526 --- /dev/null +++ b/docs/source/2_admin/2_administration/notebook_detail.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dd4ca44c61e7ac60541569ccbbb4ada8d577cf2c07a6bc9b8d208417d5c066e4 +size 63910 diff --git a/docs/source/2_admin/2_administration/notebook_list.png b/docs/source/2_admin/2_administration/notebook_list.png new file mode 100644 index 0000000..69cf025 --- /dev/null +++ b/docs/source/2_admin/2_administration/notebook_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1d82d22e5e270165875006f6b764f4f6eeeba49f9ee627919c48bd1b38f778f9 +size 34941 diff --git a/docs/source/2_admin/2_administration/researchgroup_detail.png b/docs/source/2_admin/2_administration/researchgroup_detail.png new file mode 100644 index 0000000..f10224c --- /dev/null +++ b/docs/source/2_admin/2_administration/researchgroup_detail.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:addbd193f8f103711a5c07f8782d58d7412d31eaf8efdbea35dc88635af340fb +size 46809 diff --git a/docs/source/2_admin/2_administration/researchgroup_list.png b/docs/source/2_admin/2_administration/researchgroup_list.png new file mode 100644 index 0000000..a95d031 --- /dev/null +++ b/docs/source/2_admin/2_administration/researchgroup_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:906cae69844692f8196aaa10e07768e52af5d0c1eb440b4e3deb5466fa6329b5 +size 26709 diff --git a/docs/source/2_admin/2_administration/researchproject_detail.png b/docs/source/2_admin/2_administration/researchproject_detail.png new file mode 100644 index 0000000..e7b234f --- /dev/null +++ b/docs/source/2_admin/2_administration/researchproject_detail.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:91b8edb0265610bc2e26c9fdd6aa638f517219a6fc276ece7ce597832f765eba +size 43098 diff --git a/docs/source/2_admin/2_administration/researchproject_list.png b/docs/source/2_admin/2_administration/researchproject_list.png new file mode 100644 index 0000000..dc84908 --- /dev/null +++ b/docs/source/2_admin/2_administration/researchproject_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e66fe36471b5e6278ef731d281be7ef03b403f6688effe5eb9db04516d9fe12 +size 23283 diff --git a/docs/source/1_user/2_concepts/1_instances/theme_amber.png b/docs/source/2_admin/2_administration/theme_amber.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/theme_amber.png rename to docs/source/2_admin/2_administration/theme_amber.png diff --git a/docs/source/1_user/2_concepts/1_instances/theme_hacker.png b/docs/source/2_admin/2_administration/theme_hacker.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/theme_hacker.png rename to docs/source/2_admin/2_administration/theme_hacker.png diff --git a/docs/source/1_user/2_concepts/1_instances/theme_paper.png b/docs/source/2_admin/2_administration/theme_paper.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/theme_paper.png rename to docs/source/2_admin/2_administration/theme_paper.png diff --git a/docs/source/1_user/2_concepts/1_instances/theme_royalblue.png b/docs/source/2_admin/2_administration/theme_royalblue.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/theme_royalblue.png rename to docs/source/2_admin/2_administration/theme_royalblue.png diff --git a/docs/source/1_user/2_concepts/1_instances/theme_sophon.png b/docs/source/2_admin/2_administration/theme_sophon.png similarity index 100% rename from docs/source/1_user/2_concepts/1_instances/theme_sophon.png rename to docs/source/2_admin/2_administration/theme_sophon.png diff --git a/docs/source/2_admin/2_administration/token_detail.png b/docs/source/2_admin/2_administration/token_detail.png new file mode 100644 index 0000000..42ec6a3 --- /dev/null +++ b/docs/source/2_admin/2_administration/token_detail.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6ea1c2d28d70d53cec0aded395d24eaaabad99f1dbe5426d086a1b1f1eb3b68e +size 11632 diff --git a/docs/source/2_admin/2_administration/token_list.png b/docs/source/2_admin/2_administration/token_list.png new file mode 100644 index 0000000..de348f2 --- /dev/null +++ b/docs/source/2_admin/2_administration/token_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:de32b22e21d78beb49924a804897bac93699fbbf9d5d81af83051fa0349cf4d5 +size 19474 diff --git a/docs/source/2_admin/2_administration/topright.png b/docs/source/2_admin/2_administration/topright.png new file mode 100644 index 0000000..ec306de --- /dev/null +++ b/docs/source/2_admin/2_administration/topright.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0db77ac5563a6a4d5f070504db8c1935d854331d8d72849e55775a3ddc94271f +size 2915 diff --git a/docs/source/2_admin/2_administration/user_detail.png b/docs/source/2_admin/2_administration/user_detail.png new file mode 100644 index 0000000..129f98a --- /dev/null +++ b/docs/source/2_admin/2_administration/user_detail.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:230cd2e5336de82b35c91144b86dfe17ab56436d5b24551422478bea05363399 +size 43813 diff --git a/docs/source/2_admin/2_administration/user_list.png b/docs/source/2_admin/2_administration/user_list.png new file mode 100644 index 0000000..32063a0 --- /dev/null +++ b/docs/source/2_admin/2_administration/user_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:eea11c7bdf759f791596c31b81119cf874d7be544f5f8b0a9c1ab15299c85c1e +size 28944 diff --git a/docs/source/2_admin/3_installation.rst b/docs/source/2_admin/3_installation.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/2_admin/3_update/index.rst b/docs/source/2_admin/3_update/index.rst new file mode 100644 index 0000000..d66311d --- /dev/null +++ b/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/ diff --git a/docs/source/2_admin/4_uninstallation/index.rst b/docs/source/2_admin/4_uninstallation/index.rst new file mode 100644 index 0000000..e96aed7 --- /dev/null +++ b/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 diff --git a/docs/source/2_admin/4_update.rst b/docs/source/2_admin/4_update.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/3_dev/2_differences/index.rst b/docs/source/3_dev/2_differences/index.rst new file mode 100644 index 0000000..1c887a4 --- /dev/null +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 1c65925..312394e 100644 --- a/docs/source/index.rst +++ b/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