steffo/sophon
steffo/sophon
1
Fork 0
mirror of https://github.com/Steffo99/sophon.git synced 2024-12-22 06:44:21 +00:00
Code Activity

🎓 Add installation chapter

Browse source
This commit is contained in:
Steffo 2021-11-26 06:56:14 +01:00
parent 05bd7ecb73
commit 16de3ed109
Signed by: steffo
GPG key ID: 6965406171929D01
17 changed files with 456 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
thesis/source/docs/1_sinossi/index.rst
View file

@ -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
*******

7
thesis/source/docs/2_introduzione/index.rst
View file

@ -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à;
#. nell'settimo capitolo, :ref:`Conclusione`, vengono tratte le conclusioni della tesi.
#. nel sesto capitolo, :ref:`Installazione`, vengono riportate le istruzioni di installazione del software;
#. nel settimo capitolo, :ref:`Utilizzo`, viene spiegato come utilizzare il software;
#. nell'ottavo capitolo, :ref:`Conclusione`, vengono tratte le conclusioni della tesi;

2
thesis/source/docs/3_presentazione/index.rst
View file

@ -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

2
thesis/source/docs/4_progetto/index.rst
View file

@ -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

4
thesis/source/docs/5_implementazione/index.rst
View file

@ -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

9
thesis/source/docs/6_applicazione/index.rst
View file

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

26
thesis/source/docs/6_installazione/1_requirements.rst Normal file
View file

@ -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/

32
thesis/source/docs/6_installazione/2_preparing_compose.rst Normal file
View file

@ -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]

19
thesis/source/docs/6_installazione/3_configuring_dns.rst Normal file
View file

@ -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/``).

199
thesis/source/docs/6_installazione/4_configuring_compose.rst Normal file
View file

@ -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

50
thesis/source/docs/6_installazione/5_pulling_images.rst Normal file
View file

@ -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/

27
thesis/source/docs/6_installazione/6_starting_sophon.rst Normal file
View file

@ -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/

64
thesis/source/docs/6_installazione/7_host_reverse_proxy.rst Normal file
View file

@ -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

6
thesis/source/docs/6_installazione/8_final_check.rst Normal file
View file

@ -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`.

20
thesis/source/docs/6_installazione/index.rst Normal file
View file

@ -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

0
thesis/source/docs/7_conclusione/index.rst → thesis/source/docs/8_conclusione/index.rst
View file

9
thesis/source/docs/8_appendice/index.rst → thesis/source/docs/9_bibliografia/index.rst
View file

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