CGI Programming 101: CGI Programming With Apache and Perl on Windows XP

This page will show you how to install the Apache web server and Perl on your home computer. You'll then be able to write CGI programs and test them locally on your computer. Once Apache is installed and running, you'll be able to view your pages by pointing your web browser at the http://localhost/ address. You don't even need to be connected to the internet to view local pages and CGI programs, which can be quite useful if you want to work on programming while you're traveling or otherwise offline.

These instructions have been tested on Windows XP. You should be able to install Apache and Perl on earlier versions of Windows, but on those systems you should definitely read the installation instructions that come with the software, since some things may need to be configured differently.

Who can see your website?

If you have a permanent, fixed IP address for your computer (e.g. your computer is in an office, or you have your own T1 line), your Apache server will be able to serve pages to anyone in the world*. If you have a transient IP address (e.g. you use a dialup modem, DSL modem or cable modem to connect to the internet), you can give people your temporary IP address and they can access your page using the IP address instead of a host name (e.g, http://209.189.198.102/)*. But when you logout, your server will obviously not be connected, and when you dial in again you'll probably have a different IP address.

Obviously for permanent web hosting, you should either get a fixed IP address (and your own domain name), or sign up with an ISP that can host your pages for you (like cgi101.com).

* Unless you're behind a firewall, and the firewall is not configured to allow web traffic through.

Programming Locally, then Uploading to the ISP

You may want to develop and debug your programs on your own computer, then upload the final working versions to your ISP for permanent hosting. Nearly all of the programs shown in CGI Programming 101 will work seamlessly on Unix or Windows, but see below for a few differences.

Differences between CGI Programs on Unix and Windows

1. The "shebang" line.
The first line of a Perl program (often called the shebang line) typically looks like this:

#!/usr/bin/perl

The actual location of Perl may be different from system to system (e.g. /bin/perl, /usr/local/bin/perl, etc.) For ActivePerl in Windows, this line should be changed to:

#!/perl/bin/perl

If you're programming locally and uploading to a remote ISP, you'll have to change this line each time.... unless your ISP was thoughtful enough to add a symlink to Perl in /perl/bin/perl. (We've done that on cgi101.com.)

2. Permissions.
On XP you don't need to worry about file permissions. A CGI program is always executable, and your programs can always write to files to your directory. (Although, this isn't necessarily a good thing...)

On Unix, permissions matter. Your CGI programs will need to be set with execute permissions. Any files you want to write to will need to be set with write permissions.

CGI Programming 101 includes instructions on how to properly adjust file permissions for CGI programs in Unix. If you are writing your programs on XP and are not planning to upload them to a Unix server, you can simply disregard the permissions information.

Installing Apache on Windows XP

First go to http://httpd.apache.org/download.cgi and download Apache. Scroll down the page a bit until you find the one that says "best available version" (Apache 2.something). Then look for the "Win32 Binary (MSI Installer)". Download the binary .msi file to your computer (choose "open" rather than "save" so the installer will launch immediately).

The installer start screen.
Server Information - use localhost for both the Network Domain and the Server Name, unless you have a fixed IP address and your own domain name. Put your e-mail address for the Administrator's Email Address.
Setup Type - select "Typical"
Destination folder - the default is fine, C:\Program Files\Apache Group\

Finish the installation and quit the installer. At this point Apache is probably already running on your machine; go to http://localhost/ in your browser to view your start page.

To start/stop the Apache server, go to the Start menu and navigate to All Programs > Apache HTTP Server > Control Apache Server. There you can start, stop and restart Apache. You can also install the Apache taskbar icon via the "Monitor Apache Servers" option.

If you want to modify the homepage displayed by your Apache server, go to the Start menu and choose "My Computer", then navigate to Local Disk (C:) > Program Files > Apache Group > Apache 2. You'll see a folder containing items like this:

Open the htdocs folder and look for index.html. You can edit the file in Notepad or whatever HTML editor you like.

For the programming examples in CGI Programming 101 we're going to create a separate folder in your "My Documents" area for CGI programs and HTML files. There's not really any need to modify the files here in htdocs unless you are setting up your own webserver and plan to host your own domain there.


Now you'll need to install Perl.

Installing ActivePerl on Windows XP

Installing Perl should be just as easy as installing Apache. Go to http://www.activestate.com/Products/ActivePerl/ and click on the download link to begin. Download the latest version of Perl available (which is 5.8.1 as of November 2003). Download the MSI file and open it.

The installer starts up.
On the Custom Setup screen, you can leave the setup as the default. This will install Perl, PPM (the Perl Package Manager) and programming examples to your hard drive in the location C:\Perl.
The "new featuers in PPM" screen talks about a PPM profile feature, but that requires ASPN (the full, commercial version) Perl, which you probably aren't installing right now. Leave the "Enabled PPM3 to send profile info to ASPN" unchecked.
Under Choose Setup Options, both "Add Perl to the PATH environment variable" and "Create Perl file extension association" should be checked.

The installer will finish up by installing HTML documentation. This step will take a while so be patient. When it's finished, your browser will launch and bring up the ActivePerl documentation:

Bookmark this page now (in your browser's favorites menu) so you can access it easily later.


Now Perl is installed. All you need to do now is modify the Apache server configuration.

Configuring Apache

First go to the Start menu and go to "My Documents". Make a new folder there called "My Website". This is where you're going to store your web pages and CGI programs.

Next you need to modify the Apache configuration file to tell it where your pages are, and enable CGI programs. Go back to the Start menu and navigate to All Programs > Apache HTTP Server > Configure Apache Server > Edit the Apache httpd.conf Configuration file. The config file will be opened for you in Notepad.

Scroll down (or use Find) until you get to the UserDir section of the file. It should have a line like this: 

        UserDir "My Documents/My Website"

Apache 2.2 doesn't have a UserDir section
If you're using Apache 2.2, you'll have to ADD the UserDir line and the Directory section ( see below ). See http://httpd.apache.org/docs/2.2/mod/mod_userdir.html for more info on this.

Scroll down just past that and you'll come to a commented section for Directory: 

        #<Directory "C:/Documents and Settings/*/My Documents/My Website">
        #  AllowOverride FileInfo AuthConfig Limit
        #  Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
        #  <Limit GET POST OPTIONS PROPFIND>
        #     Order allow,deny
        #     Allow from all
        #  </Limit>
        #  <LimitExcept GET POST OPTIONS PROPFIND>
        #     Order deny,allow
        #     Deny from all
        #  </LimitExcept>
        #</Directory>

Uncomment this entire section (by removing the pound signs at the beginning of each line), and change the Options line to this: 

        Options MultiViews Indexes SymLinksIfOwnerMatch Includes ExecCGI

Options specifies what options are available in this directory. The important ones here are Indexes, which enables server-side includes, and ExecCGI, which enables CGI programs in this directory.

Scroll down a bit further to the DirectoryIndex line, and add index.cgi to the end of that line: 

        DirectoryIndex index.html index.html.var index.cgi

Now scroll down several pages (or use Find) to the AddHandler section. Uncomment the CGI line: 

        AddHandler cgi-script .cgi

This causes any file with a .cgi extension to be processed as a CGI program. If you want to also have files with a .pl extension be processed as CGI programs, add the .pl extension on that same line: 

        AddHandler cgi-script .cgi .pl

Next add this line immediately after: 

        AddHandler server-parsed .html

This causes all .html files to be searched for server-side include tags.

Now save the configuration file, and restart Apache. Check http://localhost/ in your browser to ensure that the server restarted successfully.

Trouble? If you get an error like the following:

Only one usage of each socket address (protocol/network address/port)
is normally permitted. : make_sock: could not bind to address 0.0.0.0:80
no listening sockets available, shutting down

This probably means you're already running another web server (such as IIS) on your machine. You'll need to remove IIS in order to run Apache. See the following Microsoft document on How to Remove IIS.

Viewing Your Site

http://localhost/ is the homepage for your site; it shows the index.html page located in the htdocs folder.

To view the pages in your "My Website" folder, the actual URL is http://localhost/~my username/. For example, on my computer, my username is "Jackie Hamilton", so the URL to my pages is http://localhost/~Jackie Hamilton/. (If you don't know your username, open the Start menu; your username is at the top of the Start box.)

In your browser, go ahead and type in the URL to your web page. If you remembered to create the "My Website" folder earlier, you should now see an empty directory listing. Bookmark the page so you don't have to type in the long URL any more.

Writing Your CGI Programs

Now you're ready to write some CGI programs! Here's a simple one you can use to get started. You can write this in Notepad: 
        #!/perl/bin/perl -wT
        print "Content-type: text/html\n\n";
        print "<h2>Hello, World!</h2>\n";

Unfortunately Notepad has a nasty habit of appending .txt to the end of all text files, so when you go to save this file, change the "Save as Type" from "Text Documents" to "All Files". Then put "first.cgi" as the file name. Save it in your My Website folder, then reload your web page in your browser. You should see first.cgi listed there; click on it to view your first CGI program!

Now go to Chapter 1 to start learning CGI programming.

Other Perl Editors

You can get by just fine by writing all of your CGI programs in Notepad. But you might find it more helpful to use a proper Perl editor for writing code. ActiveState (the generous folks who provide ActivePerl for free) also sells Visual Perl, a Perl plug-in for Visual Studio .NET.

EditPlus is a shareware ($30) text/HTML/programming editor with syntax highlighting for various languages.

The DzSoft Perl Editor offers syntax coloring (and checking), a builtin "run" option that you can use to test your scripts (and view error messages), a file template for new files, quick-insert shortcuts, and other useful tools. This program is shareware ($49) but a demo is available for download and evaluation.

OptiPerl is a visual developing environment and editor for creating, testing, debugging and running perl scripts. A free trial download is available, and if you decide to keep it, the standard license is $39.

Perl Editor by EngInSite is an integrated development environment for creating, testing and debugging Perl scripts.

Troubleshooting

If you get an error like this when you try to start Apache:

Only one usage of each socket address <protocol/network address/port> is normally petmitted. :make_sock could not bound to address:0.0.0.0:80
no listening sockets available , shutting down
Unable to open logs

This probably means you already have another web server program (like IIS) running. You'll need to turn the other one off before you can start Apache. To disable this, go to the Control Panel->Administrative Tools->Services, and look for the IIS service. Right-click to stop the service.