Introduzione

Redmine è un applicativo per il project management.

La sua funzionalità principale consiste nella gestione di progetti. è possibile gestire le persone coinvolte, creare requisiti, issue per l'avanzamento del progetto, definire delle milestone, associare documentazione e wiki al progetto e via dicendo. Permette anche la gestione delle risorse, mediante strumenti dedicati come il Gantt ed un calendario.

Redmine inoltre è estensibile nelle funzionalità dato che supporta un'architettura a plugin reperibili in rete.

Installazione

Redmine è un'applicazione web basata su Ruby on Rails. Occorre quindi installare il corrispettivo ambiente. Inoltre si appoggia a dei database. È possibile utilizzare diversi database mediante appositi driver, ma in questa fase di installazione ci limiteremo ad utilizzare i driver per MySQL o MySQLWorkbench.

I pacchetti necessari vanno installati secondo una precisa sequenza, seguendo i seguenti passaggi:

1. Installare i pacchetti apache2, libapache2-mod-passenger.

2. Installare i pacchetti mysql-server, mysql-client, se si desidera usare il database in locale.

3. Installare i pacchetti medmine redmine-mysql, git libfftw3-dev, libfftw3-bin, fonts-noto, fonts-freefont-ttf, fonts-texgyre, ghostscript-x cups-common, libjs-jquery-ui-docs, liblcms2-utils, libmagickcore-6.q16-6-extra, poppler-utils, ruby-fcgi, darcs.

4. All'apparire della domanda Configure database for redmine/instances/default with dbconfig-common selezionare Yes.

5. Impostare una password.

6. Installare i pacchetti ruby-dev, libssl-dev, libmagickwand-dev, libmysqlclient-dev, build-essential.

7. Aggiornare l'ambiente di Ruby, utilizzando il comando gem:

   sudo gem update
   sudo gem install bundler

Al termine, in caso d'esito positivo, procedere a configurare il server web Apache.
In caso di esito negativo occorre analizzare i log di Apache, in modo tale da trovare l'errore ed eventualmente risolverlo.

Configurare Apache

1. Aprire con i privilegi di amministrazione e con un editor di testo il file /etc/apache2/mods-available/passenger.conf.

2. Inserire come prima opzione della sezione (quale sezione ?) la seguente riga:

   PassengerDefaultUser www-data

3. Creare un collegamento simbolico nello spazio dei servizi web:

   sudo ln -s /usr/share/redmine/public /var/www/html/redmine

4. Aprire con i privilegi di amministrazione e con un editor di testo il file /etc/apache2/sites-available/000-default.conf.

5. Copiare alla fine del file la seguente sezione necessaria per usare e configurare Redmine:

   <cartella /var/www/html/redmine>
       RailsBaseURI /redmine
       PassengerResolveSymlinksInDocumentRoot on
   </cartella>

   • Sostituire /redmine con / se di desidera che l'applicazione Redmine compaia nella document root, ovvero se si vuole che compaia quando nella barra degli indirizzi del browser si digita l'indirizzo del server; altrimenti in mancanza della sostituzione l'indirizzo sarà serveraddress/redmine.

6. Impostare sempre nello stesso file il parametro DocumentRoot affinché punti all'applicativo Redmine:

   ...
   DocumentRoot /var/www/html/redmine
   ...

7. Creare e coi privilegi di amministrazione un file vuoto di nome Gemfile.lock :

   sudo touch /usr/share/redmine/Gemfile.lock

8. Assegnare l'utente www-date al file appena creato, in maniera tale da poterlo fare gestire a Redmine

   sudo chown www-data:www-data /usr/share/redmine/Gemfile.lock

9. Riavviare il server web Apache

   sudo service apache2 restart

Se tutti i passaggi sono stati eseguiti correttamente, puntando all'indirizzo IP si dovrebbe vedere la pagina principale di Redmine.

Migrazione

Può capitare che occorra importare dei dati da una versione precedente di Redmine. In questo caso occorre seguire i seguenti passaggi del paragrafo.

Nel caso in cui invece l'installazione sia nuova e non occorra importare nulla, potete saltare questi passaggi.

Per importare i dati di Redmine occorre importare due (o tre ?) tipologie di dati:

• Database
• Files
• Plugins

Importazione dei database

1. Creare il database tramite il server mysql o mysqlworkbench.

2. Creare un utente dedicato per questo database, per evitare d'operare come superutente che può fare danni.

3. Assegnare i permessi all'utente creato per gestire il database.

   • Quando si crea lo schema impostare il charset in utf8 e la collation in utf8_bin (in un file, una variabile ?).

4. Importare il database esistente in quello creato:

   (quale comando o procedura ?)

5. Creare il backup del database preesistente di Redmine:

   (con quale procedura o comando ?  E non sarebbe meglio __prima__ backuppare e __poi__ importare in quello nuovo col passaggio precedente ?)

   Quando s'esegue il backup rimembrare d'abilitare l'opzione create scheme nel caso si utilizzi il server mysqlworkbench, poiché il database di ripristino è vuoto e quindi si devono creare le tabelle.

Una volta esportato si può importare. (cioè ?)

A questo punto dovremmo avere il nuovo database che può essere modificato a piacimento.

Adesso occorre impostare Redmine a puntare al database creato per aggiornarlo.

1. Aprire con i privilegi di amministrazione e con un editor di testo il file /usr/share/redmine/config/database.yml.

2. Modificare i parametri di connessione con quelli del database che si vuole utilizzare. (esempio di parametri ?).

3. Riavviare il servizio per poter caricare il nuovo database:

   sudo service apache2 (il nome è corretto ?) restart

4. Spostarsi nella cartella /usr/share/redmine per importare (migrare ?) il database.

5. Eseguire l'importazione digitando il seguente comando:

   sudo bundle exec rake db:migrate RAILS_ENV=production

Il database adesso è importato (migrato ? come verifica la corretta importazione (migrazione) ?).

Importazione dei file

Adesso occorre importare i file dal database preesistente a quello creato.

La locazione predefinita ove sono salvati i file è /var/lib/redmine/default/files/.

1. Copiare i file dal database preesistente a quello creato, coi seguenti comandi:

   sudo scp -r rmadmin@192.168.100.225:/data/redmine/redmine/files/* /var/lib/redmine/default/files
   sudo chown -R www-data:www-data /var/lib/redmine/default/files

Sistemare il percorso del database preesistente in quello creato nel caso fosse necessario. Adesso i file sono aggiornati. (come verificare l'avvenuto aggiornamento ?)

Configurazione posta

Adesso occorre configurare Redmine per inviare la posta.

1. Spostarsi nella cartella /usr/share/redmine/config.

2. Copiare coi privilegi di amministrazione il file configuration.yml.example in configuration.yml.

3. Aprire con i privilegi di amministrazione e con un editor di testo il file configuration.yml.

4. Cercare la sezione email_delivery e inserire i dati dell'account di posta che si vuole utilizzare, ad esempio nel caso di un account SMTP:

     email_delivery:
       delivery_method: :smtp
       smtp_settings:
         ssl: true
         enable_starttls_auto: true
         address: "smtps.ubuntu.it"
         port: 465
         authentication: :login
         domain: "dominio-mail.it"
         user_name: "ubuntu@dominio-mail.it"
         password: "12345678?"

   Sostituire i parametri d'esempio con quelli reali del proprio account di posta elettronica.

5. Copiare coi privilegi di amministrazione il file configuration.yml nella cartella /etc/redmine/default.

6. Riavviare il server web Apache

   sudo service apache2 restart

In questo modo la posta elettronica è abilitata.

In caso di problemi consultare questa sezione. (come verificare la congruità delle impostazioni ?)

Git

Adesso occorre configurare Redmine per integrarsi con Git.

Questo serve se un progetto viene sviluppato attraverso Git e si vuole sincronizzare il progetto con il suo repository.

1. Creare con i privilegi di amministrazione la cartella /var/lib/redmine/gitrepositories.

2. Assegnare i permessi alla cartella creata:

   sudo chown -r www-data:www-data /var/lib/redmine/gitrepositories

Adesso occorre impostare la chiave (di che tipo ? scaricata da dove e quando ?), copiando sul server la chiave di Redmine associata ai repository Git, e installandola.

1. Spostarsi nella cartella /var/www.

2. Creare coi privilegi di amministrazione la cartella .ssh.

3. Copiare coi privilegi di amministrazione la chiave redminesshkey nella cartella .ssh.

4. Assegnare i permessi alla cartelle genitore e figlie create:

   sudo chown -R www-data:www-data .ssh
   sudo chmod 0700 .ssh
   sudo chmod 0600 .ssh/id_rsa

Clonazione del repository

sudo -su www-data (per quel che ne so la sinossi dovrebbe essere [sudo -su <nomeutente> <comando>], puoi chiarire ?)

1. Spostarsi nella cartella /var/lib/redmine/gitrepositories.

2. Scaricare il repository:

   git clone --mirror git@192.168.1.2:cgf.git

Il repository adesso dovrebbe essere clonato. Adesso bisogna andare nella pagina del progetto (quale pagina ?) e impostare il repository Git (come ?).

In caso di problemi consultare questa sezione. (come verificare la congruità delle impostazioni ?)

Risoluzione problemi

Vediamo adesso come risolvere alcuni problemi che possono capitare durante l'utilizzo di Redmine.

Impostazioni posta elettronica in Ubuntu 20.04

Col rilascio Focal 20.04 di Ubuntu possono capitare incompatibilità col server Smtp che usano una vecchia versione di ssl, ad esempio i server Aruba.

Questo è dovuto alla configurazione del server Ubuntu, che occorre modificare.

Se si dovesse verificare occorre modificare le impostazioni ssl del server Ubuntu.

1. Aprire con i privilegi di amministrazione e con un editor di testo /etc/ssl/openssl.cnf e aggiungere all'inizio del file la stringa:

   openssl_conf = default_conf

2. Nello stesso file alla fine del file aggiungere la sezione:

   [ default_conf ]
   
   ssl_conf = ssl_sect
   
   [ ssl_sect ]
   
   system_default = ssl_default_sect
   
   [ ssl_default_sect ]
   
   MinProtocol = TLSv1
   CipherString = DEFAULT:@SECLEVEL=1

3. Riavviare il server web Apache

   sudo service apache2 restart

   (procedura corretta ?)

Problema clonazione repository

In presenza di errori dovrebbe essere mostrata una schermata del tipo:

Started GET "/projects/cgf_login/repository" for 172.16.10.108 at 2020-06-24 14:20:36 +0000
Processing by RepositoriesController#show as HTML
  Parameters: {"id"=>"cgf_login"}
  Current user: NomeUtente(id=4)
Completed 500 Internal Server Error in 35ms (ActiveRecord: 6.6ms)

FrozenError (can't modify frozen String: ""):

lib/redmine/scm/adapters/abstract_adapter.rb:279:in `force_encoding'
lib/redmine/scm/adapters/abstract_adapter.rb:279:in `scm_iconv'
lib/redmine/scm/adapters/git_adapter.rb:136:in `entries'
app/models/repository/git.rb:98:in `scm_entries'
app/models/repository.rb:204:in `entries'
app/controllers/repositories_controller.rb:86:in `show'
lib/redmine/sudo_mode.rb:63:in `sudo_modè

Nella schermata mostrata appaiono degli errori alla linea 279 del file lib/redmine/scm/adapters/abstract_adapter.rb:279, (le altre linee non vanno corrette ?), seguire i seguenti passaggi per correggere gli errori.

1. Aprire con i privilegi di amministrazione e con un editor di testo il file /usr/share/redmine/lib/redmine/scm/adapters/abstract_adapter.rb.

2. Sostituire alla linea 279 la stringa:

   • str.force_encoding(from)

   • colla stringa:

     str.dup.force_encoding(from)

3. Riavviare il server web Apache

   sudo service apache2 restart

   (corretta la procedura ?)

Una volta funzionante, occorre creare un cronjob (come ?) per poter automatizzare il fetch (come ?) del repository per averlo sempre aggiornato.

1. Modificare il crontab di www-date:

   sudo crontab -e -u www-data
   
   */5 * * * * cd /var/lib/redmine/gitrepositories/cgf && git remote update --prune

In presenza di malfunzionamenti analizzare pure i log.

Problema export

Modificare il file /usr/share/redmine/lib/redmine/codeset_util.rb in presenza d'un errore di export.

1. Aprire con i privilegi di amministrazione e con un editor di testo il file /usr/share/redmine/lib/redmine/codeset_util.rb.

2. Sostituire alla riga 59 la stringa:

   • str.force_encoding('UTF-8')

     colla stringa:

     str = str.dup.force_encoding('UTF-8')

3. Riavviare il server web Apache

   sudo service apache2 restart

   (corretta la procedura ?)

Visualizzare log di Redmine

1. Per analizzare i log di Redmine leggere il file /usr/share/redmine/instances/default/log/production.log.

2. Per ulteriori informazioni log leggere il file del webserver /var/log/apache2/error.log.

Separatore CSV

Quando si esporta un elenco di issue in formato CSV, non è possibile personalizzare il tipo di separatore, perlomeno non dall'interfaccia grafica, in quanto è collegato al locale usato da Redmine.

Nel caso in cui ci sia la necessità di modificare il separatore (sarebbe il separatore ?), occorre configurare manualmente il file corrispondente al locale utilizzato.

Andare prima di tutto nella pagina di amministrazione di Redmine e selezionare il menù Administration → Settings → Display per prendere nota della lingua utilizzata. (questo passaggio non l'ho capito).

1. Aprire con i privilegi di amministrazione e con un editor di testo il file /usr/local/redmine/config/locales/XXX.yml, dove XXX è la sigla del locale utilizzato dal programma.

2. Modificare la voce general_csv_separator impostando il separatore (sarebbe il separatore ?) da usare.

Errore di upload CSV

Quando si importa un CSV in Redmine può comparire un errore.

Il file log di Redmine mostrerà una schermata del tipo:

Processing by ImportsController#new as HTML
  Current user: DanieleLupo (id=4)
  Rendering imports/new.html.erb within layouts/base
  Rendered issues/_sidebar.html.erb (4.2ms)
  Rendered imports/new.html.erb within layouts/base (6.0ms)
Completed 200 OK in 82ms (Views: 65.0ms | ActiveRecord: 8.2ms)
Started POST "/imports" for 172.16.10.198 at 2020-07-24 14:08:57 +0000
Processing by ImportsController#create as HTML
  Parameters: {"utf8"=>"✓", "authenticity_token"=>"b52D75w/j8HmKiE1FzGlPSNq5yP3s3emDro/lXxOL7LzhTl1cYm5LtibrhjJDkPD9xezxbqoJJ2JRVskRHy8Rw==", "file"=>#<ActionDispatch::Http::UploadedFile:0x00007f7ad91e0b80 @tempfile=#<Tempfile:/tmp/RackMultipart20200724-1091606-54pfjd.csv>, @original_filename="issues.csv", @content_type="application/vnd.ms-excel", @headers="Content-Disposition: form-data; name=\"file\"; filename=\"issues.csv\"\r\nContent-Type: application/vnd.ms-excel\r\n">}
  Current user: NomeUtente(id=4)
Completed 500 Internal Server Error in 12ms (ActiveRecord: 3.7ms)

Errno::EACCES (Permission denied @ dir_s_mkdir - /usr/share/redmine/tmp/imports):

lib/redmine/utils.rb:49:in `save_upload'
app/models/import.rb:47:in `file='
app/controllers/imports_controller.rb:35:in `creatè
lib/redmine/sudo_mode.rb:63:in `sudo_modè

Possiamo leggere che non ci sono i permessi in /usr/share/redmine/tmp.

1. Creare coi privilegi di amministrazione la cartella, nel caso non esista, /usr/share/redmine/tmp.

2. Assegnare i permessi alla cartella creata:

   sudo chown -R www-data:www-data /usr/share/redmine/tmp

Ricezione e-mail

È possibile mandare mail al Redmine, ad esempio per aprire nuove segnalazioni o rispondere a quelle già aperte, senza la necessità d'avviare il browser, l'unico prerequisito è che la mail del mittente sia associata ad un utente già registrato sul Redmine stesso.

Il file che si occupa di processare le mail e da includerle nel Redmine è il file /redmine/extra/mail_handler/rdm-mailhandler.rb, che dev'essere reso eseguibile.

1. Assegnare i permessi d'esecuzione al file /redmine/extra/mail_handler/rdm-mailhandler.rb.

Per poter attivare la funzione di ricezione è necessaria una Chiave API generata dal redmine stesso:

• Con il browser accedere al Redmine

• Andare in: Amministrazione > Impostazioni > Email in arrivo...

• Attivare il flag su: Abilita WS per le email in arrivo
• Premere: Genera una chiave
• Copiarsi la chiave generata che servirà più avanti

Per funzionare correttamente è necessario che sul server sia presente un utente specifico dotato di mailbox interna.

1. Dalla riga di comando dell'OS creare l'utente della mailbox con il seguente comando:

   sudo useradd -r -m -d /redmine/ -c 'Redmine user' -s /bin/bash redmine

2. Aggiungere l'utente appena creato al gruppo del webserver:

   sudo usermod -g www-data redmine

3. Impostare i permessi alla cartella contenente l'installazione del Redmine:

   sudo chown -R redmine:www-data /redmine/

4. Aprire con i privilegi di amministrazione e con un editor di testo il file /etc/apache2/mods-available/passenger.conf.

5. Individuare i paramteri di passanger e modificarli come segue (se non esistono li si devono aggiungere):

   <IfModule mod_passenger.c>
     PassengerRoot /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini
     PassengerDefaultRuby /usr/bin/ruby
   
     PassengerUserSwitching on
     PassengerUser redmine
     PassengerGroup www-data
   </IfModule>

6. Installare il pacchetto postfix

7. Aprire con i privilegi di amministrazione e con un editor di testo il file /etc/virtual per impostare il server e l'utente ricevente.

8. Copiare alla fine del file la seguente stringa (modificano l'indirizzo email inizale con quello assegniato al server):

   indirizzo@dominio2.dominio1 redmine

9. Aprire con i privilegi di amministrazione e con un editor di testo il file /etc/aliases.

10. Per impostare cosa deve fare postfix quando arriva una mail, cercare questa linea e riportare la Chiave API generata in precedenza:

    redmine: "|/usr/bin/ruby /redmine/extra/mail_handler/rdm-mailhandler.rb --url http://indirizzo.sito-redmine.it --key <mettere_chiave_api> --no-check-certificate --allow-override <mettere_categorie_da_gestire>

    Le categorie sono quelle configurate nel tracker delle segnalazioni del redmine (es: --allow-override project,tracker,priority,custom_field).

11. Aggiornare Postfix alle modifiche fatte:

    sudo newaliases

Esempio del corpo di una mail da mandare al redmine per aprire una nuova segnalazione con le categorie di esempio:

project: METTERE_IL_NOME_DEL_PROGETTO
tracker: Unclassified
status: new
priority: normal
external ticket nr: 12345

Pulire la cache

In caso di problemi o altro, può essere di aiuto pulire la cache.

1. Spostarsi nella cartella /redmine. (percorso corretto ?).

2. Eseguire la pulizia col comando:

   bundle exec rake tmp:cache:clear tmp:sessions:clear RAILS_ENV=production

Plugins

Il Redmine dispone di molti plugin aggiuntivi gratuiti e a pagamento, possono essere trovati qui:

https://www.redmine.org/plugins

Per l'installazione e l'uso dei medesimi fare riferimento alla documentazione allegata.

Alcuni utili plugin sono:

• Mega Calendar plugin: Mostra un bel calendario con tutte le issue inserite nel sistema con la possibilità di applicare filtri di visualizzazione
• Redmine Base Deface plugin: Pre-requisito del plugin che comunica la maintenance del sistema
• Redmine Maintenance Mode: Mostra un avviso evidente che segnala la schedulazione della manutenzione e la attiva/disattiva quando prestabilito
• Image Clipboard Paste: Permette di allegare un immagine quando viene premuto CTRL+V

  • https://github.com/thorin/redmine_image_clipboard_paste

• Redmine Mentions: Permette di inviare mail agli utenti menzionati con @username nelle segnalazioni

Ulteriori risorse

• Sito ufficiale del progetto (in inglese)

CategoryServer