Home » Documentation » General documentation » E-mail configuration The Zotonic shell command Install HTTPS Install Deployment The Query search-model Data model - ERD Module structure Directory structure Install

Working with sites

How a Zotonic site works, and how to create multiple sites.

What exactly is a Zotonic site?

Zotonic has the capability of serving more than one site at the same time. You can have multiple sites enabled, each which have their own set of templates, has its own database and its own URL dispatch rules.

A zotonic site is defined as a folder which lives in the priv/sites directory of the zotonic installation (or on a location which is symlinked to this folder, see the tip below).

The name of a zotonic site should be valid as a simple Erlang atom: it should be lowercase and only contain letters, numbers and the underscore character.

A zotonic site contains at least the following:

1. a config file
2. A file called sitename.erl

For the rest, a zotonic site functions exactly the same as a zotonic module, and, as such, can contain all kinds of resources (templates, dispatch rules, etc) that a normal module also has. See the module internals doc for more details on this.

The site config file

Most of the stuff in the site In the config file speaks for itself, like the database credentials. There are however a few config keys that need special explanation.

{host, sitename}
The {host} config key should always be equal to the name of the site which is the directory that the site is placed in. Like stated above, there must also exist a sitename.erl erlang module.

{hostname, "127.0.0.1:8000"}
This config key specifies the hostname+port part of the site's URL, to determine to which site an incoming request belongs to (since they all come in on the same port).

If you run zotonic in port 80, or if you put a web-frontend like varnish in front of your zotonic, you can leave out the port number, and just put the hostname in there.

The hostname does not specify on which port zotonic will listen! That information comes from the ZOTONIC_PORT environment variable, which is set to port 8000 by default.  Zotonic can (currently) listen on only one TCP port, and that port is specified in the 'zotonic.sh' startup script (and the start.sh debug script as well).

{hostalias, "www.example.com"}
The host aliases allow you to specify extra aliases for your site. This comes in handy if you have registered yoursite.com, yoursite.net and yoursite.org, and all want them to be served the same site. Mind you that zotonic will always redirect from a hostalias to the real hostname of the site. This is done to prevent content duplication: it is good web practice to let your content live on a single URL only.

Multiple sites in a Zotonic instance

Once you have configured and installed zotonic and have the default site running, creating a new site is quite easy. Let's create a site called "yoursite". For development purposes, we choose to let this site run on the url "http://yoursite.local:8000/".

1) Create an entry in your /etc/hosts file in which you let point yoursite.local to your loopback network interface:

sudo su
echo "127.0.0.1  yoursite.local" >> /etc/hosts

2) Create a directory called "yoursite", in zotonic's priv/sites directory:

cd zotonic/priv/sites
mkdir yoursite; cd yoursite

3) Copy the default.erl file from the default site as well:

cp ../default/default.erl yoursite.erl

Edit this file and change the -module(default). line to -module(yoursite).

4) In this directory, copy the config file from the default site, and edit it:

cp ../default/config .

In particular, you need to change {host, default} into {host, yoursite}, and {hostname, "http://127.0.0.1:8000"} into {hostname, "http://yoursite.local:8000"}

You should also change the configuration of the database, otherwise your 2 sites will use the same database configuration, whichis not a good idea. Look at the installer page to see how to create a postgres database and change the {dbdatabase, "zotonic"} accordingly.

5) Go back to the zotonic root, run make and start zotonic.

cd ../../..
make && ./start.sh

Zotonic should now be serving your new site. Point your browser to http://yoursite.local:8000/ to see if it works :-) You should see the "Welcome to Zotonic" page. Go to the admin and enable your new "yoursite" module.

Now, you should go ahead with two things:

1. Create some URL dispatch rules to anchor the pages for your site on
2. Create templates to make your site

Good luck!

 

Tip: use symlinks for easy development

You clearly want to separate your new site from the main zotonic repository. This migh seem hard because you have created your site in priv/sites/yoursite.

However, using symlinks you can put the yoursite folder anywhere on your filesystem. For instance in $HOME/yoursite. If you put it there, just symlink it from the priv/sites directory like this:

cd $HOME/zotonic/priv/sites
ln -s $HOME/yoursite

When you now start zotonic, everything will work as normal, and your new site lives outside the repository. Now it's become easy to put your site under version control, for instance.

Tip: multiple sites using one database

From Zotonic 0.4, you can use a single PostgreSQL database to host multiple web sites. This does not work using table prefixing (like Wordpress does for example), but instead, Zotonic uses postgres' native feature database schemas to support this.

A database schema is basically another database inside your database: it's a namespace in which tables live. By default, your tables live in the namespace called PUBLIC, but it's quite easy to create another schema:

CREATE SCHEMA anothersite;
GRANT ALL ON SCHEMA anothersite TO yourdatabaseuser;

And then in your site config put a {dbschema, "anothersite"} entry next to the regular database config keys. Restart zotonic and off you go.