Introduzione

Redmine è un applicativo per il project management.

La sua funzionalità principale consiste nella gestione di progetti. E' 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. E' possibile utilizzare diversi database mediante appositi driver, ma in questa fase di installazione ci limiteremo ad utilizzare i driver per MySQL.

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:

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

   • 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 un file vuoto di nome Gemfile.lock :

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

8. Assegnare l'utente www-data 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 di utilizzare root che può fare danni.

3. Assegnare i permessi all'utente creato per modificare 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 schema nel caso si utilizzi il server mysqlworkbench, poiché il database di ripristino e' 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.

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 e' importato (migrato ? come verifica la corretta importazione (migrazione) ?).

Importazione dei file

Adesso occorre copiare 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 in caso ce ne fosse bisogno. Adesso i file sono aggiornati. (come verificare l'avvenuto aggiornamento ?)

Configurazione posta

Dobbiamo adesso 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.aruba.it"
         port: 465
         authentication: :login
         domain: "dominio-mail.it"
         user_name: "redmine@dominio-mail.it"
         password: "tipiacerebbesaperelapasswordeh?"

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

6. Riavviare il server web Apache

   sudo service apache2 restart

In questo modo le mail dovrebbero essere abilitate. In caso di necessita' modificare i parametri dell'account di posta. (come verificare la congruità delle impostazioni ?)

Dato che utilizziamo Ubuntu 20.04 possono capitare incompatibilità'server smtp che utilizzano una vecchia versione di ssl, ad esempio i server Aruba. Questo e' dovuto ad una configurazione del server Ubuntu, che occorre quindi modificare.

Se si dovesse verificare occorre modificare le impostazioni ssl del server ubuntu. Aprire quindi il file /etc/ssl/openssl.cnf ed aggiungere all'inizio del file

openssl_conf = default_conf

Alla fine del file invece aggiungere

[ default_conf ]

ssl_conf = ssl_sect

[ ssl_sect ]

system_default = ssl_default_sect

[ ssl_default_sect ]

MinProtocol = TLSv1
CipherString = DEFAULT:@SECLEVEL=1

Salvare e riavviare.

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.

Dobbiamo creare la cartella dove i repository verranno caricati, quindi nella cartella dei dati di redmine, che di default dovrebbe essere /var/lib/redmine creare la cartella gitrepositories

sudo mkdir gitrepositories
sudo chown -r www-data:www-data gitrepositories

Dobbiamo adesso settare la chiave. Copiamo sul server la chiave di redmine associata ai repository git, e installiamola. Dobbiamo andare nella home di www-data, che e' /var/www, e a questo punto copiamo la chiave nella cartella .ssh:

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

Adesso possiamo clonare il repository

sudo -su www-data
cd /var/lib/redmine/gitrepositories
git clone --mirror git@192.168.1.2:cgf.git

Il repository adesso dovrebbe essere clonato. Adesso bisogna andare nella pagina del progetto, settare il repository git e dovrebbe funzionare. Se non funziona occorre analizzare i log; in caso di errore dovrebbe spuntare un errore 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_mode'

Aprire quindi il file /usr/share/redmine/lib/redmine/scm/adapters/abstract_adapter.rb e sostituire la riga 279 da

str.force_encoding(from)

a

str.dup.force_encoding(from)

Riavviare il server apache e verificare di nuovo.

Una volta funzionante, occorre creare un cronjob per poter automatizzare il fetch del repository per averlo sempre aggiornato. Occorre quindi modificare il crontab di www-data

sudo crontab -e -u www-data

*/5 * * * * cd /var/lib/redmine/gitrepositories/cgf && git remote update --prune

Deve essere creata una riga per ogni repository.

Risoluzione problemi

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

Problema export

Probabilmente e' necessario modificare il file /usr/share/redmine/lib/redmine/codeset_util.rb se si ha un errore di export. Modificare la riga 59 da

str.force_encoding('UTF-8')

a

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

Visualizzare log di Redmine

Nel caso si vogliano analizzare i log di redmine, si trovano nel seguente file:

/usr/share/redmine/instances/default/log/production.log

Alcune informazioni di log si trovano anche nei log del Webserver:

/var/log/apache2/error.log

Separatore CSV

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

Nel caso in cui ci sia la necessita' di modificare il separatore, occorre andare a configurare manualmente il file corrispettivo al locale utilizzato.

Andare prima di tutto nella pagina di amministrazione di Redmine Administration->Settings->Display per prendere nota della lingua utilizzata.

Occorre quindi modificare il file /usr/local/redmine/config/locales/XXX.yml, dove XXX e' il locale utilizzato dal programma. In questo file occorre modificare la voce general_csv_separator settando quindi il separatore che si vuole utilizzare.

Errore di upload CSV

Quando si importa un CSV in redmine puo' comparire un errore. Il log mostra qualcosa come:

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 `create'
lib/redmine/sudo_mode.rb:63:in `sudo_mode'

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

Occorre quindi creare la directory, nel caso non esistesse, e dare i permessi all'utente www-data:

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

Ricezione e-mail

E' possibile fare in modo di mandare email al redmine per poter per esempio aprire nuove segnalazioni o rispondere a quelli già aperti senza la necessità di entrare dal Browser, l'unico requisito è che la mail del mittente sia associata ad un utente già registrato.

La parte di acquisizione delle mail da parte del redmine, è gestita dal file /redmine/extra/mail_handler/rdm-mailhandler.rb che deve avere permessi di esecuzione.

sudo chmod +x /opt/redmine/extra/mail_handler/rdm-mailhandler.rb

Per poter attivare la funzione di ricezione è necessaria una Chiave API generata dal redmine stesso, attivando la voce.

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

• Attivare il flag su: Abilita WS per le email in arrivo
• Premere: Genera una chiave

Per funzionare correttametne è necessario che sul server sia presente un utente specifico dotato di mailbox interna, va quindi creato e i permessi cambiati.

sudo useradd -r -m -d /redmine/ -c 'Redmine user' -s /bin/bash redmine
sudo usermod -g www-data redmine
sudo chown -R redmine:www-data /redmine/

Configurare Passenger modifificando il file di configurazione /etc/apache2/mods-available/passenger.conf

PassengerRoot /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini
PassengerDefaultRuby /usr/bin/ruby

PassengerUserSwitching on
PassengerUser redmine
PassengerGroup www-data

Ora bisogna installare postfix e configurarlo.

sudo apt install postfix

Nel file di configurazione dei virtualhost va indicato l'indirizzo email del server e l'utente interno a cui deve essere mandato, per fare ciò aggiungere una rigua come segue al file /etc/virtual

indirizzo@dominio2.dominio1 redmine

Ora va configurato il file /etc/aliases aggiungendo una riga dove viene indicato cosa deve fare postfix quando arriva una mail, in questa riga va indicato la Chiave API generato 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>

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

Infine va avvisato il servizio di postfix che sono state fatte modifiche.

sudo newaliases

Pulire la cache

In alcuni casi (problemi o altro), può essere di aiuto pulire la cache.

cd /redmine
bundle exec rake tmp:cache:clear tmp:sessions:clear RAILS_ENV=production

Plugins

Il redmine dispondi di una buona scelta di plugin aggiuntivi gratuiti e a pagamento, li si possono trovare qui:

https://www.redmine.org/plugins

Per l'installazione degli stessi fare riferimento alla documentazione del plugin stesso.

Alcuni buoni 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