From Habari Project
A single installation of the Habari source code can power multiple, independent sites.
If you have only a single site, then Habari will use the config.php file that resides in the same directory as index.php. This is the default configuration file, and will be used if no site-specific configuration can be found.
How it works
In order to run multiple sites, you will first need to create a
sites directory inside Habari's
user directory. Then, inside
user/sites you will create a directory for each site you want to run. Inside each of these sub-directories you will place a config.php with that site's configuration directives.
The name of the directory to use for each site is constructed in the following way:
- strip off the protocol used to access the site. http://habariproject.org/en/ becomes habariproject.org/en/
- replace all slashes with periods. So habariproject.org/en becomes habariproject.org.en.
- place any non-standard HTTP port at the beginning of the directory. So habariproject.org/en:8080 becomes 8080.habariproject.org.en
Habari will traverse the directories in /user/sites looking for the closest match. So, for a request to www.habariproject.org/en, Habari will look in the following directories under user/sites in the following order for a config.php
Please note that some of the Multisite functionality is broken in Habari 0.9.2, especially running sites in subdirectories!
Additional Habari-powered sites do not need to use the same domain. Provided the web server is properly configured, a single installation of the Habari source code can serve www.habariproject.org, www.habarithemes.org, and www.habari-ya-kazi.com. Likewise, sub-domains are also supported.
Properly configured simply mean that all sites running off one habari installation are configured to point to the same directory. Assume you install Habari in /home/www and /home/www is configured to be your DocumentRoot. You want to run three sites off this one installation of Habari: www.mysite.org, themes.mysite.org, and www.example.org.
Install www.mysite.org in the root of the installation by creating a config file in /home/www. This will be the default site.
Install themes.mysite.org by creating the directory /home/www/user/sites/themes.mysite.org, then place a config file in that directory for the site.
Install www.example.org by creating the directory /home/www/user/sites/www.example.org, then place a config file in that directory for the site.
You can even use this feature when your Habari core is running in a subdirectory. So, if your main site is located at habariproject.org/habari, you can have the following (Habari 0.10 and higher only):
- test.habariproject.org/habari -> name your site directory test.habariproject.org
- habariproject.org/habari/sub -> name your site directory habariproject.org.habari.sub
- test.habariproject.org/habari/sub -> name your site directory test.habariproject.org.habari.sub
Note that the site directory in the second example will also be a fallback for the third example. As you can see, you just have to include the core's directory when using multisites in subdirectories.
Configuring your webserver
When you configure each of these sites on your webserver, point all of them to /home/www by setting /home/www as their DocumentRoot. When a request is made for one of these sites, Habari will look in the directories in /user/sites for one that matches the name of the site being requested. If it finds a match, the config file in that directory will be used to load the site. If it isn't able to find a match, Habari will fall back to the config file located in in Habari's root directory - in this example, using the config file in /home/www.
Each Habari site can use its own themes and plugins, as well as the themes and plugins available to the "main" site. Simply create /themes and /plugins sub-directories inside each site's directory. A theme or plugin located in a site's directory structure is only available to that site; while themes and plugins in the top-level /user directory will be available to all sites.
- DocumentRoot is the directory which web servers use to supply requested files on the internet. It is often named /htdocs or /www, but doesn't have to be. Any subdirectory on a file system can be set up as the DocumentRoot for a given domain.
- Each Habari site is strictly independent. Although sites may share themes and plugins located in the top-level /user directory, no data is shared between sites. User accounts, posts, and settings are completely independent.
- In order for the installation routine to work for a site other than the default site, there must be a
config.phpin that site's directory. Before trying to install the site, replace the placehold text with the text that you plan to use for the database connection details.
- Each site can use any type of supported database desired.
- Sub-directory sites do not correctly function at the moment. Independent domains and subdomains function very well.
- The safest way to name a directory in user/sites is to use the same name as the site it will be hosting rather than relying on Habari's algorithm to determine which configuration file to use to load the site.
- When installing a sub-site using SQLite as its database, if the config file just contains a database name, the database file will be created in the same directory as the site's configuration file.
- When you want www.example.org and example.org to be the same, but in a multisite installation, create sites/example.org and place the config file in it, and then create a symbolic link sites/www.example.org that points to sites/example.org.