You will need
- Java 8
- Tomcat 8
- PostgreSQL 9.6.5
- Git 2.7
- Maven 3.5
- (MacOS) Homebrew
Mac OSX
brew install postgres
brew install tomcat
brew install maven
Install Java for Mac OSX manually
-
Install JDK 8, get it here
-
Set your JAVA_HOME to jdk 8 (9 will not work), i.e. add the following line to your
~/.profile
:
export JAVA_HOME=`/System/Library/Frameworks/JavaVM.framework/Versions/Current/commands/java_home`
Debian 9
sudo apt update
sudo apt install maven openjdk-8 openjdk-8-jre git curl unzip postgresql-9.6 tomcat8
-- enable some services to autostart, and start them
$ sudo systemctl enable postgresql@9.6-main.service
$ sudo systemctl start postgresql@9.6-main.service
$ sudo systemctl enable tomcat8
$ sudo systemctl start tomcat8
-- add a dhis user and create dhis2 folders
-- useful if you are setting up dhis2 on a server
$ sudo adduser dhis
$ mkdir /path/to/dhis2
$ sudo chown dhis:tomcat8 /path/to/dhis2
$ sudo chmod -R 775 /path/to/dhis2
Create your DHIS2_HOME
environment variable
Applications (e.g. DHIS2, D2) read their configuration from this folder.
$ mkdir /path/to/dhis2/home
$ export DHIS2_HOME=/path/to/dhis2/home
Frontend uses $DHIS2_HOME/config.json
to get the URL to your DHIS2 instance and uses basic auth with a base64 encoded username/password
in the format of user:pass
. The example below is the base64 encode of admin:district
.
Create the file $DHIS2_HOME/config.json
and add the following:
{
"baseUrl": "http://localhost:8080/dhis",
"authorization": "Basic YWRtaW46ZGlzdHJpY3Q="
}
Backend uses $DHIS2_HOME/dhis.conf
to get for example, configuration to the database. It will not start without this file.
connection.dialect = org.hibernate.dialect.PostgreSQLDialect
connection.driver_class = org.postgresql.Driver
connection.url = jdbc:postgresql://localhost/dhis2
connection.username = dhis
connection.password = dhis
# Database schema behavior, can be validate, update, create, create-drop
connection.schema = update
encryption.password = xxxx
Setup the database
Create a Postgres Database with name, role and password from $DHIS2_HOME/dhis.conf
.
This example assumes name, role and password to be dhis.
Linux e.g.
Open the psql
client as the postgres
user:
sudo -u postgres psql
And then create the database:
create user 'dhis' with password 'dhis';
create database "dhis2" with owner dhis;
\q
Load demo data into database
Import one of the databases shared at dhis2-demo-db.
If this step is skipped a clean DHIS2 instance will installed and will work properly, the default login for a fresh instance is admin:district
.
Linux e.g.
$ curl -o dhis2-demo.zip https://www.dhis2.org/download/resources/2.28/dhis2-demo.zip
$ unzip dhis2-demo.zip
$ sudo -u postgres psql -d dhis2 -U dhis -f demo.sql
Update 2.28 database to 2.29
This is a temporary step, but illustrates how to update a 2.28 database to a 2.29 database. If you imported a demo database for 2.29, or are starting from a fresh db, you can skip this step.
Linux e.g.
$ curl -o upgrade-229.sql https://raw.githubusercontent.com/dhis2/dhis2-utils/master/resources/sql/upgrade-229.sql
$ sudo -u postgres psql -d dhis2 -U dhis -f upgrade-229.sql
Building DHIS2 WAR-file
This will clone the dhis2-core repo to your machine, and build the master
branch. If you need
functionality on a separate branch, switch to that branch before running the mvn
commands.
It is common for frontend developers to develop against master
branch of DHIS2.
$ git clone git@github.com:dhis2/dhis2-core.git /path/to/dhis2-core
$ cd /path/to/dhis2-core/dhis-2
$ mvn clean install
-- build the `dhis.war` under `dhis-web/dhis-web-portal/target`
$ cd dhis-web
$ mvn clean install
-- to skip tests run
$ mvn clean install -Pdev
-- or
$ mvn clean install -DskipTests
-- or
$ mvn -Dmaven.test.failure.ignore=true clean install
Tomcat
You can either install Tomcat manually by downloading it as a standalone zip-file, or install it using your package manager.
If you have followed this guide these should be your paths:
Directory | Debian 9 | Mac OSX |
---|---|---|
webapps/ | /var/lib/tomcat8/webapps | /usr/local/opt/tomcat/libexec/webapps |
config/ | /etc/tomcat8 | /usr/local/opt/tomcat/libexec/config |
logs/ | /var/log/tomcat8 | /usr/local/opt/tomcat/libexec/logs |
bin/ | /usr/share/tomcat8/bin | /usr/local/opt/tomcat/libexec/bin |
If you cannot figure out your Tomcat paths on Mac OSX try:
$ brew ls tomcat
-- or
$ catalina.sh -h
...
Using CATALINA_BASE: /usr/share/tomcat8
Using CATALINA_HOME: /usr/share/tomcat8
...
Running Tomcat as another user
If you plan on running Tomcat as a different user, you need to use $CATALINA_BASE/bin/setenv.sh
to set the DHIS2_HOME
variable.
$ echo "export DHIS2_HOME=/path/to/dhis2/home" >> $CATALINA_BASE/bin/setenv.sh
$ chmod +x $CATALINA_BASE/bin/setenv.sh
Access the Tomcat Manager GUI
You need to give a user access to the web manager which can start and stop the app.
Go to your Tomcat config folder and update the tomcat-users.xml
file.
Add the lines below before the end of the XML file:
<role rolename="manager-gui"/>
<user username="tomcat" password="tomcat" roles="manager-gui"/>
If you have a running Tomcat restart it now.
Linux e.g.
-- if running as a service
$ sudo systemctl restart tomcat8
Mac OSX e.g.
-- if running as a service
brew services stop tomcat
brew services start tomcat
Deploy by dropping a WAR-file in Tomcat's webapps/
In Tomcat there is a folder called webapps/
. Tomcat monitors this folder for WAR-files, which it automatically deploys as it finds them to the context path (by default) matching the WAR-file name.
So dhis.war
will be deployed to the context path /dhis
, and is therefor available at http://localhost:8080/dhis
. You can name the WAR-file anything you want and it will be deployed with the context path of the name you gave the WAR-file, e.g. dev.war
becomes /dev
and foobar.war
is mounted to /foobar
.
Note: There is a special case for if you name your WAR-file ROOT.war
, then your context path will be /
.
Tomcat redeploys an overwritten WAR-file, so you don't need to remove the old WAR-file before dropping in the updated WAR-file.
In catalina.out
you will see when it starts deploying and when it has finished deploying the context:
-- started deploy of dhis.war
25-Jan-2018 10:29:22.161 INFO [localhost-startStop-3] org.apache.catalina.start
up.HostConfig.deployWAR Deploying web application archive /var/lib/tomcat8/weba
pps/dhis.war
...
-- completed deploy of dhis.war
25-Jan-2018 10:30:45.970 INFO [localhost-startStop-3] org.apache.catalina.start
up.HostConfig.deployWAR Deployment of web application archive /var/lib/tomcat8/
webapps/dhis.war has finished in 83,809 ms
Linux e.g.
$ sudo cp /path/to/dhis2-core/dhis-2/dhis-web/dhis-web-portal/target/dhis.war /var/lib/tomcat8/webapps/
-- monitor the deployment
$ sudo tail -f /var/log/tomcat8/catalina.out
Manual start
At your Tomcat bin folder create a setenv.sh
file where you define the $DHIS2_HOME
environment variable which will point to necessary config: export DHIS2_HOME=/path/to/dhis2/home
Start your tomcat and monitor the logs: ./startup.sh && tail -f ../logs/catalina.out
);
Autostart
When you reboot, tomcat will not start automatically. If you want tomcat to start upon login, and you have installed it via homebrew, you can do brew services start tomcat
.
Test that DHIS2 is available
At this point your Tomcat is serving DHIS2 on http://localhost:8080/dhis and you can use this URL for your frontend apps in $DHIS2_HOME/config.json
.
Go to http://localhost:8080/dhis to visit your local instance of dhis2-core.
Or if you are using a headless server:
-- test that everything works
$ curl -i -L http://localhost:8080/dhis
HTTP/1.1 302
...
HTTP/1.1 200
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Set-Cookie: JSESSIONID=A0F13BCD6E81A5FDD5C66EAFEBE8DCE4; Path=/dhis; HttpOnly
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Login-Page: true
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 25 Jan 2018 10:36:12 GMT
<!DOCTYPE HTML>
...
Congratulations!
Your very own DHIS2 instance is up and running. 🎉
Now what?
If you want, you can take a look at the advanced DHIS2 environment setup for running multiple databases, DHIS2 instances, different application servers, and more.