Install on APT-based systems

[0.7+] Step by step guide to installing Zotonic on a Debian Squeeze or Ubuntu-based system.

NOTE: these instructions are for installing the development version of Zotonic, not the release version. However, the core developers use this version for their own projects so I consider it a safer bet.

Why

This guide exists to provide a clear set of directions to get a new Zotonic server off the ground. By the end of the guide you should have a working Zotonic server with an example blog site running and ready to play with.

Assumptions

Readers of this guide are assumed to be comfortable using the command-line. You should be comfortable doing command-line installation using apt-get and know some basics of shell scripting like chmod. The guide will walk you through step-by-step, but this knowledge will help if something goes wrong.

How

Install Zotonic

Download the zotonic_install script from the official repo:
```
wget http://zotonic.googlecode.com/hg/zotonic_install
```
Make the script executable with chmod +x zotonic_install
On the Admin User's shell: Run zotonic_install as Root
```
sudo ./zotonic_install
```

Verify Install

Visit http://localhost:8000/ in your browser

You should see a Sites on this Zotonic Server page with no sites listed

Add a Blog to Your Zotonic Server

On the Zotonic User's shell: Add a basic blog to your Zotonic server
```
zotonic createdb blog
zotonic addsite -d zotonic_blog blog
```
NOTE: -d zotonic_blog should not be necessary, but zotonic addsite needs be fixed first to use site-specific databases by default. Until then you'll need to specify it manually.
On the Zotonic User's shell: Return to the Root shell
```
exit
```
On the Root shell: Open an editor for /etc/hosts
```
vim /etc/hosts
```
In the editor for /etc/hosts: add an entry for blog
```
127.0.0.1 blog
```
Hit ESC and type :wq, then hit ENTER to save and return to the Root shell.
In your web browser: Visit http://localhost:8000/
You should see a Sites on this Zotonic Server page with http://blog:8000/ listed as Stopped
In fact, if you had the browser visible you'd see Zotonic pick up the site immediately.
On the Zotonic User's shell: Get the Sites page password
```
cat priv/config | sed -nE 's/^\s*\{\s*password\s*,\s*"(.*?)".*/\1/p'
```
You should see something like bRM8FLG2 for example. Your Sites page password will be different.
In your web browser: Go to http://localhost:8000/ and log in with that password.
In your web browser logged in to the Sites page: Start the blog
Click start by http://blog:8000/
After a short delay the status should be green and Running
In your web browser logged in to the Sites page: Visit the blog
Click http://blog:8000/
You should see an example blog site.
In your web browser: log into the admin interface at http://blog:8000/admin
Log in with username and password admin
You should see the Zotonic admin interface with Pages and other links on the left side and a Dashboard of the latest content changes in the center.

Troubleshooting

Browsers can't connect to http://blog:8000/

Check /etc/hosts and make sure you have an entry like 127.0.0.1 blog.

Zotonic won't start and shows errors when running zotonic debug

Check PostgreSQL Authentication Config (pg_hba.conf)

If you get connection failures when starting Zotonic you should double-check pg_hba.conf and make sure to /etc/init.d/postgresql reload to make sure it gets loaded.

Check Hosts File for Unusual Localhost Mapping

Check /etc/hosts: Another oddity Julian Schrittwieser discovered was that /etc/hosts can map localhost to something other than 127.0.0.1 on some hosting environments. By default the site skeletons set dbhost to 127.0.0.1.

Repair a Broken Install

If you are really stuck and the above troubleshooting steps don't work, try repairing the install:

From the Root shell: delete the Zotonic user:
```
deluser zotonic && rm -Rf
/home/zotonic
```
From the Root shell: delete the Zotonic user's home and all contents:
```
rm -Rf /home/zotonic
```
From the Root shell: log in as postgres and remove the Zotonic databases and role:
```
su -l postgres
dropdb zotonic
dropdb zotonic_blog
dropuser zotonic
```

From the Root shell: remove the Zotonic PostgreSQL access rules:

f=`tempfile`
cat /etc/postgresql/8.4/main/pg_hba.conf | grep -v zotonic | grep -v Zotonic > $f
cat $f > /etc/postgresql/8.4/main/pg_hba.conf
/etc/init.d/postgresql reload

Now, carefully, re-execute all steps from Step 3 through 9 above. You will note a few error messages when you execute zotonic_install. If they refer to PostgreSQL issues, ignore them.

This page is part of the Zotonic documentation, which is licensed under the Apache License 2.0.