Dynamic Web Development with Seaside

23.3.4Running the VMs

Before we hook up the Smalltalk side with the web server, we need a reliable way to start and keep the Smalltalk images running as daemon (background process). We have had positive experience using the daemontools, a free collection of tools for managing UNIX service written by Daniel J. Bernstein. Contrary to other tools like inittab, ttys, init.d, or rc.local, the daemontools are reliable and easy to use. Adding a new service means linking a directory with a script that runs your VM into a centralized place. Removing the service means removing the linked directory.

Type the following command to install daemontools. Please refer to official website (http://cr.yp.to/daemontools.html) for additional information.

$ apt-get install daemontools-run

On the server create a new folder to carry all the files of your Seaside application. We usually put this folder into a subdirectory of /srv and name it according to our application /srv/appname, but this is up to you. Copy the deployment image you prepared in Section 23.1 into that directory. Next we create a run script in the same directory:

#!/bin/bash

# settings
USER="www-data"
VM="/usr/bin/squeakvm"
VM_PARAMS="-mmap 256m -vm-sound-null -vm-display-null"
IMAGE="seaside.image"

# start the vm
exec \
    setuidgid "$USER" \
    "$VM" $VM_PARAMS "$IMAGE"

Again, we are using Squeak in this example. You need to check out the documentation of your Smalltalk VM, if you are running with a different dialect. Let’s have a quick look at the different parts of the script.

On lines 3 to 7 we define some generic settings. $USER is the user of the system that should run your Smalltalk image. If you don’t set a user here, the web service will run as root, something you must avoid. Make sure you have the user specified here on your system. www-data is the default user for web services on Debian systems. Make sure that this is not a user with root privileges. $VM defines the full path to the Squeak VM. If you have a different installation or Smalltalk dialect, you again need to adapt this setting. $VM_PARAMS defines the parameters passed to the Squeak VM. If you use a different environment, you need to consult the documentation and adapt these parameters accordingly. The first parameter -mmap 256m limits the dynamic heap size of the Squeak VM to 256 MB and makes Squeak VMs run more stably. -vm-sound-null disables the sound plugin, something we certainly don’t need on the server. -vm-display-null makes the VM run headless. This is crucial on our server, as we presumably don’t have any windowing server installed.

The last four lines of the script actually start the VM with the given parameters. Line 11 changes the user id of the Squeak VM, and line 12 actually runs the Squeak VM.

To test the script mark it as executable and run it from the command line. You need to do this as superuser, otherwise you will get an error when trying to change the user id of the VM.

$ chmod +x ./run
$ sudo ./run

The VM should be running now. You can verify that by using on of the UNIX console tools. In the following example we assume that the image has a web server installed and is listening on port 8080:

$ curl http://localhost:8080
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>Dispatcher at /</title>
...

You might want to change the URL to point to your application. As long as you don’t get an error message like curl: (7) couldn't connect to host everything is fine. You can install curl using

 apt-get install curl

Troubleshooting the VM. You may encounter some common problems at this point. One of these problems is that the VM is unable to find or read the image, change or source files. Make sure that all these files are in the same directory and that their permissions are correctly set so that the user www-data can actually read them. Also ensure that the image has been saved with the web server running on the correct port.

Squeak and Pharo both display an error message when the .changes or .sources file cannot be found or accessed. Unfortunately this message is not visible from the console, but only pops up virtually in the headless window of the VM. The modal dialog prevents the VM from starting up the server and thus the image remains unreachable. To solve the problem make sure that .changes and .sources files are in the same directory as the image-file and that all files can be read by the user www-data. Another possibility (if you really do not want to distribute the files) is to disable the missing files warning using:

Preferences disable: #warnIfNoSourcesFile

A valuable tool to further troubleshoot a running but otherwise not responding VM is lsof, an utility that lists opened files and sockets by process. You can install it using apt-get install lsof. Use a different terminal to type the following commands:

$ ps -A | grep squeakvm
	22315 ?        00:17:49 squeakvm
$ lsof -p 22315 | grep LISTEN
squeakvm 22315 www-data  7u  IPv4 411140468  TCP *:webcache (LISTEN)
squeakvm 22315 www-data  8u  IPv4 409571873  TCP *:5900 (LISTEN)

With the first line, we find out the process id of the running Squeak VM. lsof -p 22315 lists all the open files and sockets of process 22315. Since we are only interested in the sockets Squeak is listening on we grep for the string LISTEN. In this case we see that a web server is correctly listening on port 8080 (webcache) and that another service is listening on port 5900. In fact the latter is the RFB server, which we will discuss in Section 23.4.2.

In the original terminal, press Ctrl+C to stop the VM.

Starting the service. Go to /service and link the directory with your run-script in there, to let daemontools automatically start your image.

Go to /etc/service (on other distributions this might be /service) and link the directory with your run-script in there, to let daemontools automatically start your image.

$ cd /service
$ ln -s /srv/appname .

You can do an svstat to see if the new service is running correctly:

$ svstat *
appname: up (pid 4165) 8 seconds

The output of the command tells you that the service appname is up and running for 8 seconds with process id 4165. From now on daemontools makes sure that the image is running all the time. The image gets started automatically when the machine boots and — should it crash — it is immediately restarted.

Stopping the service. To stop the image unlink the directory from /service and terminate the service.

$ rm /etc/service/appname
$ cd /srv/appname 
$ svc -t .

Note that only unlinking the service doesn’t stop it from running, it is just taking it away from the pool of services. Also note that terminating the service without first unlinking it from the service directory will cause it to restart immediately. daemontools is very strict on that and will try to keep all services running all the time.

As you have seen starting and stopping an image with daemontools is simple and can be easily scripted with a few shell scripts.

Copyright © 19 March 2024 Stéphane Ducasse, Lukas Renggli, C. David Shaffer, Rick Zaccone
This book is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 license.

This book is published using Seaside, Magritte and the Pier book publishing engine.