This will fetch all of the files that are needed to build GroupServer and E-Democracy's custom eggs. This repo is also used to save and share changes to the buildout configuration. If you plan to develop on E-Democracy, always be sure to do a '''git pull''' to get the latest buildout configuration and eggs.

+

This will fetch all of the files that are needed to build GroupServer and E-Democracy's custom eggs. This repo is also used to save and share changes to the buildout configuration. If you plan to develop on E-Democracy, always be sure to do a ''git pull'' to get the latest buildout configuration and eggs.

== Set config.cfg ==

== Set config.cfg ==

Revision as of 14:18, 16 April 2013

This page attempts to walk you through the installation of GroupServer, E-Democracy's custom eggs, and the ZMI files required to make many of E-Democracy's pages work as they do on http://forums.e-democracy.org. The resulting local instance will not be a perfect replica of the pages and functionality that is currently hosted at http://forums.e-democracy.org, but it will provide an instance that you can use to develop on E-Democracy's code.

If you are interested in simply installing and developing on core GroupServer, please visit http://groupserver.org/downloads/ to download the most recent release and find instructions on how to install it.

Set Hosts

The absolute first thing you need to do is decide on the host name you will use to access your local instance of GroupServer/E-Democracy. Zope will behave differently based on what URL you use to access it, and it is best to choose a host name besides 'localhost'.

The host name used as an example through this document is 'e-dem-box'.

Once you have decided on a host name, you must edit /etc/hosts to add a reference for your host name. If your hosts file contains lines for both 127.0.0.1 and 127.0.1.1 (common in Debian and Ubuntu), add a reference for your chosen name on the 127.0.1.1 line.

Requirements

In the following list, the brackets [] contain the name of the apt package to get.

Debian based OS (Debian and Ubuntu both known to work)

Sudo [sudo]

Git [git]

Mercurial* [mercurial]

Python 2.7 [python2.7]

Postfix [postfix]

PostgreSQL [postgresql]

Nginx [nginx]

libxslt1-dev [libxslt1-dev]

It actually is possible to install E-Democracy without Mercurial. However, GroupServer's code is kept in Mercurial repos, so if you plan on doing any programming, you will need to have Mercurial installed to push your changes.

There is a great write-up by a user who attempted to install GroupServer on Scientific Linux (a variant of RHEL), which gives hope to those who want to install on rpm based distros. That said, it will probably be a lot easier to just install Ubuntu or Debian.

Sudo

If you are installing on Ubuntu, you can skip this section, since sudo is already installed and setup on Ubuntu.

Several of the steps that follow require root access. More importantly, gs_install_ubuntu.sh (the file that will drive a lot of the installation) assumes that sudo is available and configured for the user that runs it. In theory it is possible to run gs_install_ubuntu.sh as root, but this will mess up the permissions of all files created in the process, and will make it harder in the future to develop on E-Democracy as a regular user.

Assuming that sudo is installed, you can run the command visudo as root to edit the sudoers file, which controls how sudo works. In this file, find the following line:

root ALL=(ALL:ALL) ALL

and add a similar line for your regular system user (called 'super-programmer-hero' here):

super-programmer-hero ALL=(ALL:ALL) ALL

Save the file and exit the editor.

Configure Postfix

While installing the required packages, you will be asked to configure Postfix. Fortunately, Ubuntu provides an easy to follow example of how to configure Postfix that you can follow. The goal here isn't to make Postfix work (the linked to configuration doesn't fully succeed in doing that), but to provide GroupServer with enough of a Postfix installation/configuration to make it think it can send/receive emails (while developing, there will be other ways by which we can feed GroupServer emails and observe what it wants to send out.)

Fix Postgresql Transactions Limit and Authentication

Postgresql out of the box is not configured to support transactions, which GroupServer makes use of. Thus, you will have to edit /etc/postgresql/<version>/main/postgresql.conf so that it contains the following line:

max_prepared_transactions = 10

postgresql.conf should already contain a commented line that sets max_prepared_transactions, so just find that line, uncomment it and modify it so that max_prepared_transactions is any non-zero value.

Postgresql out of the box also does not allow you to login to a database by supplying a username/password to the command line client (psql). If you plan to do any development work and want to be able to peek inside the database (you probably will), this will become super annoying. To change this, edit /etc/postgresql/<version>/main/pg_hba.conf, find the following line:

local all all peer

change it to

local all all md5

And save.

Now restart postgresql:

service postgresql restart

Configure Nginx

You will want to add a site configuration for E-Democarcy. This is important for two reasons:

Its always good to create a configuration for any web-app you are developing on, since you may have multiple web apps you are working on at any given time

The Nginx configuration does two very important things:

It inserts a string into the URL of requests that tells GroupServer to apply E-Democracy's custom eggs/skin

It inserts a header that tells GroupSever which configuration instance to use

On your file system go to /etc/nginx/sites-available and create a file named 'e-democracy'. In e-democracy, insert the following:

Note that in the above we refer to the host name established earlier. Replace 'e-dem-box' with whatever host name you choose. Also note the value of INSTANCEID we insert; this must correspond to a configuration instance that we will create in gsconfig.ini later.

Save /etc/nginx/sites-available/e-democracy. Then go into /etc/nginx/sites-enabled and create a link to sites-available/e-democarcy:

ln -s ../sites-available/e-democracy e-democracy

Now restart Nginx:

service nginx restart

Get the E-Democracy Config Files

Visit E-Democracy's buildout-config repo and grab the URI that you wish to use. Then, in your development space on your file system, create a folder named 'e-democracy' and cd into it. Finally, clone the above repo. It's recommended that you clone into a folder with a name that makes sense, such as 'forums', 'forums.e-democracy.org', or 'groupserver'. Thus, your clone command might look like:

This will fetch all of the files that are needed to build GroupServer and E-Democracy's custom eggs. This repo is also used to save and share changes to the buildout configuration. If you plan to develop on E-Democracy, always be sure to do a git pull to get the latest buildout configuration and eggs.

Set config.cfg

Cd into the folder you just cloned into. Before we can run the installation script, we must first create and edit config.cfg. A config.cfg.sample is included in the buildout-config repo to make this a lot easier. Copy that:

cp config.cfg.sample config.cfg

Now edit config.cfg. Read the comments, and edit the values as necessary. host and zope_host should be set to the host name you selected earlier ('e-dem-box' in our example). Once you reach the Advanced Configuration Options section you should be done.

Run gs_install_ubuntu.sh

You should now be ready to run the installation script. Go to the folder that you cloned buildout-config into earlier and run the following command, as a regular user without sudo:

./gs_install_ubuntu.sh

If you haven't used sudo recently, you will be prompted right away for your sudo password. After that, grab some coffee/beer/food, cause this will take a bit of time (20 to 60 minutes depending on your system and Internet connection).

This script will install a few other required system packages. It will then create an environment in which to install GroupServer, and create the databases that GroupServer and Zope need. Finally, it will run buildout, which will fetch the 100+ eggs that GroupServer/E-Democracy require.

Because this relies on fetching so much from the Internet, it is possible the script will fail due to network errors/congestion. If this happens, simply re-run the script. If it continues the fail at the same step, visit either irc://irc.freenode.net/%23gsdevel (that's irc.freenode.net/#gsdevel)or http://www.groupserver.org/groups/development and let us know what problem you are having with the script.

Start GroupServer

Woohoo. At this point, you should now have an instance of GroupServer with custom E-Democracy eggs installed on your machine. Now it's time to start this thing up.

From the root folder of your local install (where you cloned buildout-config into earlier), simply run:

./bin/instance fg

If things go well, you will see some info scroll by in your console, concluding with the line 'INFO Zope Ready to handle requests'. Assuming this works well, you can now open your browser and enter the following (replacing 'e-dem-box' with whatever host name you choose earlier):

e-dem-box/groups

A page with the E-Democracy skin should appear that lists the groups currently available on your new local instance (which, at this point, will only be the Example Group.)

See Bare GroupServer

Earlier we configured Nginx so that requests to our selected host name would result in E-Democracy's custom eggs being used. If you want to see what GroupServer looks and acts like without the custom eggs, simply visit the same address at port 8080 (assuming you kept the default port in config.cfg). Thus, to see the bare GroupServer version of the groups page, you would visit:

e-dem-box:8080/groups

Go to the ZMI

All of the steps that follow require you to work in the Zope Management Interface, a backend interface that lets you manipulate some of the objects (users, groups, pages, etc...) that make up your local instance of GroupServer/E-Democracy.

To get to the ZMI, enter the following address in your browser:

127.0.1.1:8080/manage

This assumes you are on Debian/Ubuntu, which provides a 127.0.1.1 address. If you are not, then use 127.0.0.1 instead. If you try to visit the manage page via your selected host name (i.e. e-dem-box/manage or e-dem-box:8080/manage), you will get caught by GroupServer's authentication system, which does not properly authenticate you to access the ZMI.

Once you go to the above address, you will be prompted for a username and password. This corresponds to the zope_admin and zope_password settings in config.cfg, and default to admin/admin.

Create dummy error pages

There is a difference between the error handling systems of the production server and our development environment that causes the development environment to redirect to a non-existant page whenever an error/missing page is encountered. This makes reading errors in the log file a lot harder, because it becomes an infinate loop of not found pages.

So, we create a dummy new_unexpected_error.html in the ZMI:

Go to ZMI

Go to groupserver/Content/initial_site

Create page template new_unexpected_error.html

Set Content-Type to text/html

Leave Body as default, or customize if you wish

We also create a dummy new_not_found.html page in the ZMI. It won't display anything useful, but it will make reading the logs a lot easier:

Go to ZMI

Go to groupserver/Content/initial_site

Create page template new_not_found.html

Set Content-Type to text/html

Leave Body as default, or customize if you wish

Make the E-Democracy Homepage

Right now if you try to visit the root of your local instance of E-Democracy in your browser, you will get a File Not Found error, because the eggs do not include a homepage for E-Democracy (well, its slightly more complicated than that.) To fix that, first:

Go to ZMI

Go to groupserver/Content/initial_site

Create a Page Template named content_en

In the file field, browse to the zmi folder in your GroupServer folder, and select e-dem-homepage-template.pt

Click Add and Edit

You will see a compliation error, that is fine.

Set the Content-Type to text/xml

Click Save Changes

Now, if you visit the root of your local instance of E-Democracy, you'll see an E-Democracy skinned page. But we are not quite done yet. You'll notice that this page displays the same information/options regardless of whether you are logged in (hey, look at that, anonymous users can administer the site!). To fix that, we need to customize a property of the initial_site folder in the ZMI:

Go back to initial_site

Go to Properties tab

Delete the content that is currently in the introduction property. Do not save yet.

In your favorite text editor, open the file zmi/e-dem-introduction.pt in the GroupServer folder on your file system

Copy and Paste the content of e-dem-introduction.pt into the introduction property of initial_site

Click Save Changes.

Homepage JavaScript and Metadata

We're not quite done yet with E-Democracy's homepage. There is still some much needed javascript we need to add:

In /groupserver/Content/initial_site, create a Page Tempate named javascript.xml

In the file field, browse to the zmi folder in your GroupServer folder, and select javascript.xml

Click Add and Edit

Verify that Content-Type is text/xml, and that no compilation errors occurred.

Click Save Changes

And we have to add a little bit of HTML metadata:

Create a Page Template named metadata.xml

In the file field, browse to the zmi folder in your GroupServer folder, and select metadata.xml

Click Add and Edit

You will see a compliation error, that is fine.

Set the Content-Type to text/html

Click Save Changes

Make Digests Work

Go to ZMI

Go to /groupserver/Content/initial_site

Create a page template named digest_news.txt

Set Content-Type to text/html

Set body to the following (plain text):

Hello World

Create a page template named digest_news.xml

Set Content-Type to text/xml

Set body to the following:

<p>Hello World!</p>

Make /groups Work

Go to ZMI

Go to /groupserver/Content/groups

Click content_en to edit it

Using the file field near the bottom, browse to the zmi folder in your GroupServer folder, and select groups-template.xml

Click Upload File

Verify that Content-Type is text/xml, and that no compliation errors occurred.

<p>Select by place for community <a href="http://e-democracy.org/if">Issues Forums</a> or join the Online Communities and Project online groups that we host below.</p>
<p>No <a href="http://e-democracy.org/if">Issues Forum</a> in your community? <a href="http://e-democracy.org/contact">Contact Us</a> to propose one.</p>

Set up XSLT

Go to Properties tab of /groupserver/Content/initial_site/groups/content_en

Set transform_paths to: Presentation/Tofu/XHTML2/xslt/

Save

Set property named 'transform_html' to 'xhtml2-transform_body-content-only (xslt)'. Leave the other transform properties as 'do not use transform'

Save

Set category properties

In /groupserver/Content/initial_site/groups, go to Properties tab

Create a property named 'categories' of type lines

Once saved, enter a couple of categoires ('Test', 'Empty')

For each group that current exists

Go into the group's folder

View the group's Properties

Create a property named 'category' of type 'string', with a vlue equal to one of the categories entered above