Go to page content

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.


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.


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.


Install Zotonic

  1. Download the zotonic_install script from the official repo:

    wget http://zotonic.googlecode.com/hg/zotonic_install
  2. Make the script executable with chmod +x zotonic_install

  3. 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

  1. 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.

  2. On the Zotonic User's shell: Return to the Root shell

  3. On the Root shell: Open an editor for /etc/hosts

    vim /etc/hosts

    In the editor for /etc/hosts: add an entry for blog blog

    Hit ESC and type :wq, then hit ENTER to save and return to the Root shell.

  4. 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.

  5. 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.

  6. In your web browser: Go to http://localhost:8000/ and log in with that password.

  7. 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

  8. In your web browser logged in to the Sites page: Visit the blog

    Click http://blog:8000/

    You should see an example blog site.

  9. 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.


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

Check /etc/hosts and make sure you have an entry like 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 on some hosting environments. By default the site skeletons set dbhost to

Repair a Broken Install

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

  1. From the Root shell: delete the Zotonic user:
    deluser zotonic && rm -Rf
  2. From the Root shell: delete the Zotonic user's home and all contents:
    rm -Rf /home/zotonic
  3. 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
  4. From the Root shell: remove the Zotonic PostgreSQL access rules:
    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
  5. 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.