Sviluppo

La seguente guida è pensata per aiutare gli sviluppatori che si occupano della manutenzione di Fiore o desiderano apportare modifiche.

Preparazione per lo sviluppo locale

Questa sezione illustra la configurazione iniziale per sviluppare Fiore.

Installazione di Java e Maven (su Mac)

brew update
brew install openjdk@17

Alla fine dell'ultimo prompt dei comandi, apparirà qualcosa di simile a quanto segue:

For the system Java wrappers to find this JDK, symlink it with
  sudo ln -sfn ...openjdk@17/libexec/openjdk.jdk .../JavaVirtualMachines/openjdk-17.jdk

openjdk@17 is keg-only, which means it was not symlinked into /usr/local,
because this is an alternate version of another formula.

If you need to have openjdk@17 first in your PATH, run:
  echo 'export PATH=".../openjdk@17/bin:$PATH"' >> .../.bash_profile

For compilers to find openjdk@17 you may need to set:
  export CPPFLAGS="-I.../openjdk@17/include"

Assicurati di eseguire i comandi sudo ln -sfn, echo 'export PATH=... e export CPPFLAGS= sopra.

Fiore è compilato con Maven. Maven utilizza una versione separata del JDK, che può essere visualizzata tramite mvn -v. Se non è JDK 17, dovremmo fare in modo che Maven punti al nostro JDK 17 usando JAVA_HOME:

$ /usr/libexec/java_home
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

$ export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

Se vediamo qualcosa di simile dopo aver digitato il comando con il flag di versione qui sotto, siamo a posto.

$ java --version
openjdk 17.0.10 2021-01-19
OpenJDK Runtime Environment (build 17.0.10+9)
VM Server OpenJDK a 64 bit (build 17.0.10+9, modalità mista)

Installazione di Docker Engine

Fiore dispone di test di integrazione basati su Docker; supporta anche l'esecuzione di template webservice in Docker. Docker può essere installato seguendo le sue istruzioni ufficiali

Ottenere il codice sorgente

git clone git@github.com:QubitPi/Fiore.git
cd Fiore

Sincronizzazione con gli stili di codice di Fiore con IntelliJ

Per il momento, abbiamo sintetizzato le convenzioni di stile più importanti relative al codice di Fiore come impostazioni di IntelliJ. Se IntelliJ viene utilizzato per l'IDE, è possibile importare queste impostazioni di stile del codice importando il file Fiore-Project-intellij-code-style.xml nella radice del repository. Le impostazioni per il progetto appariranno come un nuovo schema denominato "Fiore-Project" nella sezione Editor -> Stile Codice dell'IDE.

Abilitare anche "rimuovi importazioni inutilizzate" da Editor -> Generale -> Importazione Automatica -> Ottimizza Importazioni al Volo, che rimuoverà automaticamente le importazioni inutilizzate.

Esecuzione dei test

I seguenti comandi eseguono sia test unitari che di integrazione:

mancia

Se i test falliscono con 404 o endpoint-not-working, assicurarsi che la porta 8080 non sia occupata. Tutti i test di integrazione vengono eseguiti sul servizio web in esecuzione su quella porta.

mvn clean verify

Per i test IT, utilizziamo Testcontainers invece di jcabi-mysql perché quest'ultimo è difficile da configurare e debuggare e Testcontainers supporta più tipi di database, come mongo

Creazione di pacchetti

Un file WAR denominato fiore-1.0-SNAPSHOT.war verrà generato nella directory target per l'esecuzione in Jetty con il comando seguente:

mvn clean package

Esecuzione del servizio web in Docker

Assicurarsi che Docker sia installato (Installing Docker), quindi esegui i seguenti comandi:

Ottenere l'immagine

Possiamo ottenere l'immagine in uno dei 2 modi seguenti:

Docker Hub

Possiamo estrarre l'immagine dal mio Docker Hub:

docker pull jack20191124/fiore

GitHub

Possiamo anche compilare l'immagine da source:

git clone https://github.com/QubitPi/Fiore.git
cd Fiore
docker build -t jack20191124/fiore .

Si noti che jack20191124/fiore nell'ultimo comando è il nome dell'immagine; possiamo sostituire quel valore con qualsiasi altro valore desiderato.

Creazione di un container

Una volta creata l'immagine, possiamo creare un'istanza con

informazioni

Sostituire OPENAI_API_KEY qui sotto con la chiave effettiva che può essere ottenuta qui

export OPENAI_API_KEY=...
docker run --name=fiore -it \
-p 8080:8080 \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
jack20191124/fiore

• name=fiore: il container si chiama "fiore". Possiamo modificarlo di conseguenza.
• -p 8080:8080: 8080 è la porta su cui il servizio web sarà in ascolto. Con questo port forwarding, saremo in grado di accedere al servizio web dal browser web della macchina host all'indirizzo localhost:8080

Se visualizziamo il seguente output, significa che il contenitore è in esecuzione correttamente ed è pronto ad accettare richieste come http://localhost:8080/v1/healthcheck

...

2023-10-24 05:21:46.032:INFO :oejss.DefaultSessionIdManager:main: Session workerName=node0
2023-10-24 05:21:46.977:INFO :oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@2892dae4{ROOT.war,/,file:///tmp/jetty-0_0_0_0-8080-ROOT_war-_-any-13760845903749066689/webapp/,AVAILABLE}{/jetty-base/webapps/ROOT.war}
2023-10-24 05:21:46.994:INFO :oejs.AbstractConnector:main: Started ServerConnector@5c8dfc08{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2023-10-24 05:21:47.009:INFO :oejs.Server:main: Started Server@71d44a3{STARTING}[11.0.15,sto=5000] @2947ms

Esecuzione del servizio Web in Jetty autonomo

Scarica Jetty

Per JDK 17, la versione su cui gira Fiore, è stato testato che Jetty 11.0.15 funzionava. Pertanto, useremo la versione "11.0.15" come esempio:

Inserisci il file tar.gz in una posizione a tua scelta come percorso di installazione ed estrai il binario Jetty usando

tar -xzvf jetty-home-11.0.15.tar.gz

La directory estratta jetty-home-11.0.15 è la distribuzione Jetty. Chiamiamo questa directory $JETTY_HOME, che non deve essere modificata.

Configurazione di Jetty standalone

Il nostro file WAR verrà copiato in una directory da cui Jetty potrà essere prelevato ed eseguito. Chiamiamo questa directory $JETTY_BASE, che solitamente è diversa da $JETTY_HOME. $JETTY_BASE contiene anche le configurazioni di runtime del container. In breve, il contenitore Jetty autonomo verrà configurato con:

export JETTY_HOME=/path/to/jetty-home-11.0.15
mkdir -p /path/to/jetty-base
cd /path/to/jetty-base
java -jar $JETTY_HOME/start.jar --add-module=annotations,server,http,deploy,servlet,webapp,resources,jsp

dove /path/to/ è il percorso assoluto alla directory contenente la directory jetty-home-11.0.15

Con --add-module=annotations,server,http,deploy,servlet,webapp,resources,jsp configuriamo il contenitore Jetty.

Infine, trascina il file WAR nella directory /path/to/jetty-base/webapps e rinominalo in ROOT.war:

mv /path/to/war-file /path/to/jetty-base/webapps/ROOT.war

Servizio web in esecuzione

java -jar $JETTY_HOME/start.jar

Il servizio web verrà eseguito sulla porta 8080

Risoluzione dei problemi

IntelliJ

IntelliJ non riesce a LEGGERE il file di risorse

A volte, durante l'esecuzione di unit test in IntelliJ, si verificano errori che indicano che "un file di risorse" non è stato trovato. Sappiamo che il percorso è assolutamente corretto. In questo caso, si tratta semplicemente di un problema di IntelliJ che si risolve caricando esplicitamente tali risorse, indicando a IntelliJ dove si trovano:

Larghezza tabulazione

Utilizziamo 4 spazi come tabulazione. Questa impostazione può essere configurata in Code Style -> Java -> Tabs and Indents con le seguenti impostazioni:

• Dimensione tabulazione: 4
• Rientro: 4
• Rientro di continuazione: 8

Se le tabulazioni escono ancora con 2 spazi quando si preme TAB o Invio, non con 4 spazi, provare:

1. "Settings | Editor | Code Style" -- provare a disabilitare "Detect and use existing file indents for editing" nel caso in cui sia abilitato (è di default). NOTA: potrebbe essere necessario riaprire il file nell'editor.
2. Hai file .editorconfig da qualche parte nel percorso di quel file? Le impostazioni di .editorconfig ("Settings | Editor | Code Style") hanno la priorità (sovrascriveranno) sulle impostazioni dell'IDE.