INSTALL

   1 Elgg version 0.8 installation instructions
   2
   3 Ben Werdmuller <ben@curverider.co.uk>
   4 5 July 2007
   5
   6
   7 1. BEFORE YOU BEGIN
   8
   9 1.1 Requirements
  10
  11 Please read LICENSE and README. If you're upgrading rather than making
  12 a fresh install, also read the UPGRADE file.
  13
  14 Elgg currently requires the Apache web server with mod_rewrite
  15 installed and the ability to send emails, plus PHP 4.3+ and MySQL
  16 4.1+ (Postgres can also be used).  It has currently been tested on
  17 Apache installations running Red Hat Linux and Microsoft Windows XP.
  18
  19 It is now possible to install Elgg on Microsoft IIS web server
  20 environments. See the separate IIS-INSTALL file for more details, but
  21 you need to follow the instructions below as normal.
  22
  23 In your Apache configuration, you must have AllowOverride set to
  24 All for the directory where Elgg is installed.
  25
  26 You must have a database on the database 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.org/ and viewing the installation support community there.
  36
  37 Note that if URLs like /username/weblog/ are not working for you, this
  38 is an issue with mod_rewrite, and is an error in your Apache installation
  39 rather than Elgg. A mod_rewrite primer (written by a third party) is
  40 available here:
  41
  42 http://www.kuro5hin.org/story/2003/7/31/2335/08552#setup
  43
  44
  45 1.2 Recommendations
  46
  47 For this release, it is recommended that MySQL has cacheing enabled.
  48 Please see the MySQL documentation for instructions, or ask your
  49 system administrator.
  50
  51
  52 1.3 Time estimate
  53
  54 Assuming you have satisfied the requirements in 1.1, the installation
  55 should not take longer than 20 minutes. This may vary depending on
  56 the connection speed to your web server.
  57
  58
  59
  60 2. INSTALLING FILES
  61
  62
  63 2.1 Deploy Elgg framework
  64
  65 Move all files from the distribution package to your web server root directory.
  66 This is normally called 'public_html', 'httpdocs' or 'www'. If you like, you
  67 can place Elgg in a subdirectory of this; commonly, people will place it in
  68 one called 'elgg'.
  69
  70 Rename htaccess-dist to .htaccess, and config-dist.php to config.php.
  71
  72 PLEASE NOTE: Elgg 0.8 contains integration with the Explode service at
  73 http://ex.plode.us/. From time to time, Elgg will ping Explode to let it know
  74 it exists. If you don't want this to happen, you must delete the folder at
  75 /mod/explodeping.
  76
  77
  78 2.2 Create data directory
  79
  80 The data directory needs to be written to during Elgg's normal
  81 operation to store uploaded files and so on.  This does not come with
  82 Elgg out of the box, and needs to be manually created. You can
  83 create it anywhere reachable by the Elgg installation scripts,
  84 although we recommend you place it outside of your web server root.
  85
  86 You must assign the correct privileges.  To do this you may be able to
  87 right click on the folder and set the "CHMOD" value, or you may have
  88 to use your command line terminal, navigate to the data folder, and
  89 type:
  90
  91     chmod 777 data
  92
  93 Where 'data' is the name of your data directory.
  94
  95
  96 2.3 Allow admin access to the templates
  97
  98 If you want to use the Elgg administration panel to change templates etc,
  99 you will also need to run the following command from the root of your Elgg
 100 installation:
 101
 102     chmod 777 mod/template/templates/Default_Template
 103
 104
 105 3. SETTING UP ELGG
 106
 107 NB: you can ignore everything from here on in if you want to use the
 108 visual installer. To do this, just call up the web directory you used
 109 to install Elgg, and follow the instructions on-screen. The direct
 110 URL for the installer is http://[your elgg install location]/_elggadmin.
 111
 112 3.1 Edit config.php
 113
 114 config.php does not exist out of the box.  You will need to copy
 115 config-dist.php to config.php and edit the configuration values there.
 116
 117 There are several variables that must be set at the top of the file -
 118 all of them are important, and they are clearly described within the
 119 file.  Each of them is of the form:
 120
 121     $CFG->data = 'value';
 122
 123 You must enter your values within the second set of quotation marks.
 124 To include a quotation mark within a value (e.g. if you wanted
 125 My University's "Elgg" Trial to be your site title), prefix it with
 126 a backslash ("\").
 127
 128
 129 3.2 Customise your default homepage and other settings
 130
 131 Once you've filled in config.php, you can visit http://yoursite/_elggadmin/,
 132 and log in using the main email address and news initial password. This will
 133 allow you to change various aspects of your site, including the default
 134 template and the site homepage.
 135
 136
 137 3.3 Optional plugins
 138
 139 Misja Hoebe has written an XML-RPC unit that requires the PEAR library.
 140 Please see units/rpc/README for more details. If you are sure you have
 141 all the prerequisites for this unit, uncomment the include XMLRPC line
 142 in the plugins section of includes.php.
 143
 144 We have also included an implementation of the TinyMCE editor. This
 145 is enabled by default. To disable it, comment out the TinyMCE line in
 146 the plugins section of includes.php.
 147
 148
 149 3.4 Log in
 150
 151 We have included a default user, "news". This user owns all the
 152 public custom templates. Its login name is "news" and its default
 153 password is "password"; you should log in and change this as soon
 154 as possible. All new users will automatically list the news account
 155 as a friend, so you should not delete it.
 156
 157 The news account comes with full administrator access, whether you've
 158 upgraded or installed fresh. To change this (we recommend that you do
 159 as a matter of urgency for security reasons), create a second account,
 160 and give that account administrator privileges using the administrator
 161 panel.
 162
 163
 164 3.5 Elgg in a subdirectory and 404 errors
 165
 166 If you are running Elgg in a subdirectory of your web site, and when browsing
 167 around it pages seem to be missing, you may also need to edit the .htaccess file.
 168 Below the "RewriteEngine on" line, add a line:
 169
 170 RewriteBase /subdirectory/
 171
 172 changing subdirectory to the location of Elgg relative to your overall web root.
 173
 174 For example, if your site is http://example.com/
 175               and Elgg is in http://example.com/sites/elgg/
 176 try adding the line:
 177
 178 RewriteBase /sites/elgg/
 179
 180 If you're not running Elgg in a subdirectory on your site, but still getting lots
 181 of 404 errors beyond the front page, you could instead try:
 182
 183 RewriteBase /
 184
 185
 186 3.6 Tell us about it!
 187
 188 Because Elgg is free and open source, we often don't hear about new
 189 installations. You don't have to, but we'd love it if you'd tell us
 190 what you're doing with it. You can reach us at info@curverider.co.uk,
 191 or give us a phone using the details in README.
 192
 193
 194 4. FURTHER CUSTOMISATION AND DEVELOPMENTS
 195
 196 Please keep an eye on http://elgg.org/ for forthcoming developments
 197 within Elgg, including documentation on how to alter your default
 198 templates and writing new functionality into the system.