After having installed your very own vanilla and having it got up and running you may wonder: "Heck, how to I get those nice /space/ urls used on www.vanillasite.at?" This short guide aims to answer your question.

Some important things to note before we start: You must be able to configure your webserver (this may be a problem on some shared hosting platforms). We only discuss Apache configuration here and you need to have mod_rewrite installed and enabled in your Apache installation - to do this, search for and uncomment the LoadModule line with rewrite_module in it.

To reach our goal of nicer urls, two steps are necessary. We have to

1. configure the webserver
2. configure vanilla

webserver configuration

First, we must instruct Apache to internally rewrite the "nice" urls to the urls used by vanilla. This configuration can either be done globally (in the global Apache configuration file usually called httpd.conf) or if in a .htaccess file usually placed in the root directory of your web site. Please note that using .htaccess files may be disabled in your Apache setup.

If you choose the former method, place the following lines somewhere near the end of httpd.conf (or if you use vhosts, place it somewhere in the appropriate vhost section):

RewriteEngine on
RewriteRule ^/$ /space/start [R,L]
RewriteRule ^/space/(.*)$ /cgi-bin/vanilla.cgi?selector=display&snip=$1 [PT]

You'll have to restart Apache for the changes to take effect.

If you choose the .htaccess method instead, create a .htaccess file in the root of your website. The stuff the be placed in there is almost the same as for global configuration, only the leading slashes of the RewriteRule patterns have to be omitted:

RewriteEngine on
RewriteRule ^$ /space/start [R,L]
RewriteRule ^space/(.*)$ /cgi-bin/vanilla.cgi?selector=display&snip=$1 [PT]

Please note that the vanilla target url used here (i.e. /cgi-bin/vanilla.cgi?selector=display&snip=$1) assumes that your vanilla CGI resides under /cgi-bin/ and is called vanilla.cgi. Basically, this is what you should have if you followed the install guides (see documentation).

However, if you have a different setup, you have to change the target URL of the second RewriteRule accordingly. For example if your vanilla CGI is called my-vanilla-cgi and was placed in a /exec/ directory, you'd have to use a target of /exec/my-vanilla.cgi?selector=display&snip=$1 instead.

Your Apache is ready, let's configure vanilla.

vanilla configuration

As Apache will now properly pass translate those nice urls into a form understandable by vanilla, we need to instruct vanilla how to generate those nice urls when rendering snips. While there are some more possibilities to fine-tune vanilla's link generation, we will only concentrate on how to use /space/ urls for accessing snips.

Modify your vanilla config file to contain the following:

vanilla-base-url: "http://your-domain/cgi-bin/"
vanilla-display-url: "/space/"

You will have to change the your-domain dummy to the actual domain name your vanillasite is accessible under. For strictly local setups use localhost. If you vanilla setup is different to the one suggested in the install guide, you'll also have to adapt the rest of vanilla-base-url accordingly.

Finally, please make sure that all other lines in your config file that either set vanilla-base-url or vanilla-display-url are commented (by prefixing them with a semicolon).

That's it! If all works you'll see links from one snip to another generated with proper urls and following such links will work too :)