🎓 Add installation chapter

thesis/source/docs/1_sinossi/index.rst

@@ -1,7 +1,7 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/1_sinossi/index.rst
 
 .. index::
-   pair: ! tesi; sinossi
+   pair: tesi; sinossi
 
 Sinossi
 *******

thesis/source/docs/2_introduzione/index.rst

@@ -1,7 +1,7 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/2_introduzione/index.rst
 
 .. index::
-   pair: ! tesi; introduzione
+   pair: tesi; introduzione
 
 **********************
 Introduzione alla tesi
@@ -46,5 +46,6 @@ La tesi è strutturata nel seguente modo:
 #. nel terzo capitolo, :ref:`Ricerca collaborativa`, viene presentata in dettaglio la situazione attuale della ricerca collaborativa;
 #. nel quarto capitolo, :ref:`Progettazione di Sophon`, viene descritta la progettazione avvenuta, entrando nei dettagli dei requisiti, della suddivisione in moduli e delle astrazioni create;
 #. nel quinto capitolo, :ref:`Realizzazione di Sophon`, vengono trattate le specifiche tecniche implementative del progetto;
-#. nel sesto capitolo, :ref:`Applicazione`, viene fatto un breve esempio di applicazione del progetto all'interno di un'Università;
+#. nel sesto capitolo, :ref:`Installazione`, vengono riportate le istruzioni di installazione del software;
-#. nell'settimo capitolo, :ref:`Conclusione`, vengono tratte le conclusioni della tesi.
+#. nel settimo capitolo, :ref:`Utilizzo`, viene spiegato come utilizzare il software;
+#. nell'ottavo capitolo, :ref:`Conclusione`, vengono tratte le conclusioni della tesi;

thesis/source/docs/3_presentazione/index.rst

@@ -1,7 +1,7 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/3_presentazione/index.rst
 
 .. index::
-   single: ! ricerca collaborativa
+   single: ricerca collaborativa
 
 *********************
 Ricerca collaborativa

thesis/source/docs/4_progetto/index.rst

@@ -1,7 +1,7 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/4_progetto/index.rst
 
 .. index::
-   pair: ! Sophon; progettazione
+   pair: Sophon; progettazione
 
 ***********************
 Progettazione di Sophon

thesis/source/docs/5_implementazione/index.rst

@@ -1,7 +1,7 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/5_implementazione/index.rst
 
 .. index::
-   pair: ! realizzazione; Sophon
+   pair: realizzazione; Sophon
 
 ***********************
 Realizzazione di Sophon
@@ -91,7 +91,7 @@ Inoltre, viene configurato il modulo `logging` per emettere testo colorato di pi
        "style": "{",
    }
 
-Una lista di tutte le variabili di ambiente di configurazione è riportata nella :ref:`Guida all'installazione` dell'appendice.
+Una lista di tutte le variabili di ambiente di configurazione è riportata nel capitolo :ref:`Installazione`.
 
 
 Miglioramenti all'autenticazione

thesis/source/docs/6_applicazione/index.rst

@@ -1,9 +0,0 @@
-:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_applicazione/index.rst
-
-************
-Applicazione
-************
-
-.. todo::
-
-   Scrivere questo capitolo.

thesis/source/docs/6_installazione/1_requirements.rst

@@ -0,0 +1,26 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/1_requirements.rst
+
+.. index::
+   pair: Sophon; requisiti di installazione
+
+Requisiti dell'host
+===================
+
+- Una connessione ad Internet (solo in fase di installazione)
+- `GNU Wget`_ (solo in fase di installazione)
+- Un nome di dominio
+- Un webserver (ad esempio, `Apache HTTPd`_)
+- Un certificato SSL valido *(opzionale, ma raccomandato)*
+- `Docker Engine`_
+- `Docker Compose`_
+
+.. hint::
+
+   È possibile ottenere gratuitamente un certificato SSL utilizzando `Letsencrypt`_!
+
+
+.. _GNU Wget: https://www.gnu.org/software/wget/
+.. _Apache HTTPd: https://httpd.apache.org/
+.. _Docker Engine: https://docs.docker.com/engine/
+.. _Docker Compose: https://docs.docker.com/compose/
+.. _Letsencrypt: https://letsencrypt.org/

thesis/source/docs/6_installazione/2_preparing_compose.rst

@@ -0,0 +1,32 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/2_preparing_compose.rst
+
+Preparazione di Docker Compose
+==============================
+
+Come ``root``, si crei una nuova cartella sul proprio sistema operativo in cui archiviare le risorse relative a Sophon:
+
+.. code-block:: console
+
+   root:~# mkdir -p /dock/sophon
+
+Successivamente, si scarichi il file ``docker-compose.yml`` all'interno della cartella dal repository di Sophon:
+
+.. code-block:: console
+
+   root:~# cd /dock/sophon
+
+   root:/dock/sophon# wget "https://raw.githubusercontent.com/Steffo99/sophon/main/docker-compose.yml"
+   --2021-11-02 18:03:05--  https://raw.githubusercontent.com/Steffo99/sophon/main/docker-compose.yml
+   SSL_INIT
+   Loaded CA certificate '/etc/ssl/certs/ca-certificates.crt'
+   Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 185.199.108.133,
+   185.199.109.133, 185.199.110.133, ...
+   Connecting to raw.githubusercontent.com (raw.githubusercontent.com) 185.199.108.133:443...
+   connected.
+   HTTP request sent, awaiting response... 200 OK
+   Length: 2957 (2.9K) [text/plain]
+   Saving to: ‘docker-compose.yml’
+
+   docker-compose.yml  100%[===================>]   2.89K  --.-KB/s    in 0s
+
+   2021-11-02 18:03:05 (48.0 MB/s) - ‘docker-compose.yml’ saved [2957/2957]

thesis/source/docs/6_installazione/3_configuring_dns.rst

@@ -0,0 +1,19 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/3_configuring_dns.rst
+
+Configurazione DNS
+==================
+
+Si scelga il dominio (o sottodominio) sul quale si vuole che Sophon sia accessibile e si aggiungano i seguenti record DNS, sostituendo il dominio ``ilmiosophon.it`` con il proprio nome di dominio, e gli indirizzi IPv4 e IPv6 del server al posto di `0.0.0.0` e `1234::1234`:
+
+.. code-block:: dns
+
+   *.ilmiosophon.it 1800 IN A    0.0.0.0
+   *.ilmiosophon.it 1800 IN AAAA 1234::1234
+   ilmiosophon.it   1800 IN A    0.0.0.0
+   ilmiosophon.it   1800 IN AAAA 1234::1234
+
+Sophon sarà quindi accessibile ai seguenti indirizzi:
+
+- l'interfaccia web al dominio base (``https://ilmiosophon.it/``);
+- l'API al dominio base prefisso con ``api.`` (``https://api.ilmiosophon.it/``);
+- i notebook al dominio base prefissi con lo slug del notebook (``https://ilmionotebook.ilmiosophon.it/``).

thesis/source/docs/6_installazione/4_configuring_compose.rst

@@ -0,0 +1,199 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/4_configuring_compose.rst
+
+Configurazione ``docker-compose.yml``
+=====================================
+
+Si configuri con l'editor di testo preferito il file ``docker-compose.yml`` con le impostazioni desiderate.
+
+.. code-block:: console
+
+   root:/dock/sophon# open docker-compose.yml
+
+In particolare, tutte le impostazioni precedute da ``# INSTALL`` vanno obbligatoriamente modificate.
+
+
+.. envvar:: DJANGO_SECRET_KEY
+
+   Specifica la chiave segreta da usare per i cookie di sessione.
+
+   .. code-block:: yaml
+
+      - DJANGO_SECRET_KEY=do-not-use-this-key-in-production-or-you-will-get-hacked
+
+   .. warning::
+
+      Cambiare la chiave segreta una volta installato Sophon invaliderà tutti gli accessi effettuati dagli utenti.
+
+   .. danger::
+
+      La chiave segreta è un dato estremamente riservato: chiunque sia a conoscenza della chiave segreta potrà effettuare l'accesso come qualsiasi utente!
+
+   .. seealso::
+
+      `SECRET_KEY <https://docs.djangoproject.com/en/3.2/ref/settings/#std:setting-SECRET_KEY>`_ nella documentazione di Django.
+
+
+.. envvar:: DJANGO_PROXY_BASE_DOMAIN
+
+   Specifica il dominio che dovrà essere usato come radice per il proxy, ovvero il dominio per il quale si è configurato il DNS in precedenza.
+
+   Se non è specificato, Sophon verrà eseguito in `modalità sviluppo <Modalità sviluppo>`.
+
+   .. code-block:: yaml
+
+      - DJANGO_PROXY_BASE_DOMAIN=ilmiosophon.it
+
+
+.. envvar:: DJANGO_PROXY_PROTOCOL
+
+   Specifica il protocollo che dovrà essere usato nei mapping del proxy.
+
+   Si consiglia di utilizzare ``https``, ma è un valore valido anche ``http``.
+
+   .. code-block:: yaml
+
+      - DJANGO_PROXY_PROTOCOL=https
+
+
+.. envvar:: DJANGO_ALLOWED_HOSTS
+
+   Specifica i domini da cui possono provenire le richieste alla pagina di amministrazione.
+
+   Per specificare più domini, è necessario separarli con dei pipe ``|`` .
+
+   Eccetto in configurazioni speciali, deve essere uguale al dominio prefisso da ``api.``.
+
+   .. code-block:: yaml
+
+      - DJANGO_ALLOWED_HOSTS=api.ilmiosophon.it
+
+   .. seealso::
+
+      `ALLOWED_HOSTS <https://docs.djangoproject.com/en/3.2/ref/settings/#allowed-hosts>`_ nella documentazione di Django.
+
+
+.. envvar:: DJANGO_ALLOWED_ORIGINS
+
+   Specifica i domini da cui possono provenire le richieste all'API.
+
+   Per specificare più domini, è necessario separarli con dei pipe ``|`` .
+
+   Eccetto in configurazioni speciali, deve contenere il proprio dominio prefisso dal protocollo, e in aggiunta il dominio speciale ``https://sophon.steffo.eu``, necessario per permettere l'accesso dall'interfaccia web "universale" di Sophon.
+
+   .. code-block:: yaml
+
+      - DJANGO_ALLOWED_ORIGINS=https://ilmiosophon.it|https://sophon.steffo.eu
+
+   .. seealso::
+
+      L'header `Access-Control-Allow-Origin <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin>`_ su MDN.
+
+
+.. envvar:: DJANGO_STATIC_URL
+
+   Specifica l'URL a cui saranno accessibili i file statici di Sophon.
+
+   Eccetto in configurazioni speciali, deve essere uguale alla seguente stringa, con le parole in maiuscolo sostituite rispettivamente dal protocollo e dal dominio selezionato: ``PROTOCOLLO://static.DOMINIO/django-static/``.
+
+   .. code-block:: yaml
+
+      - DJANGO_ALLOWED_ORIGINS=http://static.ilmiosophon.it/django-static/
+
+   .. warning::
+
+      Ci si assicuri che sia presente uno slash al termine della stringa, oppure il pannello di amministrazione non sarà visualizzato correttamente!
+
+   .. seealso::
+
+      `STATIC_URL <https://docs.djangoproject.com/en/3.2/ref/settings/#std:setting-STATIC_URL>`_ nella documentazione di Django
+
+
+.. envvar:: DJANGO_LANGUAGE_CODE
+
+   Specifica la lingua che deve usare Sophon nei messaggi di errore.
+
+   Usa il formato `language code`_ di Django.
+
+   .. code-block:: yaml
+
+      - DJANGO_LANGUAGE_CODE=en-us
+
+   .. seealso::
+
+      `LANGUAGE_CODE <https://docs.djangoproject.com/en/3.2/ref/settings/#language-code>`_ nella documentazione di Django
+
+   .. _language code: https://docs.djangoproject.com/en/3.2/topics/i18n/#term-language-code
+
+
+.. envvar:: DJANGO_TIME_ZONE
+
+   Specifica il fuso orario che deve usare Sophon nell'interfaccia di amministrazione.
+
+   Usa il formato `tzdata`_.
+
+   .. code-block:: yaml
+
+      - DJANGO_TIME_ZONE=Europe/Paris
+
+   .. hint::
+
+      Il fuso orario italiano è ``Europe/Rome``.
+
+   .. _tzdata: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+
+
+.. envvar:: DJANGO_SU_USERNAME
+
+   Specifica il nome del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti.
+
+   .. code-block:: yaml
+
+      - DJANGO_SU_USERNAME=root
+
+
+.. envvar:: DJANGO_SU_EMAIL
+
+   Specifica l'email del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti.
+
+   .. code-block:: yaml
+
+      - DJANGO_SU_USERNAME=django@example.org
+
+   .. note::
+
+      Attualmente, l'email non è utilizzata, ma è richiesta da Django per la creazione di un nuovo utente.
+
+
+.. envvar:: DJANGO_SU_PASSWORD
+
+   Specifica la password del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti.
+
+   .. code-block:: yaml
+
+      - DJANGO_SU_PASSWORD=square
+
+   .. warning::
+
+      La password è un dato estremamente riservato, in quanto chiunque ne venga a conoscenza potrà accedere a Sophon con pieni privilegi!
+
+
+.. envvar:: REACT_APP_DEFAULT_INSTANCE
+
+   Specifica il valore con cui precompilare il campo "selezione istanza" dell'interfaccia web di Sophon.
+
+   Eccetto in configurazioni speciali, deve essere uguale al dominio prefisso dal protocollo e da ``api.``.
+
+   .. code-block:: yaml
+
+      - REACT_APP_DEFAULT_INSTANCE=https://api.ilmiosophon.it
+
+
+.. envvar:: APACHE_PROXY_BASE_DOMAIN
+
+   Specifica il dominio che dovrà essere usato come radice per il proxy, ovvero il ``DOMINIO`` per il quale si è configurato il DNS in precedenza.
+
+   Deve essere uguale a :envvar:`DJANGO_PROXY_BASE_DOMAIN`
+
+   .. code-block:: yaml
+
+      - APACHE_PROXY_BASE_DOMAIN=ilmiosophon.it

thesis/source/docs/6_installazione/5_pulling_images.rst

@@ -0,0 +1,50 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/5_pulling_images.rst
+
+Download delle immagini Docker
+==============================
+
+Si utilizzi `Docker Compose`_ per scaricare le `immagini`_ Docker necessarie all'avvio di Sophon:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose pull
+   [+] Running 4/4
+    ⠿ proxy Pulled                                                                                 1.5s
+    ⠿ frontend Pulled                                                                              1.4s
+    ⠿ db Pulled                                                                                    1.9s
+    ⠿ backend Pulled                                                                               1.6s
+
+Inoltre, si scarichi manualmente l':ref:`immagine del Notebook` che può essere avviata da Sophon:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker image pull "ghcr.io/steffo99/sophon-jupyter:latest"
+   latest: Pulling from steffo99/sophon-jupyter
+   7b1a6ab2e44d: Already exists
+   578d7ac380c6: Pull complete
+   37f1e0b584f6: Pull complete
+   3c7282703390: Pull complete
+   b38aa558f711: Pull complete
+   1412103d568f: Pull complete
+   67419a9a821e: Pull complete
+   37e6cc015184: Pull complete
+   7d9316e2b57c: Pull complete
+   a7f024508c72: Pull complete
+   f3eae3c301a1: Pull complete
+   d3e2107efade: Pull complete
+   d94bc6f8f069: Pull complete
+   1e1dc3e818ad: Pull complete
+   c975ee664182: Pull complete
+   101cfcc0e15b: Pull complete
+   bf991a0d7538: Pull complete
+   4c044af18c7e: Pull complete
+   605d8c6e8eba: Pull complete
+   ed06f2ae4a88: Pull complete
+   ed8b1c841d10: Pull complete
+   468fe9a390ae: Pull complete
+   Digest: sha256:5d42e5e40e406130c688914d6a58aa94769eab03620b53e0fd409a7fb2682a01
+   Status: Downloaded newer image for ghcr.io/steffo99/sophon-jupyter:latest
+   ghcr.io/steffo99/sophon-jupyter:latest
+
+.. _Docker Compose: https://docs.docker.com/compose/
+.. _immagini: https://docs.docker.com/engine/reference/commandline/images/

thesis/source/docs/6_installazione/6_starting_sophon.rst

@@ -0,0 +1,27 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/6_starting_sophon.rst
+
+.. index::
+   pair: Sophon; avvio
+
+Avvio di Sophon
+===============
+
+Si utilizzi `Docker Compose`_ per eseguire le `immagini`_ di Sophon precedentemente scaricate:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose up -d
+   [+] Running 4/4
+    ⠿ Container sophon-db-1        Started                                                        11.3s
+    ⠿ Container sophon-frontend-1  Started                                                        11.7s
+    ⠿ Container sophon-backend-1   Started                                                        10.1s
+    ⠿ Container sophon-proxy-1     Started                                                        11.5s
+
+Si verifichi che i container si siano avviati correttamente con:
+
+.. code-block:: console
+
+   root:/dock/sophon# docker compose logs
+
+.. _Docker Compose: https://docs.docker.com/compose/
+.. _immagini: https://docs.docker.com/engine/reference/commandline/images/

thesis/source/docs/6_installazione/7_host_reverse_proxy.rst

@@ -0,0 +1,64 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/7_host_reverse_proxy.rst
+
+Configurazione del webserver dell'host
+======================================
+
+Si configuri il webserver dell'host per inoltrare tutto il traffico dalla porta 443 (o 80, se si è selezionato ``http`` in :ref:`\`\`DJANGO_PROXY_PROTOCOL\`\``) alla porta locale 30033.
+
+Sono allegate le istruzioni per il webserver `Apache HTTPd`_; possono essere però adattate se si vuole usare un webserver diverso, come `NGINX`_ o `caddy`_.
+
+.. _Apache HTTPd: https://httpd.apache.org/
+.. _nginx: https://www.nginx.com/
+.. _caddy: https://caddyserver.com/
+
+
+Con Apache HTTPd
+----------------
+
+Ci si assicuri che `mod_rewrite`_, `mod_proxy`_, `mod_proxy_http`_ e `mod_proxy_wstunnel`_ siano attivati.
+
+Si aggiungano i seguenti ``VirtualHost`` alla configurazione:
+
+.. code-block:: apacheconf
+
+   <VirtualHost *:80>
+       ServerName "ilmiosophon.it"
+       ServerAlias "*.ilmiosophon.it"
+
+       RewriteEngine On
+       RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
+   </VirtualHost>
+
+.. code-block:: apacheconf
+
+   <VirtualHost *:443>
+       ServerName "ilmiosophon.it"
+       ServerAlias "*.ilmiosophon.it"
+
+       SSLEngine on
+       SSLCertificateFile      "/SOSTITUISCIMI/CON/IL/PERCORSO/ALLA/FULL/CHAIN/SSL"
+       SSLCertificateKeyFile   "/SOSTITUISCIMI/CON/IL/PERCORSO/ALLA/CHIAVE/PRIVATA/SSL"
+
+       ProxyPreserveHost On
+       RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+       RewriteEngine On
+       RewriteCond %{HTTP:Upgrade} =websocket [NC]
+       RewriteRule /(.*)           ws://127.0.0.1:30033/$1 [P,L]
+       RewriteRule /(.*)           http://127.0.0.1:30033/$1 [P,L]
+
+       Protocols h2 http/1.1
+       Header always set Strict-Transport-Security "max-age=63072000"
+   </VirtualHost>
+
+Infine, si riavvii `Apache HTTPd`_:
+
+.. code-block:: console
+
+   root:/dock/sophon# systemctl restart httpd
+
+
+.. _mod_rewrite: https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html
+.. _mod_proxy: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html
+.. _mod_proxy_http: https://httpd.apache.org/docs/2.4/mod/mod_proxy_http.html
+.. _mod_proxy_wstunnel: https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html

thesis/source/docs/6_installazione/8_final_check.rst

@@ -0,0 +1,6 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/8_final_check.rst
+
+Verificare il funzionamento
+===========================
+
+Se tutto è stato configurato correttamente, l'interfaccia web Sophon dovrebbe essere raggiungibile al dominio selezionato (``https://ilmiosophon.it``), e dovrebbe essere possibile effettuare il login con le credenziali configurate del primo :ref:`superutente`.

thesis/source/docs/6_installazione/index.rst

@@ -0,0 +1,20 @@
+:github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/6_installazione/index.rst
+
+.. index::
+   pair: Sophon; installazione
+
+*************
+Installazione
+*************
+
+.. toctree::
+
+   1_requirements
+   2_preparing_compose
+   3_configuring_dns
+   4_configuring_compose
+   5_pulling_images
+   6_starting_sophon
+   7_host_reverse_proxy
+   8_final_check
+

thesis/source/docs/9_bibliografia/index.rst

@@ -1,11 +1,10 @@
 :github_url: https://github.com/Steffo99/sophon/blob/main/thesis/source/8_appendice/index.rst
 
-*********
+.. only:: html
-Appendice
-*********
 
-Bibliografia
+   ************
-============
+   Bibliografia
+   ************
 
 .. bibliography::
    :all: