Updated MU wordage
[openemr.git] / INSTALL
blob469689b3943dda3d6d91c971fede913900d47da9
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 NOTE: Most recent documentation can be found on the online documentation at
19 http://www.open-emr.org .
21 accounting    - Contains information and scripts to support SQL-Ledger
22 contrib       - Contains many user-contributed encounter forms and utilities
23 custom        - Contains scripts and other text files commonly customized
24 Documentation - Contains useful documentation
25 interface     - Contains User Interface scripts and configuration
26 library       - Contains scripts commonly included in other scripts
27 sql           - Contains initial database images
28 gacl          - Contains embedded php-GACL (access controls)
30 II. Unpacking
32 NOTE: Most recent documentation can be found on the online documention at
33 http://www.open-emr.org .
35 The OpenEMR release archive should be named as follows:
37 openemr-<version>.tar.gz  -or-  openemr-<version>.zip
39 To extract the archive, use either of the following commands from the command line:
41 bash# tar -pxvzf openemr-<version>-release.tar.gz
42 bash# unzip openemr-<version>-release.tar.gz
44 Be sure to use the -p flag when using tar, as certain permissions must be preserved.
46 OpenEMR will be extracted into a directory named openemr.
48 Alternatively a Debian package may be available as a file named
49 openemr-<version>.deb.  This may work with some other Debian-like
50 Linux distributions such as Ubuntu.
52 III. Setup
54 NOTE: Most recent documentation can be found on the online documentation at
55 http://www.open-emr.org .
57 To run OpenEMR, MySQL and Apache or another PHP-capable webserver must be configured.
58 To download Apache, visit www.apache.org
59 For information on how to install MySQL, visit www.mysql.com
60 PHP may be downloaded from www.php.net
62 OpenEMR requires a number of webserver and PHP features which may not be
63 enabled on your system.  These include:
65 - PHP Index support (ensure that index.php is in your Index path in httpd.conf)
66 - Session variables
67 - PHP libcurl support (optional for operation, mandatory for billing)
69 Copy the OpenEMR folder into the root folder of the webserver. On Mandrake
70 Linux, for example, use the command:
72   bash# mv openemr /var/www/html/
74 Make sure the webserver is running, and point a web-browser to setup.php located
75 within the openemr web folder.  If you installed OpenEMR in the root web
76 directory, the URL would read: http://localhost/openemr/setup.php.
77 The setup script will step you through the configuration of the OpenEMR.
79 The first screen of the setup script will ensure that the webserver user
80 (in linux, often is "apache", "www-data", or "nobody") has write privileges on
81 certain files and directories. The files include
82 openemr/sites/default/sqlconf.php and
83 openemr/interface/modules/zend_modules/config/application.config.php.
84 In linux, these can be set by "chmod a+w filename"
85 command to grant global write permissions to the file. The directories include
86 openemr/gacl/admin/templates_c, openemr/sites/default/edi,
87 openemr/sites/default/era, openemr/sites/default/documents, openemr/library/freeb,
88 openemr/custom/letter_templates, 
89 openemr/interface/main/calendar/modules/PostCalendar/pntemplates/compiled, and 
90 openemr/interface/main/calendar/modules/PostCalendar/pntemplates/cache.  In
91 linux, if the webserver user name is "apache", then the command
92 "chown -R apache:apache directory_name" will grant global write permissions
93 to the directories, and we recommend making these changes permanent.
94 Should the page display errors related to file or directory writing priviledges you 
95 may click the 'Check Again' button to try again (after fixing permissions).
97 In step 1, you need to tell setup whether it needs to create the database on
98 its own, or if you have already created the database.  MySQL root priveleges will
99 be required to create a database.
101 In step 2, you will be presented with a number of fields which specify the MySQL
102 server details and the openemr directory paths.
104 The "Server Host" field specifies the location of the MySQL server.  If you
105 run MySQL and Apache/PHP on the same server, then leave this as 'localhost'. 
106 If MySQL and Apache/PHP are on separate servers, then enter the IP address
107 (or host name) of the server running MySQL.
109 The "Server Port" field specifies the port to use when connecting to the MySQL
110 server over TCP/IP.  This should be left as 3306 unless you changed it in your
111 MySQL configuration.
113 The "Database Name" field is the database where OpenEMR will reside.  If you
114 selected to have the database created for you, this database will be created,
115 along with the user specified in "Login Name".  If this database exists, setup
116 will not be able to create it, and will return an error.  If you selected that
117 you have already created the database, then setup will use the information you
118 provide to connect to the MySQL server.  Note that setup will not accept a
119 password that is not at least one (1) character in length.
121 The "Login Name" field is the MySQL user that will access the OpenEMR database.
122 If you selected to have the database created for you, this user will be
123 created.  If you selected that you have already created the database, 
124 then setup will use the information you provide to connect to the MySQL server.
126 The "Password" field is the password of the user entered into the above
127 "Login Name" field.  If you selected to have the database created for you,
128 this user and password  will be created.  If you selected that you have already
129 created the database, then setup will use the information you provide to connect
130 to the MySQL server.
132 The "Name for Root Account" field will only appear if setup is creating the
133 database.  It is the name of the MySQL root account. For localhost, it is
134 usually ok to leave it 'root'.
136 The "Root Pass" field will likewise only appear if setup is creating the
137 database.  It is the password of your existing root user, and is used to acquire
138 the privileges to create the new database and user.
140 The "User Hostname" field will also only appear if setup is creating the 
141 database.  It is the hostname of the Apache/PHP server from which the user
142 ("Login Name") is permitted to connect to the MySQL database.  If you are setting
143 up MySQL and Apache/PHP on the same computer, then you can use 'localhost'.  
145 The "UTF-8 Collation" field is the collation setting for mysql. If the language
146 you are planning to use in OpenEMR is in the menu, then you can select it.
147 Otherwise, just select 'General'. Choosing 'None' is not recommended and 
148 will force latin1 encoding.
150 The "Initial User" is the username of the first user, which is what they will
151 use to login.  Limit this to one word only.
153 The "Initial User Password" is the password of the user entered into the above
154 "Initial User" field.
156 The "Initial User's First Name" is the value to be used as their first name.  This
157 information may be changed in the user administration page.
159 The "Initial User's Last Name" is the value to be used as their last name.  This
160 information may be changed in the user administration page.
162 The "Initial Group" is the first group, basically name of the practice, that
163 will be created.  A user may belong to multiple groups, which again, can be
164 altered on the user administration page. It is suggested that no more than
165 one group per office be used.
167 Step 3 is where setup will configure OpenEMR.  It will first create the database
168 and connect to it to create the initial tables.  It will then write the mysql
169 database configuration to the openemr/sites/default/sqlconf.php file.
170 Should anything fail during step 3, you may have to remove the existing database or
171 tables before you can try again. If no errors occur, you will see a "Continue"
172 button at the bottom.
174 Step 4 will install and configure the embedded phpGACL access controls.  It
175 will first write configuration settings to files.  It will then configure the
176 database.  It will then give the "Initial User" administrator access.
177 Should anything fail during step 4, you may have to remove the existing database
178 or tables before you can try again. If no errors occur, you will see a
179 "Continue" button at the bottom.
181 Step 5 gives instructions on configuring the PHP.  We suggest you print these
182 instructions for future reference.  Instructions are given to edit the php.ini
183 configuration file.  If possible, the location of your php.ini file
184 will be displayed in green.  If your php.ini file location is not displayed,
185 then you will need to search for it.  The location of the php.ini file is dependent
186 on the operating system.  In linux, php.ini is generally found in the /etc/
187 directory.  In windows, the XAMPP 1.7.0 package places the php.ini file in
188 the xampp\apache\bin\ directory.  To ensure proper functioning of OpenEMR
189 you must make sure that settings in the php.ini file include 
190 "short_open_tag = On", "display_errors = Off", "register_globals = Off",
191 "max_execution_time" set to at least 60, 
192 "max_input_time" set to at least 90 , "post_max_size" set to at least 30M,
193 and "memory_limit" set to at least "128M".  In order to take full advantage
194 of the patient documents capability you must make sure that settings in
195 php.ini file include "file_uploads = On", that "upload_max_filesize" is
196 appropriate for your use and that "upload_tmp_dir" is set to a correct
197 value that will work on your system.
199 Step 6 gives instructions on configuring the Apache web server.  We suggest
200 you print these instructions for future reference. Instructions are given to
201 secure the "openemrwebroot/sites/*/documents",
202 "openemrwebroot/sites/*/edi" and "openemrwebroot/sites/*/era"
203 directories, which contain patient information. This can
204 be done be either placing pertinent .htaccess files in these directories
205 or by editing the apache configuration file.  The location of the apache
206 configuration file is dependent on the operating system.  In linux, you can
207 type 'httpd -V' on the commandline; the location to the configuration file
208 will be the HTTPD_ROOT variable plus the SERVER_CONFIG_FILE variable.
209 In windows, the XAMPP 1.7.0 package places the configuration file at
210 xampp\apache\conf\httpd.conf. To configure Zend and to secure the /documents,
211 /edi and /era directories you can paste following to the end of the apache
212 configuration file (ensure you put full path to directories):
213 <Directory "openemrwebroot">
214 AllowOverride FileInfo
215 </Directory>
216 <Directory "openemrwebroot/sites">
217 AllowOverride None
218 </Directory>
219 <Directory "openemrwebroot/sites/*/documents">
220 order deny,allow
221 Deny from all
222 </Directory>
223 <Directory "openemrwebroot/sites/*/edi">
224 order deny,allow
225 Deny from all
226 </Directory>
227 <Directory "openemrwebroot/sites/*/era">
228 order deny,allow
229 Deny from all
230 </Directory>
232 The final screen includes some additional instructions and important
233 information. We suggest you print these instructions for future reference.
235 Once the system has been configured properly, you may login.  Connect to the
236 webserver where the files are stored with your web browser.  Login to the system
237 using the username that you picked (default 'admin' without quotes), and the
238 password.  From there, select the "Administration"
239 option, and customize the system to your needs.  Add users and groups as is
240 needed. For information on using OpenEMR, consult the User Documentation located
241 in the Documentation folder, the documentation at http://www.open-emr.org, and
242 the forums at http://sourceforge.net/projects/openemr.
244 Reading openemr/sites/default/config.php is a good idea. This file contains some
245 options to choose from including themes.
247 To create custom encounter forms, see the files
249   openemr/Documentation/3rd Party Form API.txt
250   openemr/interface/forms/OpenEMR_form_example-rev2.tar.gz
252 and read the included documentation and online documentation at www.openemr.org.
253 Many forms exist in contrib/forms as well as in interface/forms and may be used
254 as examples.
256 Other configuration settings are stored under includes/config.php.
257 Everything should work out of the installation without touching those, but if 
258 you want fax integration you will need to adjust some parameters in that file.
260 General-purpose fax support requires customization within OpenEMR at
261 Administration->Globals and custom/faxcover.txt; it also requires
262 the following utilities:
264 * faxstat and sendfax from the HylaFAX client package
265 * mogrify from the ImageMagick package
266 * tiff2pdf, tiffcp and tiffsplit from the libtiff-tools package
267 * enscript
270 IV. Setting Up Access Control
272 Since OpenEMR version 2.9.0.3, phpGACL access controls are installed and
273 configured automatically during OpenEMR setup.  It can be administered
274 within OpenEMR in the admin->acl menu.  This is very powerful
275 access control software.  To learn more about phpGACL
276 (see http://phpgacl.sourceforge.net/), recommend reading the phpGACL manual,
277 the /openemr/Documentation/README.phpgacl file, and the online documentation at
278 http://www.open-emr.org . Also recommend reading the comments in
279 /openemr/library/acl.inc.
281 V. Upgrading
283 NOTE: Most recent documentation can be found on the online documentation at
284 http://www.open-emr.org .
286 Be sure to back up your OpenEMR installation and database before upgrading!
288 Upgrading OpenEMR is currently done by replacing the old openemr directory with
289 a newer version. And, ensure you copy your settings from the following old openemr
290 files to the new configuration files (we do not recommend simply
291 copying the entire files):
293   openemr/sites/default/sqlconf.php
294     --Also in this sqlconf.php file, set the $config variable (found near bottom
295       of file within bunch of slashes) to 1 ($config = 1;)
296   openemr/sites/default/config.php
298 The following directories should be copied from the old version to the
299 new version:
301   openemr/sites/default/documents 
302   openemr/sites/default/era 
303   openemr/sites/default/edi 
304   openemr/sites/default/letter_templates
306 If there are other files that you have customized, then you will also need
307 to treat those carefully.
309 To upgrade the database, run the sql_upgrade.php script from your web
310 browser (for example http://openemr.location/sql_upgrade.php).  It will
311 prompt you to select the old release number, and will display the SQL
312 commands issued as the upgrade occurs.