-
Notifications
You must be signed in to change notification settings - Fork 77
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.
[Get, fetch and merge](Video Demo from OpenMRS folks: http://www.youtube.com/watch?v=x5OJvil1HE8)
[Official GitHub teaching site] (http://teach.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
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))
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\
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/
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
IDE integration From openMRS https://wiki.openmrs.org/display/docs/Git+IDE+Integration Experimenting with git and github