ordering of search by selection on left nav window
[openemr.git] / INSTALL
blob6320bad82c75c7042312c0b8d601ec0500754f07
1 Installation Instructions
2 -------------------------------------
4 OSI Certified Open Source Software
6 -------------------------------------
8 I...................Overview of Directories
9 II..................Unpacking
10 III.................Setup
11 IV..................Setting up Access Control
12 V...................Upgrading
14 -------------------------------------
16 I. Overview of Directories
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 gacl          - Contains embedded php-GACL (access controls)
27 II. Unpacking
29 The OpenEMR release archive should be named as follows:
31 openemr-<version>.tar.gz  -or-  openemr-<version>.zip
33 To extract the archive, use either of the following commands from the command line:
35 bash# tar -pxvzf openemr-<version>-release.tar.gz
36 bash# unzip openemr-<version>-release.tar.gz
38 Be sure to use the -p flag when using tar, as certain permissions must be preserved.
40 OpenEMR will be extracted into a directory named openemr.
42 Alternatively a Debian package may be available as a file named
43 openemr-<version>.deb.  This may work with some other Debian-like
44 Linux distributions such as Ubuntu.
46 III. Setup
48 To run OpenEMR, MySQL and Apache or another PHP-capable webserver must be configured.
49 To download Apache, visit www.apache.org
50 For information on how to install MySQL, visit www.mysql.com
51 PHP may be downloaded from www.php.net
53 OpenEMR requires a number of webserver and PHP features which may not be
54 enabled on your system.  These include:
56 - PHP Index support (ensure that index.php is in your Index path in httpd.conf)
57 - Session variables
58 - PHP libcurl support (optional for operation, mandatory for billing)
60 Copy the OpenEMR folder into the root folder of the webserver. On Mandrake
61 Linux, for example, use the command:
63   bash# mv openemr /var/www/html/
65 Make sure the webserver is running, and point a web-browser to setup.php located
66 within the openemr web folder.  If you installed OpenEMR in the root web
67 directory, the URL would read: http://localhost/openemr/setup.php.
68 The setup script will step you through the configuration of the OpenEMR.
70 The first screen of the setup script will ensure that the webserver user
71 (in linux, often is "apache", "www-data", or "nobody") has write privileges on
72 certain files and directories. The files include openemr/interface/globals.php and
73 openemr/library/sqlconf.php. In linux, these can be set by "chmod a+w filename"
74 command to grant global write permissions to the file, The directories include
75 openemr/gacl/admin/templates_c, openemr/edi, openemr/era, openemr/documents,
76 openemr/library/freeb, openemr/custom/letter_templates, 
77 openemr/interface/main/calendar/modules/PostCalendar/pntemplates/compiled, and 
78 openemr/interface/main/calendar/modules/PostCalendar/pntemplates/cache.  In
79 linux, if the webserver user name is "apache", then the command
80 "chown -R apache:apache directory_name" will grant global write permissions
81 to the directories, and we recommend making these changes permanent.
82 Should the page display errors related to file or directory writing priviledges you 
83 may click the 'Check Again' button to try again (after fixing permissions).
85 In step 1, you need to tell setup whether it needs to create the database on
86 its own, or if you have already created the database.  MySQL root priveleges will
87 be required to create a database.
89 In step 2, you will be presented with a number of fields which specify the MySQL
90 server details and the openemr directory paths.
92 The "Server Host" field specifies the location of the MySQL server.  If you
93 run MySQL and Apache/PHP on the same server, then leave this as 'localhost'. 
94 If MySQL and Apache/PHP are on separate servers, then enter the IP address
95 (or host name) of the server running MySQL.
97 The "Server Port" field specifies the port to use when connecting to the MySQL
98 server over TCP/IP.  This should be left as 3306 unless you changed it in your
99 MySQL configuration.
101 The "Database Name" field is the database where OpenEMR will reside.  If you
102 selected to have the database created for you, this database will be created,
103 along with the user specified in "Login Name".  If this database exists, setup
104 will not be able to create it, and will return an error.  If you selected that
105 you have already created the database, then setup will use the information you
106 provide to connect to the MySQL server.  Note that setup will not accept a
107 password that is not at least one (1) character in length.
109 The "Login Name" field is the MySQL user that will access the OpenEMR database.
110 If you selected to have the database created for you, this user will be
111 created.  If you selected that you have already created the database, 
112 then setup will use the information you provide to connect to the MySQL server.
114 The "Password" field is the password of the user entered into the above
115 "Login Name" field.  If you selected to have the database created for you,
116 this user and password  will be created.  If you selected that you have already
117 created the database, then setup will use the information you provide to connect
118 to the MySQL server.
120 The "Name for Root Account" field will only appear if setup is creating the
121 database.  It is the name of the MySQL root account. For localhost, it is
122 usually ok to leave it 'root'.
124 The "Root Pass" field will likewise only appear if setup is creating the
125 database.  It is the password of your existing root user, and is used to acquire
126 the privileges to create the new database and user.
128 The "User Hostname" field will also only appear if setup is creating the 
129 database.  It is the hostname of the Apache/PHP server from which the user
130 ("Login Name") is permitted to connect to the MySQL database.  If you are setting
131 up MySQL and Apache/PHP on the same computer, then you can use 'localhost'.  
133 The "UTF-8 Collation" field is the collation setting for mysql. If the language
134 you are planning to use in OpenEMR is in the menu, then you can select it.
135 Otherwise, just select 'General'. Choosing 'None' is not recommended and 
136 will force latin1 encoding.
138 The "Initial User" is the username of the first user, which is what they will
139 use to login.  Limit this to one word only.  Their default password will
140 always be "pass", without the quotes.
142 The "Initial User's Name" is the value to be used as their last name.  This
143 information may be changed in the user administration page.
145 The "Initial Group" is the first group, basically name of the practice, that
146 will be created.  A user may belong to multiple groups, which again, can be
147 altered on the user administration page. It is suggested that no more than
148 one group per office be used.
150 The "Absolute Path" is the full absolute directory path to openemr.  The
151 default value is automatically created, so this should not need to be
152 modified.  Note that it needs to end without a trailing slash.  To avoid
153 confusion, either forward or backward slashes can be used.
155 The "Relative HTML Path" is the relative html path to openemr, ie. what you
156 would type into the web browser after the server address to get to OpenEMR.
157 For example, if you type "http://127.0.0.1/clinic/openemr/"  to load OpenEMR,
158 set this to "/clinic/openemr" without the trailing slash.  To avoid
159 confusion, either forward or backward slashes can be used.
161 Step 3 is where setup will configure OpenEMR.  It will first create the database
162 and connect to it to create the initial tables.  It will then write the mysql
163 database configuration to a file.  It will then write the webserver root
164 directory to the /openemr/interface/globals.php file.  Should anything fail
165 during step 3, you may have to remove the existing database or tables before
166 you can try again. If no errors occur, you will see a "Continue" button at the bottom.
168 Step 4 will install and configure the embedded phpGACL access controls.  It
169 will first write configuration settings to files.  It will then configure the
170 database.  It will then give the "Initial User" administrator access.
171 Should anything fail during step 4, you may have to remove the existing database
172 or tables before you can try again. If no errors occur, you will see a
173 "Continue" button at the bottom.
175 Step 5 gives instructions on configuring the PHP.  We suggest you print these
176 instructions for future reference.  Instructions are given to edit the php.ini
177 configuration file.  If possible, the location of your php.ini file
178 will be displayed in green.  If your php.ini file location is not displayed,
179 then you will need to search for it.  The location of the php.ini file is dependent
180 on the operating system.  In linux, php.ini is generally found in the /etc/
181 directory.  In windows, the XAMPP 1.7.0 package places the php.ini file in
182 the xampp\apache\bin\ directory.  To ensure proper functioning of OpenEMR
183 you must make sure that settings in the php.ini file include 
184 "short_open_tag = On", "display_errors = Off", "register_globals = Off",
185 "magic_quotes_gpc = On", "max_execution_time" set to at least 60, 
186 "max_input_time" set to at least 90 , and "memory_limit" set to at least
187 "128M".  In order to take full advantage of the patient documents capability
188 you must make sure that settings in php.ini file include "file_uploads = On",
189 that "upload_max_filesize" is appropriate for your use and that
190 "upload_tmp_dir" is set to a correct value that will work on your system.
192 Step 6 gives instructions on configuring the Apache web server.  We suggest
193 you print these instructions for future reference. Instructions are given to
194 secure the "openemrwebroot/documents", "openemrwebroot/edi" and
195 "openemrwebroot/era" directories, which contain patient information. This can
196 be done be either placing pertinent .htaccess fiels in these directories
197 or by editing the apache configuration file.  The location of the apache
198 configuration file is dependent on the operating system.  In linux, you can
199 type 'httpd -V' on the commandline; the location to the configuration file
200 will be the HTTPD_ROOT variable plus the SERVER_CONFIG_FILE variable.
201 In windows, the XAMPP 1.7.0 package places the configuration file at
202 xampp\apache\conf\httpd.conf.  To secure the /documents, /edi and /era
203 directories you can paste following to the end of the apache configuration
204 file (ensure you put full path to directories):
205 <Directory "openemrwebroot/documents">
206 order deny,allow
207 Deny from all
208 </Directory>
209 <Directory "openemrwebroot/edi">
210 order deny,allow
211 Deny from all
212 </Directory>
213 <Directory "openemrwebroot/era">
214 order deny,allow
215 Deny from all
216 </Directory>
218 The final screen includes some additional instructions and important
219 information. We suggest you print these instructions for future reference.
221 Once the system has been configured properly, you may login.  Connect to the
222 webserver where the files are stored with your web browser.  Login to the system
223 using the username that you picked (default 'admin' without quotes), and the
224 password 'pass', without the quotes.  From there, select the "Administration"
225 option, and customize the system to your needs.  Add users and groups as is
226 needed. For information on using OpenEMR, consult the User Documentation located
227 in the Documentation folder, the wiki at http://www.oemr.org, and the forums
228 at http://sourceforge.net/projects/openemr.
230 Reading openemr/includes/config.php and openemr/interface/globals.php is a
231 good idea. These files contain many options to choose from including themes.
233 To create custom encounter forms, see the files
235   openemr/Documentation/3rd Party Form API.txt
236   openemr/interface/forms/OpenEMR_form_example-rev2.tar.gz
238 and read the included documentation. Many forms exist in contrib/forms as well
239 as in interface/forms and may be used as examples.
241 Other configuration settings are stored under includes/config.php.
242 Everything should work out of the installation without touching those, but if 
243 you want fax, sql-ledger, and/or Freeb integration you will need to adjust some
244 parameters in that file.
246 General-purpose fax support requires customization of interface/globals.php
247 and custom/faxcover.txt; it also requires the following utilities:
249 * faxstat and sendfax from the HylaFAX client package
250 * mogrify from the ImageMagick package
251 * tiff2pdf, tiffcp and tiffsplit from the libtiff-tools package
252 * enscript
255 IV. Setting Up Access Control
257 Since OpenEMR version 2.9.0.3, phpGACL access controls are installed and
258 configured automatically during OpenEMR setup.  It can be administered
259 within OpenEMR in the admin->acl menu.  This is very powerful
260 access control software.  To learn more about phpGACL
261 (see http://phpgacl.sourceforge.net/), recommend reading the phpGACL manual,
262 the /openemr/Documentation/README.phpgacl file, and the online wiki at
263 www.oemr.org. Also recommend reading the comments in /openemr/library/acl.inc.
265 V. Upgrading
267 Be sure to back up your OpenEMR installation and database before upgrading!
269 Upgrading OpenEMR is currently done by replacing the old openemr directory with
270 a newer version. Copy the following file from the old version to the new
271 version:
273   openemr/library/sqlconf.php
275 Ensure you copy your settings from the following old openemr
276 files to the new configuration files (we do not recommend simply
277 copying the entire files):
279   openemr/interface/globals.php 
280   openemr/includes/config.php (if you have modified it)
282 The following directories should be copied from the old version to the
283 new version:
285   openemr\documents 
286   openemr\era 
287   openemr\edi 
288   openemr\custom\letter_templates
290 If there are other files that you have customized, then you will also need
291 to treat those carefully.
293 To upgrade the database, run the sql_upgrade.php script from your web
294 browser (for example http://openemr.location/sql_upgrade.php).  It will
295 prompt you to select the old release number, and will display the SQL
296 commands issued as the upgrade occurs.
298 Next, if you are converting from SQL-Ledger to OpenEMR's internal A/R
299 management (normally you should), run the sl_convert.php script
300 (e.g. http://openemr.location/sl_convert.php).  Note this script may
301 run for several minutes or longer.
303 If phpGACL is installed (automatically installed since OpenEMR version 2.9.0.3),
304 then you should upgrade your Access Controls by running the acl_upgrade.php
305 program using your web browser (e.g. http://openemr.location/acl_upgrade.php).