The basic website tutorial here describes how to set up a static website — one that just serves HTML files saved on your server, and until you change something manually, the same content will be served each time a given page is requested. This is perfectly enough for most personal website needs. This is how blogs should be implemented, instead of relying on bloatware like WordPress!
But sometimes you genuinely do need something more. You need your website to serve different contents depending on the time, on who the requester is, on the contents of a database, or maybe process user input from a form.
CGI
CGI, or the Common Gateway Interface, is a specification to allow you, the server owner, to program your web server using pretty much any programming language you might know. The specification is almost as old as the Internet itself and for a long time CGI scripting was the primary method of creating dynamic websites.
CGI is a very simple specification indeed. You write a script in your favorite language, the script receives input about the request in environment variables, and whatever you print to the standard output will be the response. Most likely, though, you will want to use a library for your language of choice that makes a lot of this request/response handling simpler (e.g. parsing query parameters for you, setting appropriate headers, etc.).
Limitations of CGI
While in theory you could implement any sort of functionality with CGI scripts, it's going to get difficult managing a lot of separate scripts if they're supposed to be working in tandem to implement a dynamic website. If you want to build a full out web application, you'd probably be better off learning a web framework than gluing together Perl scripts.
That said, just as most of the web could be replaced with static websites, much of the remaining non-static web could be replaced with a few simple scripts, rather than bloated Ruby on Rails or Django applications.
Let's write a CGI script!
We'll implement a simple example CGI script. I'll use Ruby for this tutorial, but you'll be able to follow along even if you don't know Ruby, just treat it as pseudocode then find a CGI library for your language.
The working example
Our working example will be the Lazy Calculator. Yeah, you're probably tired of seeing calculator examples in every programming tutorial, but have you ever implemented one that takes the weekends off?
Here's how it will work. When in a browser you submit a request to your website like
example.com/calculator.html?a=10&b=32
you will receive a page with the result of the addition of 10 and 32: 42.
Unless you send your request on a weekend. Then the website will respond with
I don't get paid to work on weekends! Come back Monday.
This example will show a few things that CGI scripts can do that you wouldn't have been able to get using just file hosting in your web server:
- getting inputs from the user;
- getting external information (here just the system time, but you could imagine instead connecting to a database);
- using the above to create dynamic output.
The code
Here's an implementation of the lazy calculator as a Ruby CGI script:
#!/bin/env ruby
require 'cgi'
require 'date'
cgi = CGI.new
today = Date::today
a = cgi["a"].to_i
b = cgi["b"].to_i
if today.saturday? || today.sunday?
cgi.out do
"I don't get paid to work on weekends! Come back Monday."
end
else
cgi.out do
(a + b).to_s
end
end
Let's go through what's happening here.
The shebang line
CGI works by pointing your web server to an executable program. A Ruby
or Python script by itself is not immediately executable by a computer.
But on Unix-like systems you can specify the program that will be able
to execute your file in its first line if it starts with #! (known as
the shebang; read more about it on
Wikipedia).
So if you're going to be using a scripting language, you'll probably need the appropriate shebang line at the top of your script. If you use a compiled language, you'll just point your web server to the compiled executable binary.
Query parameters
The next interesting lines of code are where we set the variables a
and b. Here we are getting user inputs from the request.
In the example request we mentioned above
(example.com/calculator.html?a=10&b=32), the part starting from the
question mark, ?a=10&b=32, is the query string. This is how users
can submit parameters with their web requests. Usually these parameters
are set by e.g. a form on your website, but in our simple example we'll
be just manually manipulating the URL.
The query string contains key-value pairs. The Ruby CGI library makes
them available in the CGI object it provides. We just need to index it
with the desired key, and we'll get the corresponding value.
Wrapping it up
The remaining parts of the code should be pretty self-explanatory. We get today's date, check if it's a Saturday or a Sunday, and depending on that, we instruct the CGI library to output either the answer, or a "come back later" message.
The Ruby library by default returns an HTML response, so we really
should have wrapped our outputs in some html, body, etc. tags.
Alternatively, we could have specified that the response is just plain
text with
cgi.out 'text/plain' do
In general, your CGI library will probably have ways of specifying all sorts of HTTP response headers, like status code, content type, etc.
Making it work
We have a CGI script, now let's point our web server to it.
Installing FastCGI
If you're using Nginx, install fcgiwrap:
apt install fcgiwrap
This installs the necessary packages for Nginx to use FastCGI — a layer between your web server and CGI script that allows for faster handling of scripts than if the web server had to handle it all by itself.
Other web servers will probably have a similarly simple way of enabling FastCGI, or you can look into other methods for launching CGI scripts.
Nginx configuration
In the configuration file for your website, add something like the following:
location /calculator.html {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /usr/local/bin/lazy-calculator.rb;
fastcgi_param QUERY_STRING $query_string;
fastcgi_pass unix:/run/fcgiwrap.socket;
}
fastcgi_param directives specify various parameters for FastCGI.
SCRIPT_FILENAME should point to your executable. For QUERY_STRING,
we just copy Nginx's $query_string variable. You might want to pass
other information to your CGI script as well, see for example the
Debian wiki for a more detailed
example, including pointing to an entire directory of CGI scripts,
rather than adding each one by hand to your web server config.