Ubuntu Installation

From OpenEMR Project Wiki

September 3, 2008

I am adapting the DebianInstall instructions to make use of the newer Ubuntu 8.04 Desktop. Version 8.04 LTS (long term support) is to be supported and updated by Ubuntu through 2013, unlike subsequent versions. You can download the iso file to create the single CD from http://www.ubuntu.com These instructions work with Ubuntu. They may also work with little or no change for Debian. The installation described below requires a little over 3.2 G of disk space before any significant data is entered, so be sure to have a large enough disk drive.

Ubuntu 8.04 also comes in a Server edition. While I have not tried it, I suspect that a lot of the tedium of preparing the installation with the right packages may be less with that distribution than with the Desktop Edition. I welcome any feedback on that issue. (Once you set up the server you will have the choice whether to install a browser on the Linux machine or to do the browser based setup commands through the network.)

So far, I have verified proper installation and find that everything seems to work properly. I am able to enter medical records, charges and have them appear in SQL-Ledger. I can send ANSI X12 837 files to Anvicare, a free electronic claims clearing house. With some tweaking of the pertinent files, I can also send claims directly to Highmark Blue Shield and to Medicare. SSL and access control features work well. I welcome corrections and suggestions. As of August 13, 2008 the development version of OpenEMR also generates HCFA insurance forms in pdf format. Rod Roark has recently created a release snapshot of the 2.8.4-dev tree in the 2.9.0 release version.

Some of the packages that are indicated may not be necessary, but I cannot say which ones. I just know that if you do it this way, it will work.

Download the single installation/live CD for Ubuntu 8.04 Desktop Installation. This CD will allow you to install a default system by following the instructions when you boot from the CD.

All files for the Desktop Installation are drawn from the CD, though updates and enhancements require an Internet connection.

Once the installation is complete, reboot and log into a terminal as the initial non-root user and perform these commands:

sudo passwd

Then enter your non-privileged password followed by the new password for root. You will be asked for a confirmation.

then log in as root user and proceed as below:

apt-get update

apt-get upgrade

At this point, use apt-get install command to install the following packages. You can install them one at a time, or you can type multiple packages with a single apt-get install command. For example type

apt-get install gnome-system-tools

You can string multiple packages by simply typing multiple package names instead of the one above.

At one point in the installation, you will be asked which apache features to configure automatically. I checked apache2, apache-ssl and apache-php. I think it is necessary only to check apache2.

gnome-system-tools

ssh

apache2-mpm-prefork

libapache2-mod-php5

php5-mysql

php5-pgsql

php5-cli

mysql-server-5.0

(During installation, you may be asked to provide, among other things, a password for MySQL. For now, leave it blank. It will make things easier later on when we configure phpgacl. You will not want, however, to have a blank MySQL root password in a production environment.)

postgresql-8.3

tetex-extra

libdbd-pg-perl

libxml-parser-perl

libdate-calc-perl

libfrontier-rpc-perl

imagemagick

libtiff-tools

cupsys

cupsys-bsd

cupsys-client

cups-pdf

gnome-cups-manager

I installed some other packages but cannot say for sure that all are actually necessary:

phpmyadmin

php5

php-pear

jed (an easy text editor with built-in help)

cvs

libset-scalar-perl

libparse-recdescent-perl

php5-xmlrpc

expat

Here I rebooted the computer to clean thing up, but you may want to try restarting apache instead:

/etc/init.d/apache2 restart

Once these packages are installed, test the function of the apache web server by using a broswer to view http://localhost. You should see a message “It works!” if apache is working.

You can verify the proper function of php by creating the text file /var/www/test.php with the following php content. When you create your own file, however, put "<" or ">" in place of the "{" and "}." This wiki does not display less than and greater than signs properly.

{?php

phpinfo();

?}


Then point your browser to http://localhost/test.php If php is working, you will see a long diagnostic display with the PHP logo at the top.


Install OpenEMR:

Move to directory /var/www and then type:

cvs -d:pserver:anonymous@openemr.cvs.sourceforge.net:/cvsroot/openemr co -P openemr

This will download the latest development version of OpenEMR from the cvs repository. Please refer to the CVS Howto section of this wiki for information on subsequent updating of newer versions from the repository as they become available.

(Alternatively you can install the stable release of Openemr 2.9.0 by downloading and decompressing the *.tar.gz file for that release.)

Use your text exitor to edit /var/www/openemr/interface/globals.php.

You will want to confirm that $webserver_root is set to “/var/www/openemr”; The “web root” remains the same i.e. “openemr.”

Now I made some optional changes down the file a little, namely:

'simplified_prescriptions' false became true instead of false

'concurrent_layout' true became 0 instead of 1

Now cd into this directory: /var/www/openemr/interface/main/calendar/modules/PostCalendar/pntemplates

and then type

mkdir cache compiled

Now cd into this directory: /var/www

Then type:

chown www-data.www-data openemr -Rf

Now return to your browser and type http://localhost/openemr

You should see an “OpenEMR Setup” screen. Fill out the form and keep the defaults except for the following:

server password – pick one and remember it

client root password – type in the MySQL root password you used when you installed MySQL. If you did not enter one at installation time, leave this space blank

Initial group: Type the name of your practice, or perhaps an abbreviation

Have the program create the databases.

When you are asked to make sqlconf.php world writable, pull up a text terminal, as root, and cd to /var/www/openemr/library. Then type:

chmod 777 sqlconf.php

Go back to the browser screen and proceed. When it directs you to restore the permissions of sqlconf.php, go back to the text terminal and, in the same directory as before, type:

chmod 644 sqlconf.php

Log into OpenEMR according to the instructions (or by typing http://localhost/openemr again). Initial user is “admin” and password “pass.”

Click the “administration” tab, then “forms.”

I would suggest that you click “register” for CAMOS . This menu item will then jump to the top of the page. Then click “install DB” and the “disabled” button to enable CAMOS. I have found that CAMOS is an awesome tool for enetering medical notes.

Install SQL Ledger:

From the command line, as root, type

apt-get install sql-ledger

This should install a 2.6.xx version of SQL-Ledger. As of 8/13/2008, we do not want to use anything but a 2.6.xx version of SQL-Ledger.


cd into /usr/share/sql-ledger directory

If you see a symbolic link called sql-ledger.conf (by typing ls -l, for example), then remove it by typing

rm sql-ledger.conf

Then, to replace it with a real file, type:

cp sql-ledger.conf.default sql-ledger.conf -a

Edit the sql-ledger.conf file in this directory thus:

Insert these variable names into the vars section on the first line:

$oemr_ar_acc

$oemr_cash_acc

$oemr_due_days

$oemr_username

$oemr_services_partnumber

I inserted them within the parentheses at the beginning of the pre-existing list.

A little lower in the file enter the following five lines:

$oemr_username = "openemr";

$oemr_ar_acc = "1200";

$oemr_cash_acc = "1060";

$oemr_services_partnumber = "MS";

$oemr_due_days = 40;

Note the lack of quotation marks on the last line to signify that this is numeric rather than characters.

Edit file /etc/apache2/apache2.conf

add this at the bottom of the file:

Include /etc/apache2/sql-ledger-httpd.conf

This causes configuration information in the /etc/apache2/sql-ledger-httpd.conf file to influence the behavior of apache2.

Create the following new file using your favorite text editor:

/etc/apache2/sql-ledger-httpd.conf

Include all of the thirteen lines listed below. (I'm not sure why those litte question marks show up on the wiki display -- they are not really part of what is meant to be displayed.)

Important: Anywhere you see "{" or "}" below they should actually be typed as "<" and ">" respectively -- the problem is that this wiki won't display the less than or greater than signs properly. Please disregard the question marks that display on the wiki. I have not been able to suppress them.


Alias /sql-ledger /usr/share/sql-ledger/

{Directory /usr/share/sql-ledger}

AllowOverride All

AddHandler cgi-script .pl

AddDefaultCharset On

Options ExecCGI Includes FollowSymlinks


Order Allow,Deny

Allow from All

{/Directory}

{Directory /usr/share/sql-ledger/users}

Order Deny,Allow

Deny from All

{/Directory}

Then cd /usr/share/sql-ledger

as root, type:

mkdir /var/lib/sql-ledger/spool

chown www-data.www-data /var/lib/sql-ledger/spool

ln -s /var/lib/sql-ledger/spool /usr/share/sql-ledger/

chown -hR www-data.www-data users templates css spool

Then type

/etc/init.d/apache2 restart

As root in a terminal window, type:

su postgres

createuser -d -P sql-ledger

choose a password for the “sql-ledger password” (In the setup phase, I chose the same password for all the items so I would have less difficulty remembering which one was which.) Specify "no" to superuser status and "yes" to creating other users.

While you want sql-ledger user to be able to create new users, he/she will not have root/administrative privileges.

Then type

createlang plpgsql template1

exit

Then edit the file /etc/postgresql/8.3/main/pg_hba.conf:

Near the end of the file is a line that says

IPV4

host all all 127.0.0.1/32 md5

Replace “md5” with “trust.”

Edit the file /etc/postgresql/8.3/main/postgresql.conf and uncomment the line:

listen_addresses = 'localhost'

Elsewhere in the same /etc/postgresql/8.3/main/postgresql.conf file I changed:

ssl = true

to

ssl = false

Now reboot. (At very least we need to restart postgresql-8.3 and apache2)

Then point browser to http://localhost/sql-ledger/admin.pl and log into the SQL-ledger administration screen without password.

You should get an SQL-ledger administration login menu. First, use the menu to change your SQL-Ledger administration password to something secure. To avoid unnecessary confusion, I used the same password as for the other functions. This is not a good idea for production systems, but it helped me avoid unnecessary confusion about passwords early on.

Next, click on the "Pg Database Administration" tab. You will create the dataset for openemr.

Host=localhost

Port=5432

User=sql-ledger

Password=Your sql-ledger user password

Connect to=template1

Then click "Create Dataset"

Create Dataset=openemr

Leave Multibyte Encoding blank

Create Chart of Accounts leave Default checked

Then click "Continue"

Then click "Continue" again when it says Dataset openemr succesfully created.

Next, click on "Add User."

Login=openemr

Password=enter your password that you wish to use to log in to sql-ledger here

Name=openemr

Leave everything else as is on the Add User screen and go down to the Database screen.

Driver=click Pg button

Dataset=openemr

User=sql-ledger

Host=localhost

Port=5432

Password=enter your sql-ledger user password again here

Scroll down to the bottom of the page and click save

You now edit file /var/www/openemr/interface/globals.php

Find these five entries and edit them if necessary. I found that three of the five were correct by default:

$sl_income_acc = '4320';

$sl_service_id = 'MS';

$sl_dbname = 'openemr';

$sl_dbuser = 'sql-ledger';

$sl_dbpass = 'put your database password here';

Then edit /var/www/openemr/includes/config.php

Go to the section of the file where you see references to [ws_accounting].

Change ['enabled'] from false to true

Change ['username'] to “openemr”;

Change ['password'] to “put your password here”;

Keep ['income_acct'] as “4320”;

Now do this:

cp /var/www/openemr/accounting/ws_server_26.pl /usr/share/sql-ledger/ws_server.pl -a

In its new location at /usr/share/sql-ledger/ws_server.pl, edit/change the content within the parentheses on the line beginning with

use lib qw (/xxxxxxxxxxxxxxx)

to

use lib qw (/usr/share/sql-ledger)

Restart apache2 by typing /etc/init.d/apache2 restart.

Now use browser to go to http://localhost/sql-ledger/. Log in with username openemr and open the program. You will want to click on "Goods and Services" then "Add Services" then enter "number" MS and description "Medical Services." Unclick the three radio buttons for various taxes and accept all the defaults and save this code.

Type http://localhost/openemr to log into OpenEMR. It should be linked with SQL-Ledger.

This is a good point to test operation of OpenEMR and SQL-Ledger and to debug any problems you may have before proceeding to the other steps. Php-GACL will limit logins to certain privileges. SSL allows encrypted browser connections. As far as I can tell, these can be installed in any order or skipped entirely.

FreeB, used in the past for printing paper insurance claims, is not currently being used.

I have found that in order to get SQL-Ledger and OpenEMR working together properly, it is necessary to go to the Administration menu and re-save user "admin" information and a new password once the OpenEMR and SQL-Ledger are both set up and working. The same is true of any patient demographics and other OpenEMR users you may have entered into OpenEMR before installing SQL-Ledger.


Installation of php-GACL:

Download phpgacl-3.3.7.tar.gz from http://sourceforge.net – use the search feature.

Log in to a command prompt as root and move this file into the directory /var/www/. Move (cd) into /var/www/ and in that location type:

tar zxvf phpgacl-3.3.7.tar.gz

The file will be decompressed and expanded. Then rename the directory from phpgacl-3.3.7 to phpgacl.

mv phpgacl-3.3.7 phpgacl

create the mySQL database

mysql

(You may need to specify the -p switch if you have a root password.)

at the mysql> prompt, type:

create database gacl;

exit

Next go to your browser and type http://localhost/phpgacl/setup.php

Close the window. Commands below will create the "important directory" mentioned on the screen.

Log in again as root to a command prompt.

mkdir /var/www/phpgacl/admin/templates_c

chown www-data.www-data /var/www/phpgacl/admin/templates_c

chmod 777 /var/www/phpgacl/admin/templates_c

edit the file /var/www/openemr/library/acl.inc and uncomment the line that specifies $phpgacl_location. You will need to uncomment it and ascertain that it reads as below:

$phpgacl_location = “/var/www/phpgacl”;

Next we will create password protection for the /var/www/phpgacl/admin directory.

Edit the file /etc/apache2/httpd.conf It is likely to be empty to start. In any case, add the following section at the end of the file. Again, whenever you see "{" or "}" you are to replace them with "<" and ">" in your actual file. This wiki just does not display the less than and greater than signs properly.

{Directory "/var/www/phpgacl/admin"}

AuthType Basic

AuthName “ACL Administrators”

AuthUserFile /var/www/phpgacl/admin/.htpasswd

Require valid-user

{/Directory}


Next, create the password file .htpasswd by typing these commands:

cd /var/www/phpgacl/admin

htpasswd -c /var/www/phpgacl/admin/.htpasswd admin

It will then ask for a password.

Next, restart apache by typing /etc/init.d/apache2 restart. At this point I found that I had to make the following changes to permissions and ownership:

cd /var/www/

chown www-data.www-data phpgacl -Rf

chmod 777 /var/www/phpgacl/admin/gacl_admin.inc.php

Now reboot, or restart apache by typing

/etc/init.d/apache2 restart

Use browser to go to http://localhost/phpgacl/setup.php Once you get a screen indicating that you have connected to mysql, you can click out of the display without doing anything else.

Then go to browser and type http://localhost/openemr/acl_setup.php

Finally, start phpGACL by typing

http://localhost/phpgacl/admin/acl_admin.php

You then log in with username admin and the htpasswd password you entered above. At this point I set up access to some users entered into OpenEMR using the preconfigured privilege groups in this implementation of phpGACL.

Installation of SSL:

To create a home made security certificate, type this:

openssl req $@ -new -x509 -days 365 -nodes - out /etc/apache2/apache.pem -keyout /etc/apache2/apache.pem

(There is meant to be no space between the hyphen and the out expression. This should be typed on one line.)

Next type this:

cd /etc/apache2/sites-available/

cp default ssl -a

ln -s /etc/apache2/sites-available/ssl /etc/apache2/sites-enabled/

Now here are instructions contributed by Rod Roark and okhra on how to configure virtual hosts for ports 80 and 443:

( I replaced any of the less than or greater than signs with { and } so they would show up on this WIKI -- please be aware of that. RPL)

To file /etc/apache2/ports.conf add

Listen 443

below the line

Listen 80

then remove everything else within the file.

edit file /etc/apache2/sites-enabled/ssl as follows:

a) select (i.e. copy) the whole file and paste it to the end of the file. This will allow two sections for configuring two virtual hosts.

b) change then first line to : NameVirtualHost *:80

c) change the next line to : {VirtualHost *:80}

d) Do the same in the second section but use *:443 instead of *:80 in the two corresponding places.

e) add the lines:

SSLEngine on

SSLCertificateFile /etc/apache2/apache.pem

within the body of {VirtualHost *:443} {/VirtualHost}

chmod 600 /etc/apache2/apache.pem

I activated two necessary modules by creating two symbolic links thus:

ln -s /etc/apache2/mods-available/ssl.conf /etc/apache2/mods-enabled/

ln -s /etc/apache2/mods-available/ssl.load /etc/apache2/mods-enabled/

Then restart apache by typing

/etc/init.d/apache2 restart

Now to test openemr, you can direct your browser to

https://localhost/openemr:443

You will want to firewall connections to port 80 one way or another to outside connections.


Final touch ups.

FreeB is no longer required to print paper insurance forms or to create X12 electronic claim files.

I don't know much about the inner workings of the OpenEMR package, but this installation seems to work if you follow these instructions. I have been using version 2.8.4-dev (now 2.9.0) as available as recently as September 3, 2008.

It will be helpful to set your server to a fixed rather than the default DHCP IP address. You will want to set up an automatic backup system described elsewhere.

Then come configuration and staff training, both described in the OpenEMR online documentation.

Securing and maintaining your system will an ongoing job best performed by an experienced IT person. One thing I did was to set up an automatic crontab that does a dump of the MySQL and Postgresql databases along with the content of the /var/www/openemr directory and writes them automatically to a CD after office hours. Very early on, I tested these backup files to be sure they performed as hoped to restore everything to a similar setup at another location. Documentation for backup scripts can be found elsewhere on this Wiki.


Authors:
Ronald Leemhuis MD
Dorothy Leemhuis