|
| 1 | +README |
| 2 | +###### |
| 3 | + |
| 4 | +ABOUT |
| 5 | +##### |
| 6 | + |
| 7 | +Lavagna is a small and easy to use agile issue/project tracking software. |
| 8 | + |
| 9 | +It require : java 7 or better, mysql (5.1 or better) or postgresql. It can be deployed in a java servlet container. |
| 10 | + |
| 11 | + |
| 12 | +INSTALL |
| 13 | +####### |
| 14 | + |
| 15 | +Lavagna support mysql (at least 5.1) / pgsql for production use and hsqldb for testing purpose. |
| 16 | + |
| 17 | +It's distributed in 2 forms: |
| 18 | + |
| 19 | + - simple war for deploying in your preferred web container |
| 20 | + - self contained war with embedded jetty web server |
| 21 | + |
| 22 | +For trial purpose |
| 23 | +----------------- |
| 24 | + |
| 25 | +If you want to test it locally, you can download the self contained war and run (java 7 or greater required): |
| 26 | + |
| 27 | +>java -Ddatasource.driver=org.hsqldb.jdbcDriver -Ddatasource.dialect=HSQLDB -Ddatasource.url=jdbc:hsqldb:mem:lavagna -Ddatasource.username=sa -Ddatasource.password= -Dspring.profile.active=dev -jar lavagna-jetty-console.war --headless |
| 28 | + |
| 29 | +Go to http://localhost:8080 and login with "user" (password "user"). |
| 30 | + |
| 31 | +Setup |
| 32 | +----- |
| 33 | + |
| 34 | +Lavagna require the following property to be set on the jvm: |
| 35 | + |
| 36 | + - datasource.driver=org.hsqldb.jdbcDriver | com.mysql.jdbc.Driver | org.postgresql.Driver |
| 37 | + - datasource.dialect=HSQLDB | MYSQL | PGSQL |
| 38 | + - datasource.url= for example: jdbc:hsqldb:mem:lavagna | jdbc:mysql://localhost:3306/lavagna | jdbc:postgresql://localhost:5432/lavagna |
| 39 | + - datasource.username=<username> |
| 40 | + - datasource.password=<pwd> |
| 41 | + - spring.profile.active= dev | prod |
| 42 | + |
| 43 | +The db user must be able to create tables and others db objects. |
| 44 | + |
| 45 | +Once the application has been started/deployed, go to |
| 46 | + |
| 47 | +http(s)://<your deploy>(:port)/setup/ |
| 48 | + |
| 49 | +There you can: |
| 50 | + |
| 51 | +1: configure the application |
| 52 | +2: import a lavagna export |
| 53 | + |
| 54 | +Configuration steps |
| 55 | +------------------- |
| 56 | + |
| 57 | +step 1: define the base url |
| 58 | +step 2: define the initial login configuration (demo, ldap, oauth, mozilla persona) |
| 59 | +step 3: define the admin user |
| 60 | +step 4: confirm |
| 61 | + |
| 62 | + |
| 63 | +DEVELOP |
| 64 | +####### |
| 65 | + |
| 66 | +IDE Configuration |
| 67 | +================= |
| 68 | + |
| 69 | +This project use project lombok annotations, you will need to install the support in your IDE. |
| 70 | + |
| 71 | +Use UTF-8 encoding. |
| 72 | + |
| 73 | + |
| 74 | +Execute |
| 75 | +======= |
| 76 | + |
| 77 | +launch web server: |
| 78 | + |
| 79 | +# mvn jetty:run |
| 80 | + |
| 81 | +for launching web server + db manager (hsqldb only) |
| 82 | + |
| 83 | +# mvn jetty:run -DstartDBManager |
| 84 | + |
| 85 | +for launching web server with the mysql database (use mysql profile): |
| 86 | + |
| 87 | +# mvn jetty:run -Pdev-mysql |
| 88 | + |
| 89 | +# mvn jetty:run -Pdev-pgsql |
| 90 | + |
| 91 | +- go to http://localhost:8080 |
| 92 | + if you have a 403 error, you must configure the application, |
| 93 | + go to http://localhost:8080/setup, select demo + insert user "user". |
| 94 | + |
| 95 | +- enter |
| 96 | + username: user |
| 97 | + password: user |
| 98 | + |
| 99 | +For debugging |
| 100 | + |
| 101 | +# mvndebug jetty:run |
| 102 | + |
| 103 | +For running the test cases |
| 104 | + |
| 105 | +# mvn test |
| 106 | + |
| 107 | +For running the test cases with mysql or pgsql |
| 108 | + |
| 109 | +# mvn test -Ddatasource.dialect=MYSQL |
| 110 | + |
| 111 | +# mvn test -Ddatasource.dialect=PGSQL |
| 112 | + |
| 113 | + |
| 114 | +For running with jetty-runner: |
| 115 | + |
| 116 | +# mvn clean install |
| 117 | +# java -Ddatasource.dialect=HSQLDB -Ddatasource.driver=org.hsqldb.jdbcDriver -Ddatasource.url=jdbc:hsqldb:mem:lavagna -Ddatasource.username=sa -Ddatasource.password= -Dspring.profiles.active=dev -jar target/dependency/jetty-runner.jar --port 8080 target/*.war |
| 118 | + |
| 119 | +VAGRANT |
| 120 | +============= |
| 121 | + |
| 122 | +Make sure that you have installed Vagrant and VirtualBox. |
| 123 | + |
| 124 | +Initialization |
| 125 | +-------------- |
| 126 | + |
| 127 | +Fetch the submodules before: |
| 128 | + |
| 129 | +# git submodule update --init |
| 130 | + |
| 131 | +If you are under windows you need to ensure that the pgsql submodule is not in a broken state, |
| 132 | +ensure that the file puppet\modules\postgresql\files\validate_postgresql_connection.sh is using the |
| 133 | +unix end of line (run dos2unix). |
| 134 | + |
| 135 | +To run the tests with Vagrant boot the VMs with |
| 136 | + |
| 137 | +# vagrant up [optionally use pgsql / mysql to boot only one VM] |
| 138 | + |
| 139 | +Once that the VM is up and running run the tests: |
| 140 | + |
| 141 | +# mvn test -Ddatasource.dialect=PGSQL / MYSQL |
| 142 | + |
| 143 | + |
| 144 | +Connecting manually: |
| 145 | +-------------------- |
| 146 | + |
| 147 | +PGSQL: localhost:5432/lavagna as postgres / password |
| 148 | + |
| 149 | +MySQL: localhost:3306/lavagna as root |
| 150 | + |
| 151 | +Oracle: localhost:1521/XE as system / manager |
| 152 | + |
| 153 | +Notes about databases: |
| 154 | +---------------------- |
| 155 | + |
| 156 | +The application use UTF-8 at every stage, on mysql you will need to create a database with the collation set to utf8_bin : |
| 157 | + |
| 158 | +CREATE DATABASE lavagna CHARACTER SET utf8 COLLATE utf8_bin; |
| 159 | + |
| 160 | + |
| 161 | + |
| 162 | + |
| 163 | +Oracle support: |
| 164 | +--------------- |
| 165 | + |
| 166 | +First add the vbguest plugin: |
| 167 | + |
| 168 | +# vagrant plugin install vagrant-vbguest |
| 169 | + |
| 170 | +Note: if you have an error while installing the vagrant-vbguest plugin, see https://github.com/WinRb/vagrant-windows/issues/193 , install before the vagrant-login plugin with |
| 171 | + |
| 172 | +# vagrant plugin install vagrant-login |
| 173 | + |
| 174 | + |
| 175 | +Download Oracle Database 11g Express Edition for Linux x64 from ( http://www.oracle.com/technetwork/database/database-technologies/express-edition/downloads/index.html ) |
| 176 | + |
| 177 | +Place the file oracle-xe-11.2.0-1.0.x86_64.rpm.zip in the directory puppet/modules/oracle/files of this project. |
| 178 | + |
| 179 | +Thanks to Hilverd Reker for his GitHub repo: https://github.com/hilverd/vagrant-ubuntu-oracle-xe . |
| 180 | + |
| 181 | + |
| 182 | + |
| 183 | +CODE COVERAGE |
| 184 | +============= |
| 185 | + |
| 186 | +Jacoco plugin is used. |
| 187 | + |
| 188 | +# mvn install site |
| 189 | + |
| 190 | +-> open target/site/jacoco/index.html with your browser |
| 191 | + |
| 192 | +DATABASE MIGRATION |
| 193 | +================== |
| 194 | + |
| 195 | +Can be disabled using the following system property: datasource.disable.migration=true |
| 196 | + |
| 197 | + |
| 198 | +CHECK FOR UPDATED DEPENDENCIES |
| 199 | +============================== |
| 200 | + |
| 201 | +Note: |
| 202 | + |
| 203 | +- hsqldb atm will not be updated to version 2.3.2 due to a bug |
| 204 | + (default null+unique clause has changed) |
| 205 | +- tomcat-jdbc will not be updated to version 8.0.9 due to a strange |
| 206 | + class loader interaction with log4j when launching with mvn jetty:run |
| 207 | + |
| 208 | +mvn versions:display-dependency-updates |
| 209 | +mvn versions:display-plugin-updates |
0 commit comments