VirtualSafari Instructions

Documentation for version 1.0
by Sveinbjorn Thordarson (sveinbjornt@DONTSPAMhi.is)

What is VirtualSafari?

VirtualSafari is a Web-based frontend for Apple's WebKit HTML rendering engine. Basically, it makes it possible to host a website which looks like the Safari browser and allows the end-user to *load* pages rendered with the WebKit engine. Does that sound confusing? Well, it'll all be clear to you once you've seen it in action.

How does it work?

The end user is presented with a HTML web page with a form which allows him to request a URL. The form calls a Perl script ("vs.pl") which creates a "*.vsurl" document which is opened with the VirtualSafari application. This ".vsurl" document tells VirtualSafari which page to load, in what resolution to load it, and where to create a JPEG image of the rendered page. This image is then presented to the end-user with an HTML document. A rudimentary examination of the VirtualSafari source code and associated Perl scripts should makes this clearer for you if neccesary.

How do I set it up?

Before proceeding further, I want to point out that I am not open to receiving emails asking how to set VirtualSafari up. It requires a bit of know-how in configuring a webserver, etc. Just so you know. All right, let's proceed:

Setting up VirtualSafari can be a bit of a hassle. It requires the following steps:

1. Set up Apache (or your other webserver) to run as a user with access to the Window Server

Since the vs.pl script calls a graphical application, the WebServer needs to run as a user with access to the Mac OS X Window Server. This can be any regular user account. For security reasons, however, I recommend that it be a non-administrative, non-root one.

2. Copy the VirtualSafari application into your Applications folder

The VirtualSafari.app application must be located there in order to be launchable by the "vs.pl" script.

3. Copy the script into the CGI executables folder

Locate your web server's CGI directory (default is /Library/WebServer/CGI-Executables/ and copy the 'virtualsafari' folder into it. The 'virtualsafari' folder contains the "vs.pl" script and some supporting HTML files it uses. Make sure the "vs.pl" script is chmod-ed to be executable like other CGI scripts.

4. Copy the images used by the HTML files to your webserver's document root

Copy the 'webimg' directory to your webserver's document root. The default location for Apache in a Mac OS X installation is /Library/WebServer/Documents/ but this may vary according to your setup, VirtualHosts, etc.

5. Create the 'vsimg' folder

Create a folder called 'vsimg' in your webserver's document root

6. Start up your webserver

7. Visit http://localhost/cgi-bin/virtualsafari/vs.pl

A web page should pop up which looks exactly like a metal-free Safari window, complete with a text field for the URL. Try typing in a URL and pressing enter. This should launch the VirtualSafari application, and then subsequently load a JPEG image of the rendered page within the HTML-crafted Safari frame.

I have successfully set up VirtualSafari on several different machines using those same instructions, so provided that you know what you're doing, you shouldn't have any trouble. Be aware, however, of the security implications in running a webserver under a user other than 'www'.