Installation

From Habari Project

Jump to: navigation, search

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.

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> 

If you're on a hosted solution, you might want to check if there are special instructions.

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.

Stable Release

Development Release

  • If you're more adventurous, you can download a development snapshot. These are generally reasonably stable and should run properly, but you should be aware that some features might not be completed.

Git Installation

See Habari on github for how to install Habari from git, including how to contribute code back to the project.

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. To install Habari 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, PostgreSQL or SQLite, copy <root>/system/schema/<dbms>/config.php to the root folder, where index.php is.

Create a blogdata array as below, or similar, in the copied config.php file.

Config::set( 'blog_data', array(
        'admin_username' => 'ernie',
        'admin_pass1' => 'RubberDuck',
        'admin_pass2' => 'RubberDuck',
        'admin_email' => 'ernie@www.sesamestreetlive.com',
));

Valid blogdata Parameters:

        'admin_username' => 'The admin user username',
        'admin_pass1' => 'The admin user password',
        'admin_pass2' => 'The admin user password',  // Must be submitted identically in 1 and 2!
        'blog_title' => 'The title of the blog',
        'admin_email' => 'The admin email address',
        'option_theme_name' => 'The name of a theme',
        'option_theme_dir' => 'The directory of the named theme',
        'option_someoption' => 'The value of a database option named "someoption"',
        'plugin_pluginfile.plugin.php' => 'If the value of this key is 1, then the plugin file named "pluginfile.plugin.php" will be activated',

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.


Configuring A Proxy Server

If your Habari installation is behind a proxy server and you require access to sites outside of your proxy , for example you wish to use the Twitter plugin, then add the following to your config.php file:

Config::set( 'proxy', array(
	'server' => 'localhost',
	'port' => 1080,
	'username' => null,
	'password' => null,
	'exceptions' => array(
		'example.com',
	),
	'auth_type' => 'basic',		// or digest - currently only supported by curl
));

Substitute in your own configuration values. Don't leave any of the values out or things might break.

Note that the follow values will automatically be added to the list of exceptions:

  • localhost
  • 127.0.0.1
  •  ::1
  • $_SERVER['SERVER_NAME']
  • $_SERVER['SERVER_ADDR']


Custom Server Port

If you are serving Habari from your server via a different port than from what it'll be accessed you can configure Habari to use the correct port by adding the following to your config.php:

Config::set( 'custom_http_port', 8080 );

Substitute your own port number.

This configuration would be needed for the situation where your local server is hosting Habari on port 8080, but it is being accessed via port 80 through a NAT.

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 your Nginx configuration is set up properly to handle certain special URLs. Due to the lack of .htaccess files, the following needs to be added to your server configuration.

location /habari/ {
	try_files $uri $uri/ /habari/index.php?$args;
}

Substitute both instances of `/habari/` with the base URL used for accessing your site. If your site is in the root directory, simply use `/` in both instances.

This is similar to the recommended Apache config, in that it will attempt to access the URI as a file and a directory, before falling back to passing it to Habari.

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.

There are no special steps required for Habari versions since 0.6.

Configuring Cherokee

Here is how to prepare the Cherokee webserver for Habari.

  • In the cherokee-admin create a new vServer and choose languages>PHP
  • In your new vServer, go to the behavior tab and click rule management.
  • Change the handler for the default rule to redirection and add the following 2 internal rules:
    • Regular Expression: . Substitution: /index.php
    • Regular Expression: ^(system/(classes|locale|schema|$)) Substitution: index.php
  • add a new rule between the php and default rules. The matching rule should be "File exists" and the handler should be "list & send" Be sure to check "match all files"
  • If you plan to use sqlite for your database, be sure to add another "file exists" rule at the beginning of your rule list that matches the name of your db file and set the handler to HTTP error so it can't be accessed.

You should now be able to extract habari to your vServer's document root and run the installer.

Software Bundles

Web Servers

Hosting Solutions

Personal tools