How to Add EUPHORIA CGI Script Support to Your Apache Server on Windows

This article explains what you need to do to make your Apache server run EUPHORIA CGI scripts on Windows systems. (What is Apache?)

This article assumes you have EUPHORIA and Apache successfully installed. If you do not, do that first (install Euphoria, install Apache). Then come back here.

Important Definitions

    CGI Script - A program that can be used to output HTML (text). Generally, your web server (Apache) will call the CGI script and direct the output of the CGI script to the web browser. In our case, we're going to write a Euphoria program that will output a web page. It can be as simple as printing "Hello, world!" and as complex as accessing multiple databases and using complicated calculations to produce output.
    Web Server (or Apache) - A program that manages the input and output of Internet data. The server receives all HTTP requests and sends out all HTML.
    http.conf - This is a very important file: the Apache configuration file. Basically, this file contains "directives" that tell Apache what to do. You must be familiar with this file in order to use Euphoria as CGI, so read all about it.

Important Concepts

    How Your Browser Gets a Page

    Here's how this process works: a person with a web browser requests a web site. The web site is controlled by the Apache server. When the Apache server receives the request, it runs the Euphoria program. The Euphoria program does its thing and sends any output back to the Apache server. The Apache server then sends that output to the user's browser.

    The DocumentRoot

    In the Apache http.conf configuration file, there is a path specified for the DocumentRoot. This is where you will need to place all your web files. You can, of course, change the DocumentRoot to something else. For instance, mine is c:/htdocs. No matter where it is, Apache must know where your files are, and this is how you tell it.

Running EUPHORIA Scripts in a CGI directory

Generally, there is one directory where CGI scripts are placed. Web hosts typically call such a directory cgi-bin. When a request comes in that requires CGI processing, Apache knows to look to this directory for the CGI script. If you prefer, you can configure Apache to look in a different directory for CGI files.

To configure Apache to treat a particular directory as your script directory, search for the following line in your "httpd.conf" file. (The "httpd.conf" file can be found in the "conf" directory of your Apache folder. If you used the default directories supplied by the Apache installer, it would be "c:\Program Files\Apache Group\Apache\conf\httpd.conf".)

ScriptAlias /cgi-bin/ "C:/Program Files/Apache Group/Apache/cgi-bin/"

If it has been commented out- that is, if there is a hash mark ("#") before the line- remove the hash character to enable it. If it has not been commented out, it means that your Apache is already configured to run CGI scripts in that directory. You can change the directory to another directory if you wish.

You will put your EUPHORIA CGI scripts in this folder. You will have to call them with a URL like this one:

   http://www.mydomain.com/cgi-bin/myprogram.exw

You can configure Apache to run CGI script files from any directory so, for instance, the following URL could also run a CGI script program.

   http://www.mydomain.com/index.exw

Running CGI scripts anywhere in your domain

If you don't want to be restricted to running CGI scripts within the ScriptAlias directory in your domain, and want CGI scripts to run anywhere in your domain, add the following line to your "httpd.conf" file.

AddHandler cgi-script .exw

If you're using Linux/FreeBSD or DOS, you would add

AddHandler cgi-script .exu

or

AddHandler cgi-script .ex

respectively.

You can just put all three if you like!

AddHandler cgi-script .exw .exu .ex

Next, search for the line that starts with "Options" in the file. It should look something like this:

Options Indexes FollowSymLinks

Add "+ExecCGI" to the options list. The line now looks like this:

Options Indexes FollowSymLinks +ExecCGI

Making a CGI Script Your Default Page

If you want to make your CGI script execute as the default page for a directory, you have to add another line to the Apache configuration file (httpd.conf). Simply search for the line in the file that begins with a "DirectoryIndex" and add "index.exw" to the list of files on that line. For example, if the line used to be:

DirectoryIndex index.html

change it to

DirectoryIndex index.exw index.html

The next time you access "http://localhost/" or "http://localhost/directory/" without any filename specified, Apache will run "index.exw" if available or deliver "index.html" if it cannot find "index.exw". If you have both "index.exw" and "index.html" in the directory, "index.exw" is used since it's listed first.

The directive instructs Apache to look first for an an index.exw file, or if that could not be found, an index.html file.

That's it. Your Apache server now supports the execution of EUPHORIA CGI scripts. You will have to restart the server before the new configuration comes into effect. The work's not ended however - read on.

Modifying Your CGI Script

As it stands, if your CGI script is a Windows executable, it would be executed by Apache correctly. However, if it's a script that relies on an interpreter such as EUPHORIA, you will have to modify the first line of the script.

Your EUPHORIA script should contain an initial line of

#!c:/euphoria/bin/exw.exe

or some such thing. This tells Apache to look for the EUPHORIA interpreter at the path provided and invoke it to interpret the instructions in the file.

NOTE: I use WebIntellects DrupalValueHosting HostingMetro to host my Euphoria-driven web sites. If I've developed a CGI program on Windows and try to upload it there, it doesn't work because of the way Windows formats text files different than Unix. I usually have to open the file up in their web-based editor and save it. Then it works.

EUPHORIA CGI "Hello, world."

If you have any questions or need more help, ask on the EUPHORIA Forum.

You can also read about CGI with Euphoria on the RDS website.