INSTALL

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