Administrator's Guide

Work in progress !

1. Installation

See instructions in Download section to download, install and run a demo site.

1.1. Installation on collocated server

It is recommended to install a complete Smaltalk envirnoment on server to have complete development environment there too. Then you access it via VNC. Of course you need to have a windowing environment on server up and running. That way you'll be able to update your web apps the easiest way. For Aida on VisualWorks set up a Store version control system and connect both your server and your development machine to Store. You can publish changes from your development machine to Store and then load them to a server. This can of course be done live, without restarting Aida on server, because we are on Smalltalk, a dynamic programing language...

On a server you also need one IP with port 80 available and reserved only for Aida/Web server. You can run more than one website on that IP of course thanks to Aida/Web virtual website support.

You also need access to the DNS server to add DNS entries for your websites.

2. Start/stop server or website

To start or stop entire server, that is all sites, evaluate:

SwazooServer start.
SwazooServer stop.

To start or stop a specific site with name 'mysite', evaluate:

(AIDASite named: 'mysite') start.
(AIDASite named: 'mysite') stop.

3. Adding a new site

3.1 Changing settings of default website

After Aida is installed, a default website named 'aidademo' is opened, with host, ip and port as follows:

host: '*' ip: '*' port: 8888

The star '*' means that default site is started on all IP addresses on your machine (localhost included), port 8888 and with any hostname in Url is accepted. This is most general setup and works on any computer. But you must change this default before you can add any new site! Change it at least to the host: 'locahost' ip: '127.0.0.1' port: 8888 :

AIDASite default: 'aidademo'.
AIDASite default 
     stop;
     host: 'localhost' ip: '127.0.0.1' port: 8888;
     start.

3.2 Adding a site accessible from public internet

First you need to register your hostname and IP address on some DNS server. Don't forget to change settings of default site first, see 3.1. Then use a following script to add a new virtual web site to your server and start it:

name := 'mysite'.
hostname: 'mysite.company.com'. "add in your DNS server first!"
ip := 'myserver.company.com'. "also add to DNS server first!"
styleClass := 'DefaultWebStyle'. "change if you provide your own subclass"

AIDASite newNamed: name.
(AIDASite named: name) host: hostname ip: ip port: 80.
(AIDASite named: name) styleClass: styleClass.
SwazooServer startSite: name.

If you run the new site on Linux and on ports below 1024, be sure to run a whole Smalltalk image as root. Root is namely needed to run on port 80. This has security implications of course, so be careful. Chroot jail is one of possible protection here. 

3.3 Adding a site on locahost

Sometimes is handy for development and testing to run a new site locally, before it is put on public internet. Don't forget to change settings of default site first, see 3.1. If you want to add a site which is accessed only locally, from your computer (as demo site is) you need to register you hostname in local hosts file:

• on Linux: /etc/hosts
• on Windows: c:\\WINDOWS\\system32\\drivers\\etc\\hosts

Put in hosts file something like:

127.0.0.1    www.mysite.com

Now you can add new site with modified script above or a bit simplified one:

AIDASite newNamed: 'mysite'.  
(AIDASite named: 'mysite') host: 'www.mysite.com' ip: '127.0.0.1' port: 8888.
(AIDASite named: 'mysite') start.

A new site is now accessed (from local machine only) at http://www.mysite.com:8888 .

4. Registering a domain root

To access your domain model from the web, you need to set a url at least to a root object of fomain model. Urls to other domain objects will be created automatically. Besides that it is also recommended to register domain root to AIDASite user services.

• Let we register myDomainRoot object as an user service and name it #myDomain, then set an url /my-domain.html :

(AIDASite named: 'mysite') addUserService: myDomainRoot named: #myDomain
(AIDASite named: 'mysite')  register: myDomainObject onUrl: '/my-domain' 

It is also handy to write a method for registering and also accessing a domain root from your AIDASite. Here is an example, where we actually create our domain with MyDomainRoot new :

AIDASite >> myDomain

^self userServices at: #myDomain ifAbsent: 
     [self addUserService: MyDomainRoot new named: #myDomain.
     self register: self myDomain onUrl: '/my-domain'.
    ^self myDomain]

5. Styling your site

Class WebStyle in package WEB-Components holds a default CSS style for Aida/Web sites. CSS is composed of css\* methods, which are added together (alphabetically!) and presented as one CSS sheet: /screen.css. There are also cssPrint\* methods for separate print style: /print.css.

Subclass DefaultWebStyle holds a complete styling for a demo website, which is started after installation.

5.1. Changing default styling

• subclass WebStyle (or DefaultWebStyle)with your own style class (say MyWebStyle)
• change or add css\* and cssPrint\* methods
• Register your style class on your site:

  • (AIDASite named: 'mysite') styleClass: 'MyWebStyle'

6. Static file serving

Aida includes a static web server, which is very handy for serving additional static content from files. Due to streaming it is able to serve arbitrary long files like movies.

Static web server is enabled by default and expects files to reside in a subdirectory 'static' from an image directory. To change this home directory, evaluate something like:

(AIDASite named: 'mysite') homeDirectory: '/home/website/public_html'

URL of the file in the home directory is like htp://my.server.org/myfile.avi. Use subdirectories in home directory to have a hierarchy of a static file content.

Be careful not to have something registered on the same Url in URL resolver, Method resources or Method libraries. Request routing regards static file content as the lowest priority.