In this post I will explain how to install Zotonic on OSX. If you are not really acquainted with Terminal.app, you will be after this!

First things first

You guys and gals need to download some software bundles to be able to start using Zotonic. You will need:

• Xcode (OSX development bundle)
• ImageMagick
• Erlang (preferably R13B04)
• PostgreSQL (preferably 8.4 or higher)
• The Zotonic source code

ImageMagick

ImageMagick has loads of dependencies and extra bundles. Because of that, it's a pain to install. But luckily MacPorts comes to the rescue. The MacPorts Project is an open-source community initiative to design an easy-to-use system for compiling, installing, and upgrading command-line stuff on OSX.

MacPorts will do all the dependency checks and installs them. Great stuff! First download MacPorts and install (don't worry, it's just a .pkg file).

After that type:

sudo port install ImageMagick

Erlang

To install Erlang you could use MacPorts again. To be honest I wouldn't do that. It takes ages to check al the dependencies and it does not install the latest version. Just download this one.

Let the fun stuff begin and become a real command-line wizard! After you've downloaded Erlang, just unpack it. Open terminal, type cd and drag Erlang's folder into the terminal. You will see something like this appear:

cd /Users/tim/Downloads/otp_src_R13B04/

Hit enter. Now that you are in, type the following commands to configure, compile and install Erlang. Note that each of them takes some time. Don't put them in the same time, just one after another. Have some coffee / beer. This takes a while :-)

./configure
make
sudo make install

PostgreSQL

PostgreSQL has an excellent installer. Just install the package. It could be that there are some issues with the memory management your Mac has and that PostgreSQL requires. If that is the case, just pm me on @timbenniks. If this starts to happen to more people, I will write up the solution here.

The Zotonic source code

You can just download the package from: http://code.google.com/p/zotonic/. If you are using Mercurial you can get Zotonic's tip like this:

hg clone https://zotonic.googlecode.com/hg/ zotonic

Now the good stuff!

After all this downloading and compiling, we need to get to business with Zotonic. Here's a list of what we need to do to make all of this happen.

• Database crap
• "Make" zotonic
• Zotonic's configuration

Database crap

Open pgadmin. Just do cmd+space and type pgadmin, your Mac will find it for you.

In the sidebar you will see a tree structure with just "Servers(1)" and then a PostgreSQL item under it. It should have a red cross. Double click that and type in the root password that you gave while installing PostgreSQL.

Afte this, click on the Databases item in the sidebar. The Postgres database will appear in the tree structure. Click on it and then click on the SQL button in the top bar.

Now a new window opens and we can query away! Note: remove the default text that is in the window. We need to make a new user, a new database and grant the new user access to the new database. Please do these queries one at the time. Just paste in and press the little green play button in the top bar.

CREATE USER zotonic WITH PASSWORD 'yourdbpassword';
CREATE DATABASE zotonic WITH OWNER = zotonic ENCODING = 'UTF8';
GRANT ALL ON DATABASE zotonic TO zotonic;
\c zotonic
CREATE LANGUAGE "plpgsql";

Make Zotonic

I would suggest that you put the Zotonic folder in the "Sites" directory that lives in your home folder. Please note that the root folder of Zotonic needs to be named zotonic at all times. Sorry for this, we are working on it :-P

No open terminal and "cd" into this folder. Obviously my name should be swapped with your username.

cd /Users/tim/Sites/zotonic
make

Zotonic's configuration

If you open the Zotonic folder you find a "priv" folder. Your projects will live in there. For now we will use Zotonic's default site. We need to rename the config for it to be read by Zotonic.

cp priv/sites/default/config.in priv/sites/default/config

Then, edit that file and change the values of dbpassword, sign_key_simple and sign_key:

% Configuration of the default site.
[
% This site is enabled or not.
{enabled, true},
 
% Atomic hostname, MUST be equal to the directory name of this site.
{host, default},
 
% Hostname for virtual host support
{hostname, "127.0.0.1:8000"},
{hostalias, "localhost:8000"},
% PostgreSQL database connection
{dbhost, "127.0.0.1"},
{dbport, 5432},
{dbuser, "zotonic"},
{dbpassword, "yourdbpassword"},
{dbdatabase, "zotonic"},

% Admin password, used during installation. You can change it later
{adminpassword, "admin"},

% Key used for signing image urls with image manipulations (crop, rotate, resize, etc.)
% A new key will force regenerating images, which takes cpu time and will fill your hard disk.
{sign_key_simple, <<"--change-me--">>},

% Key used for signing postbacks - this _must_ be a hard to guess key, otherwise your system is insecure.
% When not defined, then zotonic will generate a new key on every restart.
% When a new key is generated then all postbacks from old html pages will fail.
{sign_key, <<"--change-me--">>}
].

Make sure that the directory "priv/sites/default/files" and all its subdirectories are readable and writeable for the current user (Which is the user zotonic will run under).

chmod -R +rw /Users/tim/Sites/zotonic/priv/sites/default/files

Now start up Zotonic! Go to Zotonic root folder and type:

./start.sh

You see zotonic starting up, lots of messages pass by, and zotonic will install the initial database. When something goes wrong here, then it is almost always a problem with the database connection. Check your database configuration in the config file.

Point your browser to http://localhost:8000/ or logon as admin (the default password is 'admin') at: http://localhost:8000/admin/

When all done, then you can stop the Erlang shell with:

q().

That's all folks. Good luck messing around with Zotonic. The next post will be about setting up a new project and about the basics of dispatch rules and templates.