Table of Contents:

Exploring the GLASS Virtual Appliance

To get extensive information about using Seaside on GemStone/S, visit Dale's blog, especially the posts about the Virtual Appliance.

When you open the GLASS Virtual Appliance in VMware, it runs Seaside 2.8 on GemStone/S. Begin by exploring the system from the Seaside page. Browse GemStone source code using the classbrowser. Run some of the script.aculo.us tests, and then use the "view source" links to see how simple they were to code. Try out the Pier Content Management System. If you encounter something that hasn't yet been implemented, or any other errors, just use the back button to escape.

If you have an existing Squeak Seaside application, porting it to GemStone/S Seaside should be straightforward. Start Squeak by using "Run Squeak" in the toolbar on the GLASS Virtual Appliance. Connect to GemStone by clicking the login button. The green buttons in the resulting window perform various GemStone functions. Details are available in Dale's Terse Guide to the GLASS Tools.

A GemSource code repository you can use to store GemStone/S Seaside projects is available at http://seaside.gemstone.com/ss/

If you are unfamiliar with Seaside or Squeak, visit seaside.st or squeak.org to get up to speed.

NAT vs. Bridged VMware Network Settings

VMware appliances have several possible network settings. NAT may work better if you use a laptop, or connect to a VPN (Virtual Private Network). However, Bridged is the only setting that will allow you to connect to the GLASS Virtual Appliance from other machines on your network.

Installing the GemStone/S Web Edition on Linux

This section covers installing the GemStone/S 2.3 Web Edition to run under your own user account. If you are not comfortable setting up Apache, FastCGI, and performing other low level Linux system administration tasks, you should use the GLASS Virtual Appliance instead. These instructions are not intended for deployment, as they don't cover automatic startup on boot, setting up services to connect from other hosts on your network, or configuring Apache. The installation is done from a terminal session as a non-root user, but you'll need to be able to use sudo for some commands that require root permissions.

If you're comfortable using shell scripts, download and execute installGemstone2.3-Linux.sh instead. It automates everything you would do manually below, but includes error checks that prevent overwriting any existing files or settings. If /opt/gemstone/product already exists, you should rename or remove it first. As I would suggest for any script you download, look it over before executing it. It contains comments that explain what it does.

Setup your Linux OS to run GemStone/S

You need to allow GemStone/S to use more shared memory than the default. Use these commands to list some important memory settings: 

 echo Total memory = `awk '/MemTotal:/{print($2);}' /proc/meminfo` bytes
 echo Max shared memory segment size = `cat /proc/sys/kernel/shmmax` bytes
 echo Max shared memory allowed = `cat /proc/sys/kernel/shmall` pages

We recommend setting shmmax to the smaller of 75% of Total Memory or 1GB, and leaving shmall at the Linux default of 2097152. These commands set them to the recommended value for a machine that has 1GB of RAM: 

 sudo bash -c "echo 805306368 > /proc/sys/kernel/shmmax"
 sudo bash -c "echo 2097152 > /proc/sys/kernel/shmall"

Note: The previous commands only set the maximum you are allowed to use, they don't actually allocate anything. If you don't want to run these commands every time you start GemStone, execute the following lines. This will set the maximum shared memory every time you boot. This is highly recommended, as GemStone/S will not start if the maximum is reset to the default. 

 sudo bash -c "echo kernel.shmmax = 805306368 >> /etc/sysctl.conf"
 sudo bash -c "echo kernel.shmall = 2097152 >> /etc/sysctl.conf"

Create some directories that GemStone/S expects, and make them writable: 

 sudo mkdir -p /opt/gemstone /opt/gemstone/log /opt/gemstone/locks
 sudo chown $USER:${GROUPS[0]} /opt/gemstone /opt/gemstone/log /opt/gemstone/locks
 sudo chmod 770 /opt/gemstone /opt/gemstone/log /opt/gemstone/locks

Install the GemStone/S software

Download GemStone/S, if you haven't already done so: 

 wget http://glass-downloads.gemstone.com/gss23/GemStone64Bit2.3.0-x86_64.Linux.zip

Unzip the downloaded archive into /opt/gemstone/, then link it to /opt/gemstone/product: 

 unzip -q -d /opt/gemstone GemStone64Bit2.3.0-x86_64.Linux.zip
 ln -sf /opt/gemstone/product/GemStone64Bit2.3.0-x86_64.Linux /opt/gemstone/product

Copy an initial extent to the Seaside data directory: 

 cp /opt/gemstone/product/bin/extent0.seaside.dbf /opt/gemstone/product/seaside/data/extent0.dbf
 chmod 644 /opt/gemstone/product/seaside/data/extent0.dbf

You can check which build number you installed. 

 cat /opt/gemstone/product/version.txt

GemStone/S is now installed, and you can jump to the section on Running the GemStone/S Web Edition.

Installing the GemStone/S Web Edition on Mac OS X Leopard

Note: the GemStone/S Web Edition does not work on Mac OS X Tiger – download the GLASS Virtual Appliance instead.

This section covers installing the GemStone/S 2.3 Web Edition to run under your own user account. If you are not comfortable setting up Apache, FastCGI, and performing other low level system administration tasks, you should use the GLASS Virtual Appliance instead. These instructions are not intended for deployment, as they don't cover automatic startup on boot, setting up services to connect from other hosts on your network, or configuring Apache. You'll need to have admin permissions for portions of the initial setup. The installation is done from a terminal session, similar to a Linux installation. We'll come up with a more Mac-oriented process before final release.

If you're comfortable using shell scripts, download and execute installGemstone2.3-MacOSX.sh instead. It automates everything you would do manually below, but includes error checks that prevent overwriting any existing files or settings. If /opt/gemstone/product already exists, you should rename or remove it first. As I would suggest for any script you download, look it over before executing it. It contains comments that explain what it does.

Setup your Mac OS to run GemStone/S

You need to allow GemStone/S to use more shared memory than the 4MB default. Use this command to list some current settings: 

 sysctl hw.cpu64bit_capable hw.memsize; ipcs -M

We recommend setting kern.sysv.shmmax to the smaller of 75% of hw.memsize or 1GB, and shmall to shmmax/2048. This command sets them to the recommended value for a machine that has 1GB of RAM: 

 sudo sysctl -w kern.sysv.shmmax=805306368 kern.sysv.shmall=393216

Note: The previous command only sets the maximum you are allowed to use, it doesn't actually allocate anything. If you don't want to run this command every time you start GemStone, put the following in a file called /etc/sysctl.conf. This will set the maximum shared memory every time you boot. This is highly recommended, as GemStone/S will not start if the maximum is reset to the default 4MB. 

 kern.sysv.shmmax=805306368
 kern.sysv.shmall=393216
 kern.sysv.shmmin=1
 kern.sysv.shmmni=32
 kern.sysv.shmseg=8

Create some directories that GemStone/S expects, and make them writable: 

 sudo mkdir -p /opt/gemstone /opt/gemstone/log /opt/gemstone/locks
 sudo chown $USER:${GROUPS[0]} /opt/gemstone /opt/gemstone/log /opt/gemstone/locks
 sudo chmod 770 /opt/gemstone /opt/gemstone/log /opt/gemstone/locks

Install the GemStone/S software

Create and change to the directory you want to contain the GemStone tree, then download GemStone/S. If you have already downloaded the zip file, make sure you've moved it to this directory and skip the curl command. 

 mkdir ~/GemStone
 cd ~/GemStone
 curl -O http://glass-downloads.gemstone.com/gss23/GemStone64Bit2.3.0-x86_64.MacOSX.zip

Unzip the downloaded archive in the current directory, then link it to a /opt/gemstone/product: 

 unzip -q GemStone64Bit2.3.0-x86_64.MacOSX.zip
 ln -sf `pwd`/GemStone64Bit2.3.0-x86_64.MacOSX /opt/gemstone/product

Copy an initial extent to the Seaside data directory: 

 cp /opt/gemstone/product/bin/extent0.seaside.dbf /opt/gemstone/product/seaside/data/extent0.dbf
 chmod 644 /opt/gemstone/product/seaside/data/extent0.dbf

You can check which build number you installed. 

 cat /opt/gemstone/product/version.txt

GemStone/S is now installed. You can try it out in the next section.

Running the GemStone/S Web Edition

Define GEMSTONE environment variables. If you don't want to do this every time you run GemStone/S, add the command to your .bashrc. 

 source /opt/gemstone/product/seaside/defSeaside

Start a netldi process, then a stone process. 

 startnet
 startGemstone

Make sure everything is running OK: 

 gslist -lcv

Exploring Seaside on GemStone/S

You can test Seaside by running Hyper from the command line, even though you'd normally use Apache, or start Hyper from a GemStone/S Workspace in Squeak. Note: While Hyper can be used to explore Seaside on GemStone/S, it is not suitable for serious development – that requires Apache load balanced to several GemStone VM's. If you don't know how to set up Apache, you should use the GLASS Virtual Appliance instead. Since the following command will never return, you'll need to enter ctl-C in the terminal window running Hyper to execute a soft break and regain control of the terminal window. 

 startSeaside_Hyper 50081

Once Hyper is running, you can access Seaside from a web browser on that machine using the links below. Take a look at some of the open source Scriptaculous tests. Try the "effects" or "drag and drop" tabs. There is a "view source" link below each example. Play with the Pier CMS from Lukas Renggli. Note: The Seaside config username/password is currently admin/swordfish, but it will be changed to the more standard seaside/admin in the next release. 

 http://localhost:50081/seaside
 http://localhost:50081/seaside/tests/scriptaculous/
 http://localhost:50081/seaside/pier/

When you're ready to shut down, enter ctl-C in the terminal window running Hyper, then stop the stone and netldi processes: 

 stopGemstone
 stopnetldi

Connecting to GemStone/S from Squeak

Download the GemTools zip file. It contains everything you need to connect to GemStone/S 2.3 and start developing a Seaside application – Squeak image/changes, GemStone library, even a Squeak VM. It runs on Mac OS X, Windows, and Linux. It's set up to connect to the GLASS Virtual Appliance, so you'll need to change "glass" in the login window to "localhost" to make it work with the native Web Edition. 

 curl -O http://seaside.gemstone.com/squeak/GemTools-2.3.zip

After you unzip the file and get it running, refer to Dale's Terse Guide to the GLASS Tools to get started.

Connecting to GemStone/S from a different machine

If you need to connect to GemStone/S from a different machine than the one it is running on, "localhost" will not suffice for a hostname. A hosts file is the simplest way on Linux or Mac OS X to specify an IP address (e.g. 192.168.1.100) to use for a hostname (e.g. frodo or frodo.example.net) without checking DNS. Note: To use this your computer must have a static IP address that never changes. Put a line like the following in /etc/hosts, substituting your real IP address and hostname: 

 192.168.1.100     frodo       frodo.example.net

You will also need a way to find the netldi service port. The simplest way to achieve this is to put a line like the following in your /etc/services file. It needs to have the same name and port number on every system you want to connect from. 

 gs64ldi           50377/tcp   #GemStone/S 64 Bit

It is possible you cannot connect to the NetLDI port due to firewall settings on your machine. You'll need to allow TCP access to the NetLDI port. If this doesn't make sense to you, talk to a local sysadmin, search for more complete information on the web, or read the GemStone/S System Administration Guide.

Running multiple copies of the GemStone/S Web Edition

This describes running two separate instances of GemStone/S on a single machine. This can useful if you want to have a separate GemStone/S system to experiment with, similar to running multiple Squeak images.

Make sure GemStone is shut down. Copy /opt/gemstone/product/seaside/data to another location. Make a copy of /opt/gemstone/product/seaside/defSeaside and modify it to override the GEMSTONE_NAME and GEMSTONE_DATADIR environment variables set by /opt/gemstone/product/seaside/etc/gemstone.conf.