INSTALL

   1 Elgg version 0.31 installation instructions
   2
   3 Ben Werdmuller <ben@elgg.net>
   4 9th December, 2005
   5
   6
   7 1. BEFORE YOU BEGIN
   8
   9 1.1 Requirements
  10
  11 Please read LICENSE.
  12
  13 Elgg currently requires the Apache web server with mod_rewrite
  14 installed and the ability to send emails, plus PHP 4.3+ and MySQL
  15 3.23+.  It has currently been tested on Apache installations running
  16 Red Hat Linux and Microsoft Windows XP.
  17
  18 In your Apache configuration, you must have AllowOverride set to
  19 All for the directory where Elgg is installed.
  20
  21 Elgg prefers to be installed on the root of a domain - for example,
  22 at http://elgg.net/, as opposed to http://elgg.net/subdirectory/.
  23 However, it has now been tested to work in subdirectories, although
  24 this remains experimental until the next release.
  25
  26 You must have a database on the MySQL server ready for use by Elgg.
  27
  28 You must have the GD library installed.
  29
  30 For internationalisation, you must have gettext support installed
  31 on your server and compiled into PHP.  If this is not found, Elgg
  32 will revert to English.
  33
  34 If you have any problems installing, please consider joining
  35 http://elgg.net/ and joining the Elgg Installation Support
  36 community at http://elgg.net/support/ .
  37
  38
  39 1.2 Recommendations
  40
  41 For this release, it is recommended that MySQL has cacheing enabled.
  42 Please see the MySQL documentation for instructions, or ask your
  43 system administrator.
  44
  45
  46 1.3 Time estimate
  47
  48 Assuming you have satisfied the requirements in 1.1, the installation
  49 should not take longer than 20 minutes. This may vary depending on
  50 the connection speed to your web server.
  51
  52
  53
  54 2. INSTALLING FILES
  55
  56
  57 2.1 Deploy Elgg framework
  58
  59 Move all files aside from README, LICENSE, INSTALL and the
  60 "distribution" directory from the distribution package to your web
  61 server directory.  Files in the root of the distribution must be in
  62 the root of your web server account.
  63
  64 ENSURE YOU HAVE INCLUDED .htaccess files - on Linux and Unix systems
  65 (including Mac OS X) you
  66
  67 IF YOU ARE UPGRADING, you may wish to retain your existing
  68 includes.php file.
  69
  70
  71 2.1 Set permissions on special directories
  72
  73 Some directories need to be written to during Elgg's normal operation
  74 - specifically the directory for uploaded files, and the directory
  75 for uploaded icons.
  76
  77 From your root directory, navigate to /_icons.  On Linux / Unix, you
  78 must change the access privileges for /_icons/data to 777 or
  79 equivalent.  To do this you may be able to right click on the folder
  80 and set the "CHMOD" value, or you may have to use your command line
  81 terminal, navigate to the _icons folder, and type:
  82
  83         chmod 777 data
  84
  85 Repeat this process for /_files/data and /_files/cache.
  86
  87
  88 3. SETTING UP THE DATABASE
  89
  90 If you are upgrading, please skip to 3.4.
  91
  92 3.1 Open database schema
  93
  94 There is a database schema supplied in the /distribution/database
  95 folder.  You must install this into the database you have set aside
  96 for Elgg.
  97
  98 If you are running phpMyAdmin, a third-party tool for easily
  99 maintaining MySQL databases, go to 3.2; otherwise go to 3.3.
 100
 101
 102 3.2 Setting up the database with phpMyAdmin
 103
 104 In phpMyAdmin, click on the database you wish to use for Elgg on the
 105 left hand side of the screen.  Click on the "SQL" tab at the top of
 106 the screen, and on the page that turns up, click "Browse" to pick a
 107 textfile to import.  Navigate to /distribution/database in the
 108 distribution package and select elgg.sql.  Click "Go".
 109
 110
 111 3.3 Setting up the database with command line MySQL
 112
 113 Using your command line terminal, navigate to /distribution/database
 114 in the distribution package. Type the following:
 115
 116         mysql -u [username] -p [password] [databasename] < elgg.sql
 117
 118 Where [username] and [password] are your MySQL access details and
 119 [databasename] is the name of the database you have set aside for
 120 Elgg.
 121
 122 Once you have done this, you should delete the /distribution
 123 directory.
 124
 125 3.4 Upgrading
 126
 127 If you are upgrading from 0.301, you don't need to perform any
 128 SQL upgrade steps.
 129
 130 Otherwise, perform the above steps but with the upgrade.sql file
 131 found in /distribution/database.
 132
 133 NB: The navigation system has changed severely since the previous
 134 version of Elgg. As a result, existing templates WILL NOT WORK.
 135 If you would like to keep your existing templates, you should back
 136 up the 'templates' and 'template_elements' tables in your database.
 137 You can then change templates over using the instructions in
 138 /THEMECHANGE.
 139
 140
 141
 142 4. SETTING UP ELGG
 143
 144
 145 4.1 Edit includes.php
 146
 147 Load "includes.php".  There are eight variables that must be
 148 set at the top of the file - all of them are important, and they are
 149 clearly described within the file.  Each of them is of the form:
 150
 151         define("name","value");
 152
 153 You must enter your values within the second set of quotation marks.
 154 To include a quotation mark within a value (e.g. if you wanted
 155 My University's "Elgg" Trial to be your site title), prefix it with
 156 a backslash ("\").
 157
 158
 159 4.2 Customise your default homepage
 160
 161 We have included a basic default homepage, but you can alter index.php
 162 as you wish.  If you would like to alter the text but maintain the
 163 position within Elgg's flexible templating system, you will need to
 164 alter the file /content/mainindex/content_main_index.php.
 165
 166
 167 4.3 XML-RPC
 168
 169 Misja Hoebe has written an XML-RPC unit that requires the PEAR library.
 170 Please see units/rpc/README for more details. If you are sure you have
 171 all the prerequisites for this unit, uncomment the include XMLRPC line
 172 in the plugins section of includes.php.
 173
 174
 175 4.4 Log in
 176
 177 We have included a default user, "news". This user owns all the
 178 public custom templates. Its login name is "news" and its default
 179 password is "password"; you should log in and change this as soon
 180 as possible. All new users will automatically list the news account
 181 as a friend, so you should not delete it.
 182
 183 The news account comes with full administrator access, whether you've
 184 upgraded or installed fresh. To change this (we recommend that you do
 185 as a matter of urgency for security reasons), create a second account,
 186 and give that account administrator privileges using the administrator
 187 panel.
 188
 189
 190 4.5 Tell us about it!
 191
 192 Because Elgg is free and open source, we often don't hear about new
 193 installations. You don't have to, but we'd love it if you'd tell us
 194 what you're doing with it. You can reach us at system@elgg.net.
 195
 196
 197 5. FURTHER CUSTOMISATION AND DEVELOPMENTS
 198
 199 Please keep an eye on http://elgg.net/development/index.php for
 200 forthcoming developments within Elgg, including documentation on how
 201 to alter your default templates and writing new functionality into
 202 the system.