INSTALL

   1 Installation Instructions
   2 -------------------------------------
   3
   4 OSI Certified Open Source Software
   5
   6 -------------------------------------
   7
   8 I...................Overview of files
   9 II..................Unpacking
  10 III.................Setup
  11 IV..................Upgrading
  12 V...................Version History
  13
  14 -------------------------------------
  15
  16 I. Overview of Directories
  17
  18 accounting    - Contains information and scripts to support SQL-Ledger
  19 contrib       - Contains many user-contributed encounter forms and utilities
  20 custom        - Contains scripts and other text files commonly customized
  21 Documentation - Contains useful documentation
  22 interface     - Contains User Interface scripts and configuration
  23 library       - Contains scripts commonly included in other scripts
  24 sql           - Contains initial database images
  25
  26 II. Unpacking
  27
  28 The OpenEMR release archive should be named as follows:
  29
  30 openemr-<version>.tar.gz  -or-  openemr-<version>.zip
  31
  32 To extract the archive, use either of the following commands from the command line:
  33
  34 bash# tar -pxvzf openemr-<version>-release.tar.gz
  35 bash# unzip openemr-<version>-release.tar.gz
  36
  37 Be sure to use the -p flag when using tar, as certain permissions must be preserved.
  38
  39 OpenEMR will be extracted into a directory named openemr.
  40
  41 III. Setup
  42
  43 To run OpenEMR, MySQL and Apache or another PHP-capable webserver must be configured.
  44 To download Apache, visit www.apache.org
  45 For information on how to install MySQL, visit www.mysql.com
  46 PHP may be downloaded from www.php.net
  47
  48 OpenEMR requires a number of webserver and PHP features which may not be
  49 enabled on your system.  These include:
  50
  51 - PHP Index support (ensure that index.php is in your Index path in httpd.conf)
  52 - Session variables
  53 - PHP libcurl support (optional for operation, mandatory for billing
  54
  55 Copy the OpenEMR folder into the root folder of the webserver. On Mandrake
  56 Linux, for example, use the command:
  57
  58   bash# mv openemr /var/www/html/
  59
  60 Make sure the webserver is running, and point a web-browser to setup.php located
  61 within the openemr web folder.  If you installed OpenEMR in the root web
  62 directory, the URL would read: http://localhost/openemr/setup.php.
  63 The setup script will step you through the configuration of the database.
  64
  65 In step 1, you need to tell setup whether it needs to create the databases on
  66 its own, or if they you have already created them.  MySQL root priveleges will
  67 be required to create a database.
  68
  69 In step 2, you will be presented with a number of fields which specify the MySQL
  70 server details.
  71
  72 The "Server Host" field is the hostname of the MySQL server.  If you use the
  73 mysql command line client, this is the string you would type after the -h flag.
  74 If this is on the same machine as the webserver, leave this as "localhost".
  75
  76 The "Server Port" field specifies the port to use when connecting to the MySQL
  77 server over TCP/IP.  This should be left as 3306 unless you changed it in your
  78 MySQL configuration.
  79
  80 The "Database Name" field is the database where OpenEMR will reside.  If you
  81 selected to have the database created for you, this database will be created,
  82 along with the user specified in "Login Name".  If this database exists, setup
  83 will not be able to create it, and will return an error.  If you selected that
  84 you have already created the database, then setup will use the information you
  85 provide to connect to the MySQL server.  Note that setup will not accept a
  86 password that is not at least one (1) character in length.
  87
  88 The "User Hostname" field accompanies the Login Name field.  It is the hostname
  89 from which the user is permitted to connect to the database.  This will only
  90 appear if setup is creating the database.
  91
  92 The "Root Pass" field will likewise only appear when setup is creating the
  93 database.  It is the password of your existing root user, and is used to acquire
  94 the privileges to create the new database and user.  The rest of the fields are
  95 specific to your practice.
  96
  97 The "Initial User" is the username of the first user, which is what they will
  98 use to login.  Their default password will always be "pass", without the quotes.
  99 The "Initial User's Name" is the value to be used as their last name.  This
 100 information may be changed in the user administration page.
 101
 102 The "Initial Group" is the first group that will be created.  A user may belong
 103 to multiple groups, which again, can be altered on the user administration page.
 104 It is suggested that no more than one group per office be used.
 105
 106 Step 3 is where setup will install the database and connect to it to create the
 107 initial tables.  If no errors occur, you will see a "Continue" button at the
 108 bottom.  Before clicking this, you need to ensure that the webserver user
 109 (often "nobody", "apache", or "www-data") has write privileges on the
 110 library/sqlconf.php file.  The command "chmod a+w library/sqlconf.php" will
 111 grant global write permissions to the file.  Be sure to set them back to
 112 something more secure (such as chmod 644) before actively using OpenEMR.
 113
 114 Should anything fail during step 3, you may have to remove the existing database
 115 or tables before you can try again.
 116
 117 Step 4 is very much like step 3, except the only thing taking place is the
 118 writing of SQL configuration to disk.  Should it fail due to permissions or any
 119 other reason, you may click the reload button to try again.
 120
 121 Once setup is completed, one last thing must be done before OpenEMR can be used.
 122 The file openemr/interface/globals.php must be edited by hand to reflect the
 123 path and address of your webserver. The values for $webserver_root and $web_root
 124 must be set accordingly. Also, to change the appearance of OpenEMR, uncomment or
 125 comment theme-description lines at the bottom of config.php.
 126
 127 Once the system has been configured properly, you may login.  Connect to the
 128 webserver where the files are stored with your web browser.  Login to the system
 129 using the username that you picked (default 'admin' without quotes), and the
 130 password 'pass', without the quotes.  From there, select the "Administration"
 131 option, and customize the system to your needs.  Add users and groups as is
 132 needed. For information on using OpenEMR, consult the User Documentation located
 133 in the Documentation folder.
 134
 135 To create custom encounter forms, see the files
 136
 137   openemr/Documentation/3rd Party Form API.txt
 138   openemr/interface/forms/OpenEMR_form_example-rev2.tar.gz
 139
 140 and read the included documentation. Many forms exist in contrib/forms as well
 141 as in interface/forms and may be used as examples.
 142
 143 Other configuration settings are stored under includes/config.php.
 144 Everything should work out of the installation without touching those, but if
 145 you want fax, sql-ledger, and/or Freeb integration you will need to adjust some
 146 parameters in that file.
 147
 148 IV. Setting Up Access Control
 149
 150 As of this writing the option of adding phpGACL to your OpenEMR installation is
 151 a work in progress.  You can choose to do nothing about this, in which case
 152 OpenEMR's traditional and very limited access controls will be used, or you can
 153 choose to install phpGACL (see http://phpgacl.sourceforge.net/), in which case
 154 you should read the phpGACL manual and the comments in library/acl.inc and also
 155 modify that file to point to your phpGACL installation directory.  See
 156 Documentation/README.phpgacl for more information.
 157
 158 It is reasonable to first get a basic OpenEMR installation working and then add
 159 these extended access controls later.
 160
 161 V. Upgrading
 162
 163 Upgrading OpenEMR is currently done by replacing the old openemr directory with
 164 a newer version. Before replacing the old openemr directory, copy the following
 165 two files out, and replace them into the new openemr folder afterwards:
 166
 167   openemr/interface/globals.php
 168   openemr/library/sqlconf.php
 169   openemr/library/sql-ledger.inc
 170   openemr/includes/config.php (if you have modified it)
 171
 172 But before replacing them, compare the old and new files in case there are
 173 new parameters that need to be included.  If there are other files that you
 174 have customized, then you will also need to treat those carefully.
 175
 176 When upgrading, check the directory openemr/sql/ for files named *upgrade.sql
 177 Those files have sql statements to modify tables in your database so they will
 178 match the layout of the current version.
 179 Be sure to backup the content of your database before doing so.