GroupServer Installation
| Authors: | Michael JasonSmith
Richard Waid Alice Murphy Dan Randow |
|---|---|
| Contact: | Michael JasonSmith <mpj17@onlinegroups.net> |
| Date: | 2011-12-19 (see History) |
| Organization: | GroupServer.org |
| Copyright: | This document is licensed under a Creative Commons Attribution-Share Alike 3.0 New Zealand License by OnlineGroups.Net. |
We wrote this documentation for people with moderate experience in Linux system administration. Installation can be tricky: you have to configure at least email sending, the web interface, and persistent storage. All these systems must work or installation will fail.
If you get stuck, please ask us questions in GroupServer Development. Other more detailed guides would be gratefully accepted.
1 Quick Start
Install the required packages (see Requirements).
Download the latest version of GroupServer from <http://groupserver.org/downloads> and extract the archive (see Download).
Ensure that the user that will run GroupServer can create databases in PostgreSQL (see Configure PostgreSQL).
Create a new hostname for your GroupServer site. Yes, you will need a new one (see Pick a Host Name).
Edit instance.cfg (see Configure Zope).
Run the following (see Run Buildout):
$ virtualenv --no-site-packages -ppython2.6 . $ ./bin/easy_install -U setuptools && ./bin/python bootstrap.py $ ./bin/buildout -v
$ ./bin/instance fg
Visit your new site.
Later you can further configure the Email Server and add an optional Web Proxy.
You can remove GroupServer in three steps.
2 Requirements
GroupServer is developed on Ubuntu, and is know to run on CentOS. We will gladly accept any modifications you have that will make GroupServer run on more platforms.
Below the packages that are required to install GroupServer are listed for Ubuntu, CentOS, and RedHat Enterprise Linux.
| Packages | ||
|---|---|---|
| System | Ubuntu | CentOS 6.1 or RHEL 6.1 |
| Python 2.6 | python2.6 | python-devel |
| python2.6-dev | python-setuptools | |
| python-virtualenv | See Virtualenv on CentOS below. | |
| GNU C++ | g++ | gcc-c++ |
| Make | make | make |
| PostgreSQL Database | postgresql | postgresql |
| postgresql-server-dev-8.4 | postgresql-server | |
| libpq-dev | postgresql-libs | |
| postgresql-devel | ||
| Postfix Email Server | postfix | postfix |
| postfix-dev | ||
| Compression | libzzip-dev (from universe) | zlib |
| lib64z1-dev (from main) | zlib-devel | |
| XML Support | libxml2 | |
| libxml2-devel | ||
| XSLT Support | libxslt | |
| libxslt-devel | ||
To install all the above libraries under Ubuntu run the following command:
$ sudo apt-get install python2.6 python2.6-dev python-virtualenv g++ \ build-essential postgresql postgresql-server-dev-8.4 libpq-dev \ postfix postfix-dev libzzip-dev lib64z1-dev
2.1 Virtualenv on CentOS
To get virtualenv for CentOS or RHEL you will need to execute the following command after installing the above packages:
# easy_install virtualenv
This command uses the easy_install system, which is part of Python, to download and install the virtualenv package.
3 Download
GroupServer is distributed as a tar-file. To download the latest version of GroupServer visit <http://groupserver.org/downloads> and click Download. You must then extract GroupServer from the tar-file into a directory such as /opt, /home or /usr/local.
When the tar-file is extracted a new directory will be made. This directory contains the configuration files for GroupServer. In addition, the installation process will download and install some dependencies into the directory (see Run Buildout). Finally, GroupServer will be run from the same directory (see Start Zope).
Note: You may need to be the root user to extract the archive. If you do then you must change the ownership of the new GroupServer directory and all of its contents. GroupServer can only be run by users with normal privileges.
4 Configure PostgreSQL
Database administrators who know what they are doing can ignore this section. For humble administrators that just want to try GroupServer, life is easier if the excellent security in PostgreSQL is disabled, by making the authentication methods trust in all cases. To do this, change the bottom few lines in the /etc/postgresql/8.4/main/pg_hba.conf file (you will have to be root to modify it):
# Database administrative login by UNIX sockets local all postgres trust # TYPE DATABASE USER CIDR-ADDRESS METHOD # "local" is for Unix domain socket connections only local all all trust # IPv4 local connections: host all all 127.0.0.1/32 trust # IPv6 local connections: host all all ::1/128 trust
PosgreSQL will have to be restarted after the pg_hba.conf file has been modified:
$ sudo service postgresql restart
For those who value privacy, security and trust, and want to understand more of PostgreSQL we recommend PostgreSQL User Administration by David Pashley.
5 Set up Zope
Installing Zope is done in four steps: first pick a host name, then configure Zope, run buildout to install Zope, and finally start Zope.
5.1 Pick a Host Name
Your new site needs its own hostname. The name needs to be known to the web browser that you will use to access the site. It will pass the name to Zope so it knows which GroupServer site to serve. (Zope can serve multiple sites, as well as its web-based management system.) For a trial system, the name can be set up in the hosts(5) file.
Edit /etc/hosts as root.
Add the new host name to the localhost entry, which is normally the first one. For example, to add the name gstest change the line to the following:
127.0.0.1 localhost gstest
Save the hosts file.
5.2 Configure Zope
The configuration of Zope is carried out by modifying instance.cfg, which is located in the root of the GroupServer folder. The cfg file is interpreted by the Python ConfigParser module, which accepts a syntax very similar to Windows INI files.
5.2.1 GroupServer
All the user-configurable options are in the config section of instance.cfg. The first set of options the setup of the initial GroupServer instance.
- host
- The domain name used by your new GroupServer instance. It must be the same as what you picked a host name earlier (see Pick a Host Name).
- port
- The port that your new GroupServer instance will run on. By default it is 8080, which is the same as the zope_port. To run on any other port you will need to set up a web proxy.
- admin_email
- When GroupServer is installed, an example site and group are created. So you can use the administration functions you must log in as an administrator. This is the email address of that administrator. Posts to the example group will be sent to the administrator at this address. In addition, this email address will be used to log into the new site.
- admin_password
- The password of the administrator of the new GroupServer site. The password will be used to log in, and can be changed after the site has been created.
- user_email
- The email address of the normal user that is created along with the new GroupServer site. The normal user is a member of the same group as the administrator, but the user has no permission to alter the site. Posts to the example group will be sent to the user at this address. In addition, this email address will be used to log in to the new site. The email address for the normal user must be different to the email address for the administrator.
- user_password
- The password for the normal user of the new GroupServer site. The password will be used to log in, and can be changed after the site has been created.
- support_email
- The email address where support messages are sent, and were email notifications are send from. For testing this can be set to your own email address.
- timezone
The timezone that will be used to represent dates and times. It defaults to Coordinated Universal Time (UTC) but can be set other zones including
- Pacific/Auckland
- Europe/London
- America/New_York
- America/Los_Angeles
- …and others.
5.2.2 SMTP
GroupServer sends email using SMTP. The four smtp options contain the information required to comminicate with the SMTP server.
- smtp_host
- The SMTP host that will be used to send notifications from GroupServer. It defaults to localhost, assuming you will be running a local SMTP server.
- smtp_port
- The port that the SMTP host will be listening to. Defaults to the standard SMTP port, 25.
- smtp_user
- The user-name that the SMTP host requires to send email messages. It defaults to no user name.
- smtp_password
- The password the SMTP host requires to send email messages. It defaults to no password.
5.2.3 Zope
The zope options configure how you will access the Zope Management Interface (ZMI).
- zope_host
- The host that will run Zope. It defaults to the local machine.
- zope_port
- The IP port that Zope will listen to. It defaults to 8080. Zope will have to run as root to use port 80, and this is discouraged.
- zope_admin
- The name of the user who will administer Zope.
- zope_pass
- The password for the Zope administrator. It can (and should) be changed after GroupServer has been set up. (However, if you change the password after installation you will also have to change the scripts that Postfix uses to communicate with GroupServer, as they store the password too, see Set up Scripts; we realise that the passwords should not be stored in the scripts.)
5.2.4 PostgreSQL
The final set of options deals with configuring the connection to the PostgreSQL database.
- pgsql_host
- The host that runs the PostgreSQL database. It defaults to the local machine, localhost.
- pgsql_port
- The IP port that PosgtreSQL listens to. It is set to the default port for Ubuntu; it may be 5433 if multiple versions of PostgreSQL are installed.
- pgsql_dbname
- During installation a database will be created in PostgreSQL. The pgsql_dbname option defines the name of the database.
- pgsql_user
- The name of the database user that will connect to the GroupServer database and modify the data. The database user is separate from the other users on the system, including those that log into the computer and those in Zope. The value of this option can be set to anything, but the default is usually good enough. Note that the pgsql_user must be set to a value that is different to the value of pgsql_admin.
- pgsql_admin
- The name of the admin of PostgreSQL, used to create the PostgreSQL user. The default is the name of the administrator under Ubuntu.
- pgsql_password
- The password required to attach to the PostgreSQL database as the pgsql_user. The default is blank, which means that no password is required.
5.3 Run Buildout
Buildout is the python-based system that we use to download and installs Zope, GroupServer, and all the libraries that they both require. To run buildout, first create a virtual Python installation in the directory that contains the GroupServer installation:
$ virtualenv --no-site-packages -ppython2.6 .
This creates a sandbox for buildout with its own version of Python 2.6, placed in ./bin/. When buildout runs it will install all the packages in the sandbox. The version of Python that is maintained by your Linux distribution will be untouched.
Next, update the setuptools package. To do this, use the local version of easy_install:
$ ./bin/easy_install -U setuptools
The buildout system has to be initialised next:
$ ./bin/python bootstrap.py
Finally, run buildout:
$ ./bin/buildout -v
Buildout takes a while, as it will download and install all the requirements for GroupServer (around 30MB of packages) including:
It is a good idea to make a cup of coffee, or go to lunch, while buildout processes.
5.4 Start Zope
To start the Zope instance run the following command:
$ ./bin/instance fg
Zope will have started when the message Zope Ready to handle requests is displayed in the terminal.
You should be able to view your GroupServer site at http://{host}:{zope_port}. If you kept the defaults, the address will be <http://gstest:8080>.
- The host is the one you picked earlier (see Pick a Host Name).
- The port is the one that Zope listens to (see Configure Zope).
Use Control-c to stop Zope.
5.4.1 Running Zope as a Daemon
It may be more convenient to run Zope in the background, as a daemon. To run Zope as a daemon run the following command:
$ ./bin/instance start
To stop the daemon run:
$ ./bin/instance start
6 Email Server
Postfix provides the email interface for GroupServer. Configuring Postfix is tricky, and is optional: you can use the Web interface to GroupServer without configuring the email server. However, GroupServer uses Postfix to:
- Queue email that is delivered to groups,
- Pass the email messages to GroupServer, and
- Send email messages from GroupServer to the email accounts of the group members.
6.1 Change the Configuration
Postfix has to know to run two scripts when email messages come in for your GroupServer site. To do this too, you will have to change some files in the Postfix configuration directory. For Ubuntu this directory is /etc/postfix.
6.1.1 Copy the Configuration Files
Copy the files postfix_config/groupserver.* from the GroupServer installation directory to the Postfix configuration directory /etc/postfix.
Change the ownership of the files to the Postfix user and group. For Ubuntu this would be:
# chown nobody.nogroup /etc/postfix/groupserver.*
If you are on a system other than Ubuntu, running the following will display the user-name of the Postfix user:
$ /usr/sbin/postconf | grep default_privs | cut -f3 -d" "
Modify the host
6.1.2 Change main.cf
Edit /etc/postfix/main.cf.
Find the alias_maps parameter.
Add the following on a line below the existing value of alias_maps:
hash:/etc/postfix/groupserver.aliases
Find the virtual_alias_maps parameter.
Add the following on a line below the existing value of virtual_alias_maps
hash:/etc/postfix/groupserver.virtual
Find the mydestination parameter.
If the hostname specified as virtual in the /etc/postfix/groupserver.virtual is listed as a destination, it will need to be removed from mydestination as it cannot be specified in both places.
Add the following to the bottom, unless it is previously defined:
smtpd_authorized_verp_clients = 127.0.0.1
6.1.3 Update Postfix
To load the new configuration into Postfix run the following commands:
# postalias /etc/postfix/groupserver.aliases # postmap /etc/postfix/groupserver.virtual # postfix reload
6.2 Set up Scripts
The two scripts that are run by Postfix are stored in the utils directory of your GroupServer installation. To allow them to be run by Postfix the ownership will need to be changed to the same user and group as the configuration fixes (see Copy the Configuration Files). For Ubuntu the command will be:
# chown nobody.nogroup utils/*py
6.3 Process the outgoing email queue
In order to avoid outgoing email from causing a noticeable delay to the user, GroupServer queues outgoing email by default. It is necessary to regularly request that GroupServer flush the outgoing queue. The easiest way to do that is to add an entry similar to this to /etc/crontab
*/3 * * * * groupserver wget -O/dev/null http://{host}:{zope_port}/groupserver/ListManager/processSpool
Change groupserver to the user you are using to run groupserver, or any other non-priviledged user.
7 Web Proxy
A web proxy is unnecessary if you only wish to try GroupServer. However, for production sites it is a good idea to run a proxy to provide the following services:
- To mediate between the low level HTTP port (port 80) and the high-port that Zope runs on (normally port 8080, see Set up Zope).
- To rewrite the URL to include a skin directive.
- To rewrite the URL to support virtual hosting.
- To provide caching.
GroupServer is known to work with many Web proxies including Varnish, NGINX, ha_proxy, and Apache. For Apache a rewrite rule that is required to provide the mapping looks like the one in the example file apache-groupserver.
8 Remove Groupserver
To remove GroupServer, you must remove the database, the associated database user, and the directory that contains the GroupServer install.
To remove the database, run the following commands:
$ dropdb gstestdb -U postgres $ dropuser gstest -U postgres
- gstestdb
- The name of the test database that you set earlier (see Configure Zope)
- postgres
- The name of the admin of PostgreSQL.
- gstest
- The name of the PostgreSQL user.
Remove the directory that contains the GroupServer install:
$ rm -r groupserver-1.0beta
9 History
| Version | Date | Change |
|---|---|---|
| 11.08 | 2011-12-19 | Adding the packages required for XML support and XSLT support on RHEL and CentOS to the list of Requirements. |
| 11.08 | 2011-12-16 | Added the CentOS packages to the list of Requirements, with much thanks to Patrick Leckey. |
| 11.08 | 2011-11-15 | Altering the requirements to switch the build-essential dependency to make on the advice of David Sturman. |
| 11.08 | 2011-10-27 | Adding the Download section, and clarifying some more of the documentation. |
| 11.08 | 2011-10-26 | Correcting some mistakes, and clarifying the documentation on the advice of Ross Chesley |
| 11.08 | 2011-09-01 | Reordering the subsections of Configure Zope. |
| 11.07 | 2011-07-08 | Adding the build-essential depenency and the cut-n-paste apt-get block to the Requirements. |
| 11.06 | 2011-07-05 | Adding the prologue. |
| 11.06 | 2011-07-04 | Updating the notes, because of a change to the name of the initial GroupServer instance. |
| 11.06 | 2011-06-17 | Added postfix configuration and spooling notes. |
| 11.05 | 2011-05-26 | Fixed a typing mistake, and mentioned that the pgsql_dbname and pgsql_user had to be different. |
| 10.09 | 2010-09-01 | Changed how the configuration options are set. |
| 1.0β² | 2010-07-15 | Improved the buildout instructions. |
| 1.0β² | 2010-07-07 | Changed the Zope 2.10 (Python 2.4) instructions to Zope 2.13 (Python 2.6) instructions. |
| 1.0β | 2010-06-04 | Removed a duplicated instruction from the Quick Start, and bumped the version number. |
| 1.0α | 2010-05-31 | Typo and minor improvement fixes. |
| 1.0α | 2010-05-01 | Fixes because upstream broke our buildout. |
| 1.0α | 2010-04-29 | Better automatic configuration, so the Configure GroupServer section has been removed. |
| 1.0α | 2010-04-28 | Improved the documentation for gs_port and added documentation for the gs_admin and gs_user configuration options. |
| 1.0α | 2010-04-23 | Added a link to the downloads page. Clarified the security changes that are made to PostgreSQL. |
| 1.0α | 2010-04-06 | Fixed some quoting in the requirements. |
| 1.0α | 2010-03-31 | Fixed the Requirements, added Remove GroupServer and History |
| 1.0α | 2010-03-25 | Fixed the config options, added Quick Start |
| 1.0α | 2009-10-04 | Updated to reflect the new egg-based system |
Start an OnlineGroups.Net site for easier email collaboration in your organization.
Powered by GroupServer, the open source web-based mailing list manager.