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

+

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.

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.

Line 35:

Line 35:

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.

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:

+

Assuming that sudo is installed, you can enable sudo for a regular user by running the following as root

−

root ALL=(ALL:ALL) ALL

+

<code>adduser REGULARUSERNAME sudo</code>

−

+

−

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

=== Configure Postfix ===

Line 49:

Line 43:

While installing the required packages, you will be asked to configure Postfix. Fortunately, [https://help.ubuntu.com/community/Postfix#Configuration 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.)

While installing the required packages, you will be asked to configure Postfix. Fortunately, [https://help.ubuntu.com/community/Postfix#Configuration 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 ===

+

=== Fix Postgresql 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:

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:

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

Line 130:

Line 119:

./gs_install_ubuntu.sh

./gs_install_ubuntu.sh

−

Right away you will be prompted 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).

+

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.

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 http://www.groupserver.org/groups/development and post a description of the problem you are having with the script.

+

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

== Start GroupServer ==

Line 168:

Line 157:

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.

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

+

== Set the E-Democracy Homepage Welcome Text ==

−

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.

+

The text at the top of the E-Democracy Homepage is set by the contents the file /groupserver/Content/initiat_site/welcome . If this file is empty or missing, GroupServer provides a default welcome statement. You can edit `welcome` to say whatever you would like.

−

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

+

== Set Metadata ==

−

# Go to ZMI

+

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

−

# 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:

+

# Create a Page Template named '''metadata.xml'''

−

+

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

−

# Go to ZMI

+

# Click Add and Edit

−

# Go to groupserver/Content/initial_site

+

# You will see a compliation error, that is fine.

−

# Create page template new_not_found.html

+

# Set the Content-Type to text/html

−

# Set Content-Type to text/html

+

# Click Save Changes

−

# Leave Body as default, or customize if you wish

+

−

+

−

== Make E-Democracy Homepage ==

+

−

+

−

# Go to ZMI

+

−

# Go to groupserver/Content/initial_site

+

−

# Create page template content_en

+

−

# Set the Content-Type to text/xml

+

−

# Place the following in it

+

−

+

−

<nowiki>

+

−

<div

+

−

xmlns:tal="http://xml.zope.org/namespaces/tal"

+

−

xmlns:metal="http://xml.zope.org/namespaces/metal"

+

−

metal:define-macro="division_homepage"

+

−

tal:define="site here/Scripts/get/division_object">

+

−

<tal:block define="userRoles python:user.getRolesInContext(site)">

+

−

<p tal:condition="python:'DivisionAdmin' in userRoles">

+

−

<p>

+

−

<bold class="label">As an admin you may:</bold>:

+

−

</p>

+

−

<ul>

+

−

<li>

+

−

<a href="/startgroup.html"><strong>Start</strong> a Group</a>

+

−

where people can join and post.

+

−

</li>

+

−

<li>

+

−

<a href="/charter"><strong>Change</strong> the default charter</a>

+

−

which will appear in a group.

+

−

</li>

+

−

<li>

+

−

<strong>View</strong> <a href="/stats.html">posting

+

−

statistics</a>.

+

−

</li>

+

−

+

−

<li>

+

−

<strong><a href="/admin_join_add_csv.html">Upload new members in bulk</a>.</strong>

+

−

</li>

+

−

+

−

<li>

+

−

<strong>Search</strong> for an existing <a href="/admin_search_people.html">forum member by e-mail</a>. Or <a href="https://zmi.onlinegroups.net/sites/edem/management_scripts/find/user_from_email/ZScriptHTML_tryForm">ZMI by e-mail</a> or <a href="https://zmi.onlinegroups.net/sites/edem/management_scripts/find/user_from_fn/ZScriptHTML_tryForm">profile name</a> for incomplete accounts, "invited" members not on a forum, etc. Requires separate ZMI login.

# Using the file field, browser to the zmi folder in your GroupServer folder, and select groups_intro.xml

−

<p tal:condition="userAuthenticated">

+

# Click Add and Edit

−

This page shows the online groups that are currently visible to you.

+

# You will see a compilation error, that is fine.

−

<a class="helpLink" href="/help/manual/#groupserver-managing-groups"

+

# Set the Content-Type to text/html

−

title="Managing Groups Help">[?]</a>

+

# Click Save Changes

−

</p>

+

−

<p tal:condition="not:userAuthenticated">

+

−

This page shows all the online groups (Issues Forums, etc.) that are visible to anyone. Generally, they are listed by country first and state second. For each state, the city and neighborhood forums are listed.

+

−

<span tal:condition="python:len(groups)==0">This site may contain

+

−

online groups that are visible only to logged in members;</span>

+

−

<a tal:attributes="title string:Please login to ${siteName}"

+

−

href="/login.html?came_from=/groups">Login</a> to see the forums

+

−

of which you are member or <a tal:attributes="title string:Register for ${siteName}"

+

−

href="/request_registration.html?came_from=/groups">register</a> and to join one or more forums.

# In /groupserver/Content/initial_site/groups, go to the Interfaces tab

−

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

+

# In the Provided Interfaces list on the left, click the checkbox next to Products.GSContent.interfaces.IGSContentFolder

−

# Save

+

# Click the Remove button

−

# 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 ===

=== Set category properties ===

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

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

−

# Create a property named 'categories' of type lines

+

# Add a property named 'categories' of type lines

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

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

−

# For each group that current exists

+

# For each group that currently exists

## Go into the group's folder

## Go into the group's folder

## View the group's Properties

## View the group's Properties

−

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

+

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

[[Category:Technology:GroupServer Development Reference]]

[[Category:Technology:GroupServer Development Reference]]

Latest revision as of 18:08, 29 January 2015

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 enable sudo for a regular user by running the following as root

adduser REGULARUSERNAME sudo

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 Authentication

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.

Set the E-Democracy Homepage Welcome Text

The text at the top of the E-Democracy Homepage is set by the contents the file /groupserver/Content/initiat_site/welcome . If this file is empty or missing, GroupServer provides a default welcome statement. You can edit `welcome` to say whatever you would like.

Set Metadata

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