Installation
From Habari Project
Habari's installation process is usually quick and painless, however as there are so many systems under which Habari can be installed, sometimes more help is needed. This page gives an overview of installation, followed by more detailed instructions.
Contents |
Overview
These are the basic steps required to install Habari. More detail can be found below.
- Download Habari to the directory on your web server where you want to run Habari.
- Create a database for Habari to store its data, and a user with appropriate privileges to access that database (not required if using SQLite).
- Point your browser at the directory that holds Habari. The installer will guide you through the installation process, including checking Habari's system requirements are met, checking that your database can be accessed, and writing configuration files.
Details
This section contains detailed instructions about all aspects of Habari installation.
Before You Install
Browser Requirements
Habari uses jQuery intensively. The admin interface will only work on applicable browsers.
Server Requirements
Below are the detailed requirements of what Habari needs to install and run. Habari's installer will check that all these requirements are met for you. Note that the required PHP modules listed here are enabled in a standard installation of PHP. You (or your host) would need to explicitly disable the extension to cause it not to be present.
- Supported Web Server
- Supported Database
- MySQL 4.1.x or greater
- SQLite
- PostgresSQL (currently not supported)
- PHP version 5.2 or above with the following modules enabled.
- PHP Data Objects (PDO) and the PDO driver for the database you wish to use
- SimpleXML
- GD
- Hash
- Iconv
- Mbstring
- Tokenizer
- JSON
- PCRE with Unicode support enabled
The easiest way to check if your system meets Habari's requirements without downloading Habari itself is to download the Habari Requirements Checker and upload it to your server. Then point your browser to http://<YOUR HOST>/requirements.php. This small file will test your server setup and let you know what requirements, if any, are not met. As mentioned, you can also simply try to install Habari. The install process will check your system and tell you if anything is missing.
Alternatively, you can get a list of the PHP modules installed by following these instructions. Create a file "/public_html/PHP_Info.php". Then, using a text editor, put in the following text. Then point your browser to http://<YOUR HOST>/PHP_Info.php. The list is long, so use the word search.
<html><head> <title>PHP Test</title> </head> <body> <?php phpinfo(-1) ?> </body></html>
To install Habari on Dreamhost you need to make sure that you have php5 selected when you are in the manage domains menu. If you are stuck there is a FAQ here.
Change Permissions
To enjoy the most convenient installation process, you can to make writable the folder where Habari will be installed. The Habari installation process will create a config.php file and, if you're installing on a web server that uses one, a .htaccess file for you automatically.
If you are using a GNU/Linux (or other UNIX-like) host, you may apply the following chmod to the root folder of your Habari installation:
chmod o+w .
That allows everyone to write to the Habari directory. Specifically, the web server will use this to create the files necessary for Habari's execution.
When the installation process completes, you may remove the "everyone" write permission with this:
chmod o-w .
Instructions for the paranoid
If the idea of giving everyone write access to your Habari directory gives you the willies, you can instead perform the following steps:
touch .htaccess touch config.php chmod o+w .htaccess chmod o+w config.php
This creates empty .htaccess and config.php files, and makes only these files world-writable. Habari will add the necessary bits to these files.
Upon completion, you may remove the world-writable permission with these commands:
chmod o-w .htaccess chmod o-w config.php
My .htaccess file wasn't written!
The Habari installation process will do its best not to clobber any existing .htaccess file that might exist.
If for some reason Habari cannot create the .htaccess file, it may present you the text of the .htaccess file so that you can save it yourself manually. If for some reason Habari doesn't create a file and doesn't produce one for your to copy and paste (this occasionally occurs when permissions aren't correct and the validity checks during installation are disabled) here is what the .htaccess file typically looks like:
### HABARI START
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteBase /
RewriteRule . index.php [PT]
RewriteRule ^(system/(classes|locale|schema|$)) index.php [PT]
### HABARI END
If you select SQLite for your database, you might also want to append this (also typically added by Habari automatically), which prevents people from downloading your database file:
### HABARI SQLITE START <Files "habari.db"> Order deny,allow deny from all </Files> ### HABARI SQLITE END
Activate PHP5
Some hosts may offer both PHP4 and PHP5, but execute files with the .php extension using the PHP4 by default. You can often change this behavior by adding the following single line in the .htaccess file found in the root folder of your Habari installation:
AddHandler application/x-httpd-php5 .php
Please read your host's FAQ as some hosts may require a different AddHandler.
Installing Habari
Step 1: Download and Extract
As Habari is still in development, no guarantees are made that these are fully stable versions, or that updating won't break the current database structure.
Developer Release
- Habari is still in development, however there is a developer release available for download.
SVN Checkout
In order to use SVN you will need SSH access to your server. Some hosts have it enabled by default, but others may only enable it upon request.
- Login to your web host.
ssh username@yourblog.com
Your host will then ask for your host password. Put it in and you are in.
- Check that Subversion is installed and running.
svn --version
- Change directory to the one you wish to install Habari in. Directory name may differ.
cd ~/public_html/habari/
- Checkout the source code.
svn checkout http://svn.habariproject.org/habari/trunk/htdocs .
- If you are not in the Habari directory, use the following command to checkout in a new directory called habari.
svn checkout http://svn.habariproject.org/habari/trunk/htdocs habari
Reference: Creating and Applying Patches for Subversion
Step 2: Preparing the Database
As mentioned, Habari requires you to have already created a database from one of the supported formats. If you are running on a professional hosting company (see Supported Hosts), chances are you either were provided with a database, or a web interface for creating a database. If that's the case, you can skip to the next step. Either way you will need:
- The name of the database,
- the database user with privileges to access the database, and
- the password for that database user.
Please note that by default some third party hosts add your user name prior to these items.
Step 3: Setting Filesystem Permissions
Before proceeding make sure the user running the webserver has write access to the user/files/ and user/cache/ directories . If you don't know the name of the webserver user try the following, the username should be the left section of the output. It is probably "apache" or "www-data".
ps -ef | grep apache
When you know the name of the user run the following commands to create the user/files folder and set the owner and permissions. Remember to change <webserver-username> to the correct username
cd ~/public_html/habari mkdir user/files chown <webserver-username> user/files chmod o+w user/files
Followed by this for the cache folder.
chown <webserver-username> user/cache chmod o+w user/cache
Step 4: Running the Installer
After checking out the files, and creating your database, you are ready to run the installer. Open your web browser and navigate to your install location, ie, http://example.com/habari. You should be prompted with an installer, requiring you to choose your database type, and the necessary information to complete installation.
If the installer is not working properly, the Common Questions page has some information that may help you troubleshoot the installer.
Database Host
99% of the time, this is going to be localhost, and should be the default value in the installer.
If this is not the case, your host should have provided you with the necessary information. For example, if your installation is to be hosted on Dreamhost, then this value will be mysql.yourDomain.com.
User Name
This is the user name for the database, not your domain's user name. If you created your database via the common C-Panel interface, remember this name is prefixed by the account, then the username, ie, user_dbusername.
Password
Again, this is the database user's password, not necessarily the account password.
Database Name
This is the name of the database you created for your installation. As with the user, it's possible the database name is prefixed with your domain username, ie, user_databasename.
Table Prefix
habari__ is the default, however if you are using multiple instances of Habari in the same database, or have your own naming conventions, you can change the prefix here.
Fill in the remaining data with the name of your blog, an admin user name and password, and a default email. Note that these can be changed later.
Click install, and if all goes well, you should be taken to the blog's home page. You can then log in with the admin name and password you used on the installer page, and start blogging!
If you had any problems, you can post to the Habari user group. Be sure to provide as many details as possible, including version of PHP, MySQL, and server config.
Advanced Installation
This procedure outlines a way to automate the installation process by predefining the config.php file.
Predefined Configuration
Depending on your DBMS of choice, MySQL or SQLite, copy <root>/system/schema/<dbms>/config.php to the root folder, where index.php is.
Modify this array definition, or similar, in the copied config.php file.
Config::set( 'db_connection', array(
'admin_username' => 'ernie',
'admin_pass1' => 'RubberDuck',
'admin_pass2' => 'RubberDuck',
'admin_email' => 'ernie@www.sesamestreetlive.com'
));
Valid Parameters
'db_user' => '',
'db_pass' => '',
'db_schema' => 'habari',
'connection_string' => '',
'table_prefix' => 'habari__',
'admin_username' => 'admin',
'admin_pass1' => '',
'admin_pass2' => '',
'blog_title' => 'I love Cookies',
'admin_email' => 'bert@www.sesamestreetlive.com',
NOTE: The admin_pass1 and admin_pass2 fields can take either plaintext or encrypted passwords. You may use our SSHA512 password encryption page to generate an encrypted password. The database password (if used) must be provided in plaintext.
These values will be extracted when or if index.php detects that there are DBMS tables present. In that case, the installer will not display the form but use these values instead.
This will allow a fully automated installation, without any prompts being displayed to the user (assuming the $db_connection array is properly constructed, too).
At the moment, it's a convenience for those who are constantly re-installing Habari and who don't want to waste a bunch of time keying in the same values over and over. It's also the basis of an automagic deployment tool for hosting providers.
Troubleshooting
See troubleshooting page for more details...
Special Instructions
Configuring on Arch Linux
A detailed howto is available at the Arch Linux Wiki.
Configuring on Microsoft IIS 7.5
IIS 7.5 has been minimally tested with the SQLite DB and all the PHP extensions installed that were provided by the 5.3.1 Installer from php.net.
Make sure that the URL Rewrite 1.1 (or higher) module is installed for IIS. This can be installed via the Web Platform Installer from Microsoft. It is also recommended to install PHP 5.3 as the FastCGI process for better performance.
As of 0.6.4 the web.config file for the rewrite rules must be created before installation and put in the document root. The following will work:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Imported Rule 1" stopProcessing="true">
<match url="^.*$" />
<conditions logicalGrouping="MatchAny">
<add input="{REQUEST_FILENAME}" matchType="IsFile" pattern="" ignoreCase="false" />
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" pattern="" ignoreCase="false" />
</conditions>
<action type="None" />
</rule>
<rule name="Imported Rule 2" stopProcessing="true">
<match url="^.*$" />
<action type="Rewrite" url="index.php" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
Configuring Lighttpd
After ensuring that mod_rewrite and mod_fastcgi are added to your server.modules list, use one of the following methods to get lighttpd to perform rewrites properly.
Method One
Before installing Habari, you need to make sure that your lighttpd configuration is setup to properly handle certain special URLs. Here is an example configuration. Make sure to replace the domain name as well as the document root.
$HTTP["host"] == "www.heyilikethis.com" {
server.document-root = "/home/alex/www/blog"
dir-listing.activate = "disable"
url.rewrite-once = (
"^/(?!scripts/|3rdparty/|system/|doc/|user/(?:themes/|files/|plugins/|locales/|sites/))[^?]*(\?(.*))?" => "/index.php/$1"
)
}
source: Habari on Lighttpd - www.heyilikethis.com
Method Two
The second, more flexible, way to configure lighttpd to handle Habari's URLs relies on mod_magnet.
- Add mod_magnet to your server.modules list (requires that lighttpd has lua support, which it usually does).
- Add a clause to your vhosts section of lighttpd.conf similar to the following
$HTTP["host"] == "www.yoursite.com" {
server.document-root = "/path/to/your/habari/root"
dir-listing.activate = "disable"
magnet.attract-physical-path-to = ( server.document-root + "/rewrite.lua" )
}
- Save the following code to a file called rewrite.lua, and put the file in your Habari root
attr = lighty.stat(lighty.env["physical.path"]) if (not attr) then lighty.env["uri.path"] = "/index.php" lighty.env["physical.rel-path"] = lighty.env["uri.path"] lighty.env["request.orig-uri"] = lighty.env["request.uri"] lighty.env["physical.path"] = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"] end
This script may also be accessed at its source at http://mattread.com/rewrite.lua
- Restart lighttpd
Habari's subsite functionality will continue to work using this method. Since all the sites on a Habari install use the same document root, they will all use the same rewrite.lua file. Habari will continue to see that the correct site is found.
Configuring Nginx
Before installing Habari, you need to make sure that your nginx configuration is setup to properly handle certain spefial URLs. due to the lack of .htaccess files. The following needs to be added to your server configuration.
if (!-e $request_filename)
{
rewrite ^/(.*)$ /index.php?$1 last;
}
Configuring Zend Server CE (Habari 0.5.x)
Before installing Habari, you need to disable the extension called "Intl" in extension panel. This extension conflicts with Habari Locale class.
