| 1 | | Please read install.pdf for 0.9 installation and upgrading instructions. |
|---|
| | 1 | For the latest version of these instructions, please check the wiki at: |
|---|
| | 2 | http://elgg.org/mod/mediawiki/wiki/index.php/Installation_guide |
|---|
| | 3 | |
|---|
| | 4 | 1. Before You Begin |
|---|
| | 5 | 1.1 Requirements |
|---|
| | 6 | Elgg currently requires the Apache web server with mod_rewrite installed and the ability to send emails, plus PHP 4.3+ and MySQL 4.1+ (Postgres can also be used, though plugin support is limited). |
|---|
| | 7 | Your Apache configuration must have AllowOverride set to All for the directory where Elgg is installed. |
|---|
| | 8 | You must have the GD library installed. |
|---|
| | 9 | For internationalization, you must have gettext support installed on your server and compiled into PHP. If this is not found, Elgg will revert to English. |
|---|
| | 10 | You must have a database on the database server ready for use by Elgg. A mySQL database and user can be created in a number of ways. If you are unfamiliar with setting up mySQL, this tutorial (based on cpanel hosting from a popular hosting company, but applicable to many hosting services) may help: |
|---|
| | 11 | http://pluto3.lunarpages.com/tutorials/tutorial_files/cpanel_xv2_mysql.htm |
|---|
| | 12 | During the setup process, be sure to write down your database name, database user name, and password. They will be needed during the elgg setup. |
|---|
| | 13 | If you have any problems installing, please consider joining http://elgg.org/ and viewing the installation support community there. |
|---|
| | 14 | |
|---|
| | 15 | Note that if URLs like /username/weblog/ are not working for you, this is an issue with mod_rewrite, and is an error in your Apache installation rather than Elgg. A mod_rewrite primer (written by a third party) is available here: |
|---|
| | 16 | http://www.kuro5hin.org/story/2003/7/31/2335/08552#setup |
|---|
| | 17 | |
|---|
| | 18 | |
|---|
| | 19 | 1.2 Recommendations |
|---|
| | 20 | |
|---|
| | 21 | For this release, it is recommended that MySQL has cacheing enabled. Please see the MySQL documentation for instructions, or ask your system administrator. |
|---|
| | 22 | |
|---|
| | 23 | 1.3 Time estimate |
|---|
| | 24 | |
|---|
| | 25 | Assuming you have satisfied the requirements in 1.1, the installation should not take longer than 20 minutes. This may vary depending on the connection speed to your web server. |
|---|
| | 26 | 1.4 Upgrading |
|---|
| | 27 | Elgg 0.9 marks some changes in the file structure and initial setup. For a first time installation all should work well via the installer which will guide you through the process. Users upgrading their installation from 0.8.* should take care since the main configuration file (config.php) and .htaccess will get overwritten. Make sure to create appropriate backups. |
|---|
| | 28 | Steps: |
|---|
| | 29 | Backup your existing Elgg home directory |
|---|
| | 30 | Backup your Elgg mySQL database |
|---|
| | 31 | Remove all your existing Elgg files. If you have installed Elgg in a sub-directory (e.g. /elgg/) then this can be as simple as renaming /elgg/ to /elgg_old/. If elgg has been installed to the root of your web server, consider creating an /elgg_old/ directory and moving all the files from your root folder into it. This step is important as it ensures that your directory is clean for Elgg and that no legacy files from Elgg 0.8 are left behind |
|---|
| | 32 | Install Elgg as though it were a new installation (see steps below). Use the same database and username/password that your previous version of Elgg used (you can check your old config.php which you just moved into /elgg_old/ to be sure) |
|---|
| | 33 | Once the install is complete (and you get to the front page of your new Elgg install), you still have some steps to complete: |
|---|
| | 34 | It is likely that if you are upgrading from an Elgg version 0.8 or less, your dataroot will need to be changed to point to where you set it up in your previous version. To do this, open your old config.php file (/elgg_old/config.php) and find out the path to your dataroot. Copy this setting and enter it into your new config.php file |
|---|
| | 35 | (e.g. $CFG->dataroot = '/home/yourdomain/user_data/';) |
|---|
| | 36 | |
|---|
| | 37 | Configuration options for dataroot and other settings can also be managed via the Administrative interface (which has moved in Elgg 0.9 from being at /_elggadmin to where it is now login as news user and find the Administration link, then choose Site Administration) |
|---|
| | 38 | |
|---|
| | 39 | Reinstalling plugins: If you had installed 3rd party plugins in your previous version of Elgg, they will have to be reinstalled/configured. As structures have changed since v0.8, it is highly recommended that you check for the latest versions of any plugins you use and consult with the plugin author to be certain they have been updated for 0.9+. |
|---|
| | 40 | Any customization you made to .htaccess (e.g. to override custom php settings, or setup rewrite rules for plugins will also have to be redone) |
|---|
| | 41 | |
|---|
| | 42 | |
|---|
| | 43 | 2. INSTALLING FILES |
|---|
| | 44 | WARNING IF YOU ARE UPGRADING AN EXISTING ELGG INSTALLATION, YOU SHOULD FOLLOW THE UPGRADING INSTRUCTIONS (1.4) |
|---|
| | 45 | TO ENSURE YOU DO NOT LOOSE DATA. |
|---|
| | 46 | |
|---|
| | 47 | |
|---|
| | 48 | 2.1 Deploy Elgg framework |
|---|
| | 49 | Move all files from the distribution package to your web server root directory. This is normally called 'public_html', 'httpdocs' or 'www'. If you like, you can place Elgg in a subdirectory of this; commonly, people will place it in one called 'elgg'. |
|---|
| | 50 | 2.2 Set Permissions |
|---|
| | 51 | In order to continue your setup, you must first adjust permissions of the file config.php and the 'data' folder to allow the web server to write information from the visual installer. |
|---|
| | 52 | Begin with your 'data' directory and assign the correct privileges. To do this you may be able to right click on the folder and set the "CHMOD" value, or you may have to use your command line terminal, navigate to the folder, and type: |
|---|
| | 53 | chmod 777 data |
|---|
| | 54 | |
|---|
| | 55 | |
|---|
| | 56 | Next will be adjusting the permissions of the main configuration file 'config.php': |
|---|
| | 57 | chmod 666 config.php |
|---|
| | 58 | |
|---|
| | 59 | A beginners guide to CHMOD is available here: |
|---|
| | 60 | http://www.stadtaus.com/en/tutorials/chmod-ftp-file-permissions.php |
|---|
| | 61 | |
|---|
| | 62 | If you have not yet completed this step, the visual installer will prompt you to correct it before going on. |
|---|
| | 63 | |
|---|
| | 64 | |
|---|
| | 65 | |
|---|
| | 66 | 3. SETTING UP ELGG |
|---|
| | 67 | 3.1 Configuring the Elgg framework |
|---|
| | 68 | The main configuration Ellg is stored in a file called config.php. Elgg now includes a Visual installer to help you setup this config file quickly and easily. |
|---|
| | 69 | To begin, navigate with your browser to where people will access your site (e.g. http://www.mysite.com/elgg/). You will be greeted by a welcome message telling you that some additional steps are required. This page will let you edit the required settings for the Elgg framework. |
|---|
| | 70 | Take time to read each requested item carefully, as an error in any field could create difficulty with your site. |
|---|
| | 71 | When you are finished, click save (make sure you wrote down all the username/password information!). The installer will try to save the settings to config.php (if it cant, it will instruct you on what to do). |
|---|
| | 72 | Typical Settings |
|---|
| | 73 | |
|---|
| | 74 | |
|---|
| | 75 | A series of prompts may be displayed (indicating various sub-components were setup successfully). |
|---|
| | 76 | |
|---|
| | 77 | Congratulations. You should now be able to visit your Elgg site |
|---|
| | 78 | |
|---|
| | 79 | |
|---|
| | 80 | |
|---|
| | 81 | 3.3 Customize your default homepage and other settings |
|---|
| | 82 | Once you've completed the visual installer, you can complete your installation via the 'Administration' link and choose the 'Site administration' option. |
|---|
| | 83 | |
|---|
| | 84 | 3.4 Log in |
|---|
| | 85 | By default, the first user in your Elgg instance is named News. You should now be ready to login (username: news, password is what you set it to in the visual installer). You should log in and change this as soon as possible. All new users will automatically list the news account as a friend, so you should not delete it. This user owns all the public custom templates. |
|---|
| | 86 | The news account comes with full administrator access, whether you've upgraded or installed fresh. To change this (we recommend that you do as a matter of urgency for security reasons), create a second account, and give that account administrator privileges using the administrator panel. |
|---|
| | 87 | |
|---|
| | 88 | 3.5 Elgg in a subdirectory and 404 errors |
|---|
| | 89 | If you are running Elgg in a subdirectory of your web site, and when browsing around it pages seem to be missing, you may also need to edit the .htaccess file. Below the "RewriteEngine on" line, add a line: |
|---|
| | 90 | RewriteBase /subdirectory/ |
|---|
| | 91 | changing subdirectory to the location of Elgg relative to your overall web |
|---|
| | 92 | For example, if your site is http://example.com/ and Elgg is in http://example.com/sites/elgg/ try adding the line: RewriteBase /sites/elgg/ |
|---|
| | 93 | If you're not running Elgg in a subdirectory on your site, but still getting lots of 404 errors beyond the front page, you could instead try: |
|---|
| | 94 | RewriteBase / |
|---|
| | 95 | 3.6 Tell us about it! |
|---|
| | 96 | Because Elgg is free and open source, we often don't hear about new installations. You don't have to, but we'd love it if you'd tell us what you're doing with it. Consider joining the community of Elgg users at http://elgg.org and sharing your experiences. |
|---|
| | 97 | |
|---|
| | 98 | 4. FURTHER CUSTOMISATION AND DEVELOPMENTS |
|---|
| | 99 | Please keep an eye on http://elgg.org/ for forthcoming developments within Elgg, including documentation on how to alter your default templates and writing new functionality into the system. |
|---|
| | 100 | Elgg has a rich API for developing enhancements and a strong community of users that contribute to its development. Numerous plugins are available to extend and refine your Elgg installation. To find out what plugins already exist, or to get involved with the development community (coders, designers, and documenters are all welcome), head over to http://elgg.org and find out how you can get involved. |
|---|
| | 101 | |
|---|
