Chapter 5. Wigwam Walkthroughs
It is often easiest to learn by example, so in this chapter we invent several fictitious Wigwam users to show how we intend Wigwam to be used. These walkthroughs may be read in any order.
Study A: Simple Database-Driven Website
Suppose we wish to set up a webserver that will use CGI scripts to make pages from a MySQL database.
Study A: Starting the Project
First we make a new Wigwam project and install the appropriate services:
wigwam-bootstrap --project=project-name
cd project-name
cvs import project-name start wigwam
cd ..
rm -rf project-name
cvs co project-name
cd project-name
./autogen.sh
. ./setup-env
packagectl install service_static_apache - service_mysqld |
Now we need to configure the services; this will consist of setting environment variables for the cluster, the role and the project. First we recommend flushing out the developer role (and sometimes a developer cluster is useful...). First, mark that you are in that role:
echo developer >! etc/role |
servicectl check-config role --verbose |
developer: static_apache: needed OUTSIDE_HOSTNAME
developer: static_apache: needed OUTSIDE_PORT
developer: static_apache: needed STATIC_HTTPD_PORT
developer: static_apache: needed SERVER_ADMIN
developer: static_apache: needed LOG_DIR
developer: mysqld: needed MYSQLD_DATA_DIR
developer: mysqld: needed MYSQLD_PORT |
To make things work, you must set these up in a cluster, role or project file. There are many possible ways, but sometimes we do it this way. Each port is relative to a PORT_PREFIX. Usually PORT_PREFIX will be defined on a cluster-wide basis, but for the developer role, it may as well be in the role's early configuration file, etc/roles/ROLE/config.pre:
 | The etc/roles/ROLE/config is sourced after etc/project.conf, so it cannot be used here, since we want to put the specific services ports in etc/project.conf. |
echo 'PORT_PREFIX=80' >> etc/roles/developer/config.pre |
if test "x$PORT_PREFIX" = "x" ; then
echo "$0: You must define PORT_PREFIX must before you source project.conf" 1>&2
exit 1
fi
STATIC_HTTPD_PORT=${PORT_PREFIX}80
MYSQLD_PORT=${PORT_PREFIX}81 |
OUTSIDE_HOSTNAME=`hostname -f`
OUTSIDE_PORT=${PORT_PREFIX}80
LOG_DIR=$LOCAL_VAR/logs
MYSQLD_DATA_DIR=$LOCAL_VAR/mysqld
SERVER_ADMIN="$USER@$OUTSIDE_HOSTNAME" |
Now you can being adding web pages in www/htdocs/.
Study A: Developing
Now we'll add some content to the webserver, and then start it. Start with a static webpage. Create the file www/htdocs/index.html:
<head> <title>Hello Wigwam</title> </head>
<body>
<h1> Get a string from mysql table and place here </h1>
</body> |
servicectl start static_apache mysqld |
Study A: Staging
So after the static website is properly written and checked into CVS, it should be tested by staging it.
There are two roles to assign: the webserver and the database. If you are staging to a single server, you can use the developer role, or a similar role so that log files and so on can be properly redirected.
It is better to stage just as the final site will be staged: so pick a staging cluster of two machines, if possible. Make two roles:
- webserver
A webserver (no database). The file etc/roles/webserver/config should set the variable playpen_services.
- database
A database. etc/roles/database/config should set the variable playpen_services to mysqld; also MYSQLD_DATA_DIR should be set (use servicectl check-config --role webserver to test this).
Then run the pubtool tag to make a tagged version of the site. You will use the tag to publish.
Study A: Publishing
Publishing mostly requires configuring a cluster.
Assume that we are publishing on the vegas cluster. We make a file etc/clusters/vegas/hosts containing the host data:
mandalay,flamingo role=webserver playpen_root=/web/PROJECT username=PROJECT luxor role=database playpen_root=/web/PROJECT username=PROJECT |
vegas |
Then, once you are confident you have tested the site adequately, run:
pubtool tag --cluster vegas |
Then publish the site by running:
pubtool publish vegas |