Getting started
If you are new to git and git workflows we have set up a sandbox repository for you to play with. It is a place to safely make mistakes and we encourage you to use it. We have general instrutions to help you get started with git.Sandbox wiki If you find errors or have insights to ease the pain please let us know.
[Official GitHub teaching site] (https://help.github.com)
[Git made my life a living nightmare, what should I do] (http://justinhileman.info/article/git-pretty/git-pretty.png)
If you are not familiar with git follow these steps in the Sandbox The following are for the sandbox, once you are comfortable, repeat these steps with production code instead of the sandbox repository.
-
Get a copy of the code to work with
a. Create a Github.com account if you do not have one
b. Go to [openelisglobal sandbox] (https://github.com/openelisglobal/openelisglobal-sandbox)
c. Fork the repository into your new github account
d. Clone the repository that you just created in your Github account onto your desktop. On your local machine your -fork will be known as the 'origin' repository.
This cloned repository is what you develop your new feature in. Typically you will develop small fixes and features in the "develop" branch. For more significant features or changes you should create a branch and name it something related to the feature following our [branching model] (http://nvie.com/posts/a-successful-git-branching-model/)
To set the original repository [sandbox] (https://github.com/openelisglobal/openelisglobal-sandbox) or [production] (https://github.com/openelisglobal/openelisglobal-core) as the "upstream" repository, you issue the command
git remote add upstream https://github.com/openelisglobal/openelisglobal-sandbox
(or use the Eclipse plugin tools "Team > Fetch from upstream". By default the plug-in will have stored the origin of the repository, in this case the repo that you cloned from in your Github home directory).
When you commit, you are commiting to your local cloned copy of the repository
When your feature development is complete you push the changes from your local repository to your copy of the repository in your account on Github.com using the command
git push origin
(origin should be set to your github.com copy of the repository. Or, use the Eclipse plugin tools "Team > Push..." (confirm that Push is configured to use your Gtihub.com repo)
Once your changes have been pushed to the repository in your Github.com account, you can then issue a "pull request" to request that the changes be merged into the "upstream"/original repository
OpenELIS is currently using Postgresql 8.4. Which can be downloaded from http://www.enterprisedb.com/products-services-training/pgdownload. The 8.4 version is at the bottom of the page.
OpenELIS does work with 9.3.5 (the current version as of this writing) however additional functionality has been added and if you use that functionality OpenELIS will break as soon as it is deployed. If you really want to use 9.3.5 and understand the risks then you can do it but definitely use the 8.4 documentation http://www.postgresql.org/docs/manuals/archive/
Download from here
- Installation directory
- User names
- Postgres user account password
- Root database name and password
- clinlims password
- clinlimsSU password
Launch installer and accept all defaults. The password for the user account should be recorded someplace safe.
There are several useful tools that will be installed with the database. The most import one is pgAdminIII
Selecting pgAdminIII will bring up the following screen
To connect double click on the small red X. You will be prompted for the password that you set up when you installed the application. If you did not keep track of the password you will have to uninstall and reinstall the postgres.
First add two new users to the system.
Right click on “Login Roles(1)” in the lefthand panel add the following for the user clinlims. Note that the account never expires and they have no role privileges. The password can be whatever you would like but you should keep track of it for later use in configuring OpenELIS to communicate with DB
Note that this password should not be made public. The other login role that should be added is for clinlimsSU. This user should have Superuser role privileges. The password should be different from the clinlims user and be kept safe.
Add two new connections by clicking on the plug icon in the upper left corner. Below is the connection for the clinlims. You should make a similar one for clinlimsSU
The end result will look similar to this
Open up the SU connection, you will be prompted for the clinlimsSU password
Right click on “Databases” and select “new database”
Fill in the new database form
Use psql to import the database with the configuration you want. It is easiest to work in the directory with the backups so change to ..\openelisglobal-core\installerTemplate\baseDatabases (this should have already been added locally to your machine).
Note which configuration you want to work with. They differ by what is in the test catalog and which features are active. If you are not sure then start with CI_IPCI. On Linux the path to psql has been set but on windows you will need to specify the complete path i.e.
"c:\Program Files (x86)\PostgreSQL\8.4\bin\psql.exe" -h localhost -U clinlims clinlims
You may need to give the password you used when you created the role of clinlims.
Once in the psgl shell you can inport the database with:
clinlims=> \i CI_IPCIOpenElis.backup
You will see some warnings about privileges as the script finishes but those can be ignored.
To exit the shell
clinlims=>\q
Not needed for Postgres 9.1 or latter
We use the tablefunc group of functions. In particular, the crosstab function. While these functions come with the installation, they are not preinstalled. They must be added to any database which wants to use them.
On a Linux system, contributions including the tablefunc.sql are part of a separate package postgresql-contrib. They can be installed with:
>pg_config --sharedir
> cd /the/postgres/share/dir=
(if the pg_config command is not found, try something like: /usr/share/postgresql/8.4)
> sudo -u postgres psql -d cdielis < contrib/tablefunc.sql
On Windows:
> pg_config --sharedir
> cd \the\postgres\share\dir\
(if the pg_config command is not found, try something like \my\tools\postgreSQL\8.4\share, or \Program Files\postgreSQL\8.4)
> psql -d cdielis -U postgres -W < contrib\tablefunc.sql
Note: cdielis in the above commands should be replaced with the name of the installed database
The schema and metadata have to be updated to the latest version. The instructions for using liquibase are here
OpenElis currently uses tomcat 6.x and while new versions may work as well (or better) there may be some incompatibilities. Feel free to try newer versions but you are on your own.
If you using Windows, Tomcat should not be installed as a service, NetBeans looks for a startup bat file which the service does not have.
Tomcat 6 can be downloaded from here
Unzip it wherever on the file system you wish to have it run.
The only change needed is:
- Add the correct postgres driver to the library.
Copy OpenElisDev\openelisglobal-core\installerTemplate\linux\bin\postgresql-jdbc3-8.2.jar To Tomcat6\lib\
Which IDE you use is entirely up to you. Among current developers we use IntelliJ, Eclipse and NetBeans. The easiest way to start a never ending argument to claim which is the best. Both Eclipse and NetBeans are free and of the two NetBeans is easier to set up so that is the one we recommend, however being able to work with the tool that you are most comfortable with outweighs our opinions. We have instructions for setting up both NetBeans workspace (see below) and settingup Eclipse workspace ([see below] (#eclipse))
Installing
- Download Netbeans from here
- Select “Java EE” for the download
When running the installer
- Deselect installing Glassfish AND Tomcat
- Accept the rest of the defaults
Importing project
-
Start Netbeans
-
Go to File->New project
-
Select Java EE project
-
Select “Java WEB” and then “Web application with existing sources”
-
Next
-
Location -> the directory where openelisgloabal-core was installed on your file system Accept defaults
-
Next
-
No server will be available because neither tomcat nor glassfish was installed.
However there is a button for configuring a new server.
Select “Apache Tomcat or TomEE”, give it a better name in the space provided at the bottom of the dialog.
At the next step of adding the new service you will be asked to find the base of the tomcat installation.You will also be asked to provide a name and password for a manager role in for that instance of tomcat.
If there is an existing name and password use that or if you can make up a new name and password and NetBeans will add them to the tomcat users config file.
It will also drill a huge security hole into your installation. In addition to the management role it tells you about it also adds admin role to the name and password you just added.
To help reduce the risk change to the tomcat6\webapps\ directory and delete the “manager”, “ROOT” and “host-manager” application.
Also remove the corresponding xml files from tomcat6\conf\Catalina\localhost When you click finish on the install server dialog you will be ready to continue with adding the project -
Next
-
Accept default file locations *Finish
Launching App
openelisglobal-core\app\WebContent\META-INF\context.xml Set context.xml to the following (note that you will need to make sure the database name and credentials match)
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ The contents of this file are subject to the Mozilla Public License
~ Version 1.1 (the "License"); you may not use this file except in
~ compliance with the License. You may obtain a copy of the License at
~ http://www.mozilla.org/MPL/
~
~ Software distributed under the License is distributed on an "AS IS"
~ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
~ License for the specific language governing rights and limitations under
~ the License.
~
~ The Original Code is OpenELIS code.
~
~ Copyright (C) ITECH, University of Washington, Seattle WA. All Rights Reserved.
-->
<Context path="/openelisglobal-core">
<Resource auth="Container"
driverClassName="org.postgresql.Driver"
maxActive="20"
maxIdle="10"
maxWait="-1"
name="jdbc/LimsDS"
password="clinlims"
type="javax.sql.DataSource"
url="jdbc:postgresql://localhost:5432/<name of database>"
username="clinlims"/>
</Context>
- Click on either run or debug button and you should be up and running.
- The url for the app will be http://localhost:8080/openelisglobal-core/
Further notes (thanks to Ezekiel Chiteri)
Deploying from Netbeans to the local server:
Successfully setting up the tomcat server will enable automatic deployment when you select the project and click Deploy (of course after Building) I prefer turning off automatic deployment on save by right-clicking the project and selecting Properties. Select Compiling under Build and deselect Compile on Save check box
Adding Hibernate framework:
If you haven't added this already, right click the OpenElis project in Netbeans and select properties. On the window, select Frameworks and click the Add button. Select the framework you want to add.
Configuring encoding:
To set default file encoding in NetBeans, go to NetBeans installation directory and edit "etc/netbeans.conf". Add the option "-J-Dfile.encoding=UTF-8" to "netbeans_default_options"
Restart NetBeans and the default encoding should be UTF-8. Check this under "Help - About":
Including iReports on Netbeans
Follow this link https://www.packtpub.com/books/content/ireport-netbeans . The page also has instructions on setting up database on Netbean, i think it is resourceful, and more on using jasper reports within Netbeans (N.B. we do not directly use the database as a data source for reports)
Using NetBeans
Using NetBeans is beyond the scope of this document but we will briefly cover using git within the application.
Because the code was cloned from github NetBeans has already configured itself to use git and it knows the git origin. To set the upstream repository the normal git tools can be used or you can use the ones within NetBeans.
When you are ready to commit code use the menu items under “Team” to commit it first to your local git repository and then push it to YOUR github account.
But before you do a commit remember to do a pull from the upstream repository so that you will be assured that your work will be able to be merged into the main repository.
-
Clone the repository: Use [sandbox example first] (https://github.com/openelisglobal/openelisglobal-sandbox) Save the cloned git directory structure to your workspace a. From your Eclipse work-space directory
git clone https://github.com/your-github-account-name/openelisglobal-sandbox.git -
In eclipse create a new project
a. New > Dynamic Web Project
b. Uncheck "Use default location" and browse to the location of the git clone and then down one sub-directory to "app". The "app" directory is the root of the Dynamic Web Project.
c. Dynamic web module version should be set to 2.5
d. Choose a new Project name (for this example we will use "OESandbox") and then click "next". The wizard should find the "src" directory and the default output folder "build\classes"
e. Click next. On the Web Module config page, make sure the Context root is set to the name you selected and the Content directory is set to WebContent.
f. Uncheck the "Generate web.xml deployment descriptor".
g. Click Finish.
-
Right click on the new project in the Project Explorer (or Project > Properties) and click "Java Build Path" in the Properties dialog and configure the build path
a. Make sure that OESandbox/src is entered in the box labeled "Source folders on build path" under the "Source" tab. If it is not there by default, then click "Add Folder" and add it as an entry.
b. At the bottom of the "Source" tab page, verify that "OESandbox/build/classes" is entered as the "Default output folder".
c. Click the "Libraries" tab. If there is not a "Web App Libraries" group, or if there is and it is empty of jars, then click "Add JARs...". Navigate to "OESandbox > WebContent > WEB-INF > lib" and select all jars in the directory and add them to the project.
-
Switch to the development branch for adding features and fixing bugs
a. Right click on the OESandbox project and select Team > Switch To > Other... A dialog box will appear titled "Branches". Open the "Remote Tracking" folder and choose "origin/develop" then click the "Checkout" button. Another dialog box will appear asking for you to choose how you would like to checkout the remote-tracking branch. Choose "Checkout as New Local Branch".
-
Create a project for liquibase and future database upgrades
a. Right click on the new project in the Project Explorer (or Project > Properties) and click "New Project...". Find the "General" folder. Open it and select "Project".
b. Name the project "openElisGlobal-liquibase".
c. Uncheck "Use default location" and browse to the location of the git clone and then down one subdirectory to "liquibase". The "liquibase" directory is the root of the New Project.
d. Click "Next" (there are no referenced projects) and then click "Finish".
e. Follow the instructions to update your local database with liquibase located here:
-
Return to the Dynamic Web Project (OESandbox in this case) and edit the context.xml file
a. Open the OESandbox application and navigate to OESanbox > WebContent > META_INF. Right click on META_INF and select New > File. Name the new file "context.xml" and paste the following into the content of the file and save it:
Note: You will need to edit the "url" attribute to match your database. In this example postgresql is listening to the default port and the name of the database is "htlnsp".
<Context path="openElisGlobal">
<Resource auth="Container"
driverClassName="org.postgresql.Driver"
maxActive="20" maxIdle="10" maxWait="-1"
name="jdbc/LimsDS"
password="clinlims"
type="javax.sql.DataSource"
url="jdbc:postgresql://localhost:5432/htlnsp"
username="clinlims"/>
</Context>
Note: These directions assume that you have a tomcat server already configured within Eclipse. Add OESandbox to your Tomcat server and build the project. At this point everything should work.
git://github.com/openelisglobal/openelisglobal-core.git