...
This tutorial is designed for users who are not so familiar with Linux, but need to have a platform to practice installing OpenMRS on such a system, and a general introduction to building a Ubuntu server.
Introduction
Ubuntu is a distribution of the Linux operating system which is relatively easy to use and well supported, and thus is a common choice for sites that require a dedicated OpenMRS server. Conveniently the Ubuntu Server Edition installation CD includes MySQL and Apache Tomcat.
For users who are unfamiliar with Linux it can be very useful to practice setting up both the operating system and OpenMRS on a virtual machine. Sun's VirtualBox software is flexible virtualization software package which can be installed on Windows, Linux, OS/X or Solaris. With regard to virtual machines, the term host refers to the system (usually physical) which is running the virtual machine, and guest refers to the system being run within the virtual machine. VirtualBox allows users to run Linux guests on Windows hosts, or vice versa.
Requirements
- An installation CD or ISO image for Ubuntu Server Edition (version 11.04+)
- Oracle VirtualBox (version 4+)
- OpenMRS WAR file (version 1.8+)
Creating the virtual machine
- In VirtualBox, click on New to start the New Virtual Machine Wizard, and then press Next.
- Give the new machine a name, and specify the type of operating system (Linux), and the version (Ubuntu).
- Use the default base memory size value value of 512MB.
- Select Create new disk and press Next to start the Create New Virtual Disk Wizard.
- Select Dynamically expanding storage.
- Specify a suitable path for Location, and use the default size of 8.00GB.
- Press Finish to complete that wizard, and Finish again to complete the previous wizard.
- Right-click on the machine and goto Settings... > System > Processor and select "Enable PAE/NX". This is required for the Ubuntu server kernel.
Installing Ubuntu Server Edition
- Start the virtual machine, and assuming this is the first time it has been started, you will see the First Run Wizard:
- Under Media Source select Image File.
- Click the folder icon beside the image list to open the Virtual Media Manager.
- Select Add from the top menu, and browse to the Ubuntu Server ISO (e.g. ubuntu-11.04-server-i386.iso).
...
- Double-click
...
- the
...
- ISO
...
- file
...
- in
...
- the
...
- list
...
- to
...
- select
...
- it
...
- and
...
- close
...
- the
...
- wizard.
...
- Press
...
- Finish
...
- and
...
- the
...
- virtual
...
- machine
...
- will
...
- boot
...
- from
...
- the
...
- installation
...
- CD.
...
- Select
...
- your
...
- language
...
- by
...
- using
...
- the
...
- arrow
...
- keys
...
- and
...
- then
...
- the
...
- enter
...
- key
...
- (this
...
- is
...
- only
...
- used
...
- for
...
- the
...
- initial
...
- menu).
...
- Select
...
- Install
...
- Ubuntu
...
- Server.
...
- Select
...
- the
...
- language
...
- for
...
- the
...
- installation.
...
- Select
...
- your
...
- location.
...
- If
...
- you
...
- know
...
- your
...
- keyboard
...
- layout
...
- (most
...
- likely
...
- USA)
...
- skip
...
- auto-detection
...
- and
...
- select
...
- it
...
- from
...
- the
...
- list.
...
- The
...
- installer
...
- will
...
- try
...
- to
...
- automatically
...
- configure
...
- the
...
- networking
...
- settings,
...
- if
...
- you
...
- have
...
- disabled
...
- network
...
- access
...
- then
...
- this
...
- will
...
- fail.
...
- If
...
- so,
...
- select
...
- Do
...
- not
...
- configure
...
- networking
...
- at
...
- this
...
- time.
...
- Enter
...
- a
...
- suitable
...
- hostname.
...
- Next
...
- the
...
- partitioner
...
- dialog
...
- will
...
- be
...
- displayed.
...
- Linux
...
- operating
...
- systems
...
- require
...
- separate
...
- partition
...
- for
...
- swap
...
- space,
...
- but
...
- the
...
- installer
...
- can
...
- configure
...
- this
...
- for
...
- you:
...
- Select
...
- "Guided
...
- -
...
- use
...
- entire
...
- disk"
...
- to
...
- use
...
- the
...
- entire
...
- virtual
...
- hard
...
- disk
...
- for
...
- Ubuntu.
...
- Select
...
- SCSI1
...
- (0,0,0)
...
- (sda)
...
- -
...
- 8.6GB
...
- ATA
...
- VBOX
...
- HARDDISK.
...
- Select
...
- Yes
...
- for
...
- Write
...
- changes
...
- to
...
- disk
...
- to
...
- finish
...
- the
...
- partitioning
...
- task.
...
- Provide
...
- a
...
- user
...
- name,
...
- and
...
- password
...
- for
...
- the
...
- administrator
...
- account.
...
- Allow
...
- installer
...
- to
...
- update
...
- list
...
- of
...
- packages,
...
- or
...
- cancel
...
- to
...
- update
...
- later
...
- Choose
...
- an
...
- update
...
- management
...
- strategy
...
- Using
...
- the
...
- arrow
...
- keys
...
- and
...
- spacebar,
...
- select
...
- LAMP
...
- Server,
...
- OpenSSH
...
- Server
...
- and
...
- Tomcat
...
- Java
...
- Server.
...
- Provide
...
- a
...
- root
...
- password
...
- for
...
- MySQL
...
- which
...
- you
...
- will
...
- need
...
- later.
...
- The
...
- installer
...
- will
...
- finish
...
- by
...
- rebooting
...
- into
...
- Ubuntu.
...
- If
...
- you
...
- mounted
...
- the
...
- installation
...
- ISO
...
- yourself,
...
- then
...
- you
...
- should
...
- unmount
...
- it
...
- (see
...
- the
...
- Devices
...
- menu)
...
- to
...
- avoid
...
- re-running
...
- the
...
- installer.
...
Configuring
...
Apache
...
Tomcat
For this step and some subsequent steps we need to edit files on the guest. If you are familiar with editors such as vi or vim you can use one of them, but if not then
is recommended as it easy to use and already installed. The sudo command causes the command following it to be run as root.
- Login and type:
Code Block sudo nano /etc/tomcat6/tomcat-users.xml
...
- Create a user with the manager and admin roles. Don't
...
- forget
...
- to
...
- remove
...
- the
...
- XML
...
- comments
...
- (<
...
- !-
...
- -
...
- >),
...
- so
...
- the
...
- result
...
- should
...
- look
...
- like:
...
Code Block
...
<tomcat-users> <user username="admin" password="XXXXXX" roles="admin,manager"/> </tomcat-users>
...
- Save (Ctrl+O)
...
- and
...
- exit
...
- (Ctrl+X).
...
- Restart
...
- Tomcat
...
- using
...
- the
...
- initialization
...
- script:
...
Code Block
...
sudo /etc/init.d/tomcat6 restart
...
Configuring Port Forwarding to the Guest
VirtualBox's
...
NAT
...
option
...
allows
...
network
...
requests
...
to
...
the
...
host
...
to
...
be
...
forwarded
...
to
...
the
...
guest,
...
which
...
means
...
other
...
computers
...
can
...
access
...
services
...
such
...
as
...
Tomcat
...
which
...
are
...
running
...
on
...
the
...
guest,
...
as
...
if
...
they
...
were
...
running
...
on
...
the
...
host.
...
This
...
step
...
forwards
...
requests
...
on
...
port
...
8090
...
on
...
the
...
host,
...
to
...
port
...
8080
...
on
...
the
...
guest,
...
which
...
is
...
Tomcat's
...
default
...
port.
...
- Shutdown
...
- the
...
- virtual
...
- machine
...
- if
...
- it
...
- is
...
- still
...
- running
...
Code Block
...
sudo shutdown -h 0
...
- Right-click
...
- on
...
- the
...
- machine
...
- and
...
- goto
...
- Settings...
...
- >
...
- Network
...
- >
...
- Port
...
- Forwarding
...
- Add
...
- a
...
- new
...
- rule
...
- Name:
...
- Tomcat
...
- Protocol:
...
- TCP
...
- Host
...
- port:
...
- 8090
...
- Guest
...
- port:
...
- 8080
...
- Restart
...
- the
...
- virtual
...
- machine.
...
- On
...
- the
...
- host,
...
- browse
...
- to
...
...
- to
...
- verify
...
- that
...
- the
...
- port
...
- is
...
- being
...
- forwarded
...
- correctly
...
Install
...
OpenMRS
...
- On
...
- the
...
- guest
...
- machine,
...
- type
...
- the
...
- following
...
- to
...
- create
...
- the
...
- OpenMRS
...
- runtime
...
- directory:
...
Code Block
...
sudo mkdir /usr/share/tomcat6/.OpenMRS sudo chown -R tomcat6:root /usr/share/tomcat6/.OpenMRS
...
- On the host,
...
- browse
...
- to
...
...
- to
...
- access
...
- the
...
- Tomcat
...
- Managment
...
- webapp.
...
- Under
...
- the
...
- heading
...
- Deploy
...
- >
...
- WAR
...
- file
...
- to
...
- deploy,
...
- browse
...
- to
...
- the
...
- OpenMRS
...
- WAR
...
- file,
...
- and
...
- then
...
- press
...
- "Deploy".
...
- Tomcat
...
- should
...
- report
...
- that
...
- the
...
- deployment
...
- succeeded.
...
- Browse
...
- to
...
...
- to
...
- begin
...
- the
...
- step-by-step
...
- installation
...
- of
...
- OpenMRS.
...
- Step
...
- 1:
...
- Select
...
- No
...
- under
...
- Do
...
- you
...
- currently
...
- have
...
- an
...
- OpenMRS
...
- database...
...
- and
...
- then
...
- enter
...
- the
...
- MySQL
...
- root
...
- password.
...
- Press
...
- Continue.
...
- Step
...
- 2:
...
- Select
...
- Yes
...
- under
...
- Do
...
- you
...
- want
...
- to
...
- add
...
- demo
...
- data...
...
- (assuming
...
- you
...
- want
...
- common
...
- concepts
...
- and
...
- some
...
- sample
...
- patients)
...
- Select
...
- No
...
- under
...
- Do
...
- you
...
- currently
...
- have
...
- a
...
- database
...
- user...
...
- and
...
- again
...
- enter
...
- the
...
- MySQL
...
- root
...
- password.
...
- Press
...
- Continue.
...
- Step
...
- 3:
...
- Leave
...
- default
...
- values,
...
- and
...
- press
...
- Continue.
...
- Step
...
- 4:
...
- Specify
...
- a
...
- suitable
...
- admin
...
- password,
...
- and
...
- press
...
- Continue.
...
- Step
...
- 5:
...
- Leave
...
- values
...
- blank,
...
- and
...
- press
...
- Continue.
...
- Step
...
- 6:
...
- Press
...
- Finish
...
- to
...
- start
...
- the
...
- OpenMRS
...
- installation
...
- process,
...
- which
...
- will
...
- take
...
- a
...
- few
...
- minutes.
...
Conclusion
You should now have a working OpenMRS server, which being a virtual machine, can be paused and resumed whenever it is needed. Additional tasks that you might want to try are:
- Configure port forwarding to the guest on port 22 to allow SSH connections to the guest system:
- Shutdown the machine
- Goto Settings... > Network > Port Forwarding
- Add a new rule to map the host port 2222 to the guest port 22
- Try connecting from host
Code Block ssh localhost -p 2222
...