99% of the time when people have problems installing, upgrading, or using Vanilla it is due to common server configuration issues. Below is a summary of some common problems and solutions you may face when using Vanilla:

By far the most common problem people have with Vanilla is getting their permissions set up correctly.

Vanilla saves configuration settings to the conf/settings.php file instead of the database in order to keep the application lean and fast. In order to allow Vanilla to make changes to those files, you must give your web server permission to write to the conf files. Some common errors you may encounter due to a permissions problem are:

• Welcome to Vanilla" message won't disappear permanently
• Extensions not "sticking"
• Installed vanilla - can't change settings

In order to fix these problems there are two methods for linux/unix servers. You either need to chmod the files so that the web server has permission to edit them, or you need to chown the files so that the web server owns the files and can retain full control over them.

You can chmod the files so that they are wide open to all users on the server with a command like:

chmod --recursive 777 /path/to/vanilla/conf/

If you still have problems with permissions after that, it could be due to your server. Some servers are set up to not allow that much access to any files for security reasons. You can try bringing the permissions down a notch with the following command:

chmod --recursive 666 /path/to/vanilla/conf/

My personal recommendation is that you chown the files so that the web server owns them. In order to do this you will need to know what user and group your web server run as. This can vary from operating system to operating system. On Debian, for example, the user and group for the Apache web server are www-data and www-data respectively. Other common names for the Apache user and group are apache and httpd. In order to chown to the apache user and group, you can run a command like this:

chown --recursive www-data:www-data /path/to/vanilla/conf/

Of course www-data will have to be replaced with the user and group for your particular operating system.

One of the most common questions is, “how can I add my site’s banner to Vanilla?”

There are a number of different ways to accomplish this.

For example, the banner above Vanilla here on the Lussumo Community was added as an extension. This is the recommended way of adding to Vanilla since it doesn’t require that you start to maintain your own custom theme. You can easily upgrade Vanilla without having to worry about what changed in the theme files you’ve altered. Here is the source code for how we added the Lussumo Banner:

<?php
/*
Extension Name: Lussumo Banner
Extension Url: http://lussumo.com/docs/
Description: Adds the lussumo banner to the top of the page.
Version: 1.0
Author: Mark O'Sullivan
Author Url: http://www.markosullivan.ca/
*/
 
if (in_array($Context->SelfUrl, array("index.php", "account.php", "categories.php", "comments.php", "post.php", "search.php", "settings.php"))) {
   class LussumoBanner extends Control {
      function LussumoBanner(&$Context) {
         $this->Name = "LussumoBanner";
         $this->Control($Context);
      }
      
      function Render() {
         echo '<div class="BannerContainer">
            <div class="Banner">
               <a class="BannerLogo" href="http://lussumo.com">&nbsp;</a>
               <div class="BannerMenu">
                  <a href="http://lussumo.com/swell">Swell Blog</a>
                  | <a href="http://lussumo.com/docs">Documentation</a>
                  | <strong><a href="http://lussumo.com/community">Community</a></strong>
                  | <a href="http://lussumo.com/addons/">Vanilla Add-ons</a>
               </div>
            </div>
         </div>';
      }
   }
   
   $LussumoBanner = new LussumoBanner($Context);
   $Page->AddRenderControl($LussumoBanner, $Configuration["CONTROL_POSITION_HEAD"]+1);
   $Head->AddStyleSheet('extensions/LussumoBanner/style.css');
}
?>

This will work like all other extensions, save this file as default.php in a folder named Banner under the extensions one. Then click the Settings tab (you must have the appropriate credentials) and go to the extensions page where you’ll just have to activate Lussumo Banner.

Note that the name of the folder Banner will only appear internally (in the conf/extensions.php file) and nowhere on the admin side of your site.

The alternate method is to create your own custom theme and start editing files. If you want to take this route, you should read the documentation, but here is a quick-start:

Make a new theme folder next to /themes/vanilla/ called something like /themes/mycustomvanilla/

Go into /themes/vanilla and copy the styles folder. Go to your /themes/mycustomvanilla and paste in the styles folder.

Go to the root /themes/ folder and copy only the files you wish to change. Go to /themes/mycustomvanilla/ and paste those files into the folder.

Open up each of the files you wish to change and alter them as necessary.

Then sign into Vanilla and go to the settings tab. Click the “Themes and Styles” form. Under themes choose “mycustomvanilla”. Under styles choose “default”. Check “apply to all users”. Click Save.

If you find that you are getting a “Precondition Failed” error when installing Vanilla, it is due to a security measure that your hosting company has taken. Add this to your .htaccess file and it should fix the problem (if you don’t have a .htaccess file in the root folder of Vanilla, go ahead and add one):

SecFilterEngine On
SecFilterSelective "REQUEST_URI" "/pms-forum/setup/installer.php" "allow,nolog"

References:

http://lussumo.com/community/discussion/2416/iis-vanilla-10-install-problem/

http://lussumo.com/community/discussion/2566/precondition-failed/

When you encounter an error like this one, if a search yeilds no good results, copy and paste the entire message into your post at lussumo.com/community. Also include your php version, mysql version, and server’s operating system and version.

Even us “pro’s” are guilty of it, we all totally screw things up from time to time (yeah, we’re big about it like that). So we’ll share with you some common mistakes *WE* have made on a regular basis, whether it be through a fresh install or an upgrade and help you locate what you should look for before making yourself look silly.

1. Accidently uploaded php files as Binary instead of ASCII.
2. File permissions on critical files or folder were not set.
3. Settings.php (Without these, Vanilla might not be running.)
   • Is the database information correct?
   • is the domain path and cookie information correct?
4. Check your servers running environment.

   <? phpinfo(); ?>

5. Does this server even meet the requirements?

Bugs, Bugs, and more bugs. If you think you’ve found a bug, or something worthy of qualifying as a serious flaw in Vanilla. Please don’t hesitate on consulting the Bugs & Bug Tracking section on how to approach it.

Installation doesn’t work and the tutorial presumes we all have SSH access, hardly server independent