GroupServer installation¶
Authors: | Michael JasonSmith; Richard Waid; Marek Kuziel; Alice Rose; Dan Randow |
---|---|
Contact: | Michael JasonSmith <mpj17@onlinegroups.net> |
Date: | 2015-08-17 (see History) |
Organization: | GroupServer.org |
Copyright: | This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net. |
Installation can be tricky: much has to be configured and set up correctly or installation will fail. We wrote this documentation for people with moderate experience in Linux system administration. If you get stuck, please ask us questions in GroupServer Development. Other more detailed guides would be gratefully accepted.
Note
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.
Quick start¶
Download the latest version of GroupServer from <http://groupserver.org/downloads> and extract the archive.
Create a new hostname for your GroupServer site. Yes, you will need a new one (see Pick a Host Name).
Edit
config.cfg
(see Configure GroupServer).Enable prepared transaction support in PostgreSQL (see Configure PostgreSQL).
Run the following (see Run the installer):
$ ./gs_install_ubuntu.sh
-
$ ./bin/instance fg
Visit your new site.
Commence the next steps.
Set up¶
GroupServer builds on five major infrastructure packages. These packages are installed by the installation script. However, you must configure the relationship between GroupServer and to these packages before you run the installer.
- Postfix handles both the incoming and outgoing email.
- Zope provides the web framework and basic web server support.
- PostgreSQL stores the posts.
- ZODB stores some web content and the user-information.
- Redis provides an application cache.
Setting up GroupServer is done in four steps: first pick a host name, then configure GroupServer, run the installer to install the system, and finally start Zope.
Pick a host name¶
Your new site needs its own hostname. This is the name that people will use to access your new GroupServer site with a web browser. For a trial system, the name can be set up in the hosts(5) file.
Edit
/etc/hosts
as theroot
user.Add the new host name to the
localhost
entry, which is normally the first one. For example, to add the namegstest
change the line to the following:127.0.0.1 localhost gstest
Save the
hosts
file.
Configure GroupServer¶
The configuration of GroupServer is mostly carried out by
modifying the config.cfg
file, which is located in the
root of the GroupServer folder [1]. First you must
configure the GroupServer Site itself. Next the Zope
system, which will run your GroupServer site, needs to be
configured, before the database storage.
GroupServer site¶
You will need to check all the configuration for your initial site.
host
- The domain name used by people accessing your new GroupServer site. It must be the same as what you picked a host name earlier (see Pick a host name).
admin_email
- When GroupServer is installed, an example site and group are created. So you can use the administration functions you must sign 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. This email address must work.
admin_password
- The password of the administrator of the new GroupServer site. The password will be used to sign 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 or the admin email address.
smtp_host
- The SMTP host that will be used to send email from
GroupServer. It defaults to
localhost
, assuming you will be running Postfix on the same machine as GroupServer.
Zope¶
Zope is used to provide the web-framework for GroupServer, and a
basic web-server. The server listens for connections on a single
port (the zope_port
) and provides the GroupServer UI if
connections are made using the host
name, or the Zope
Management Interface (ZMI) if connections are made with any other
host names.
The zope_host
and zope_port
are probably correct for most
systems, weather you are testing or if you are going to proxy
GroupServer (see Configuring a web proxy). However, for security
we recommend you change the name and password of the Zope
administrator.
zope_host
- The name of the host that will run Zope. It defaults to the
local machine (
127.0.0.1
). zope_port
- The IP port that Zope will listen to. It defaults to
8080
, and it recommended that you leave this value as-is, unless another service is running on port 8080. (Zope will have to run asroot
to use port 80, and this is discouraged; to use port 80 you will need to proxy GroupServer, see Configuring a web proxy.) zope_admin
- The name of the user who will administer Zope. This is used to log into the Zope Management Interface (ZMI).
zope_password
- The password for the Zope administrator. It can (and should) be changed after GroupServer has been set up.
Note
The IP-address of the zope_host
and host
(see
GroupServer site) must be the same.
Database storage¶
GroupServer stores most of its data in PostgreSQL. Two passwords need to be set by you to protect this data.
pgsql_password
- The password required to attach to the PostgreSQL database. The
install system will create a PostgreSQL database, and protect
it with this
pgsql_password
. relstorage_password
- The RelStorage system will store data in a PostgreSQL
database for Zope. This data is protected by the
relstorage_password
.
Configure PostgreSQL¶
The RelStorage system that is used by GroupServer requires prepared transaction support to be enabled in PostgreSQL. To enable prepared transaction support carry out the following steps.
Edit the PostgreSQL configuration file. On Ubuntu you must be
root
to edit this file, which is located in/etc/postgresql/9.x/main/postgresql.conf
. (The actual directory name may be different depending on the version of PostgreSQL you have installed; change the9.{x}
to match your version as appropriate.)Find the line that reads
max_prepared_transactions = 0
If the line is set to something other than
0
then nothing needs to change, and you can run the installer.Change the line to read
max_prepared_transactions = 1
Restart PostgreSQL. On Ubuntu this is done using the following command:
$ sudo service postgresql restart
Run the installer¶
The installer for Ubuntu is a Bash script. (For CentOS and RHEL you will have to carry out the steps by hand.) To run the GroupServer installer enter the following command:
$ ./gs_install_ubuntu.sh
You will be prompted for your password. This is required to check that your Ubuntu system has met all the dependencies. Next the installer ensures that the set up is correct.
Permissions: | GroupServer can only be run by users with normal
privileges. If the installation directory is owned
by root then you must change the ownership
of the installation directory to a normal user and
switch (su ) to that user. Then run the
installer. |
---|
The rest of the installation process should be completely automatic.
The system will create a sandbox for your GroupServer site, with its own version of Python, placed in
./bin/
.It will then configure the PostgreSQL databases that store the data for your site.
Finally, it will start the buildout [2] system that will download and install all the requirements for GroupServer (around 47MB of packages) including:
- eGenix.com mx Base (4.4MB)
- SQL Alchemy (3.9MB)
- lxml (3.4MB)
- Pillow (2.4MB)
- Zope 2.13 (1.4MB)
You need a functioning network connection to download the GroupServer requirements.
It is a good idea to make a cup of coffee, or go to lunch, while
buildout processes. The log file for the install will be written
to parts/log/{year}-{month}-{day}.{n}.log
.
CentOS and RHEL¶
The process to install GroupServer on CentOS or RedHat Enterprise Linux is manual. The basic idea is as follows, but it lacks testing.
Note
Commands that have to be run as root
are shown on
lines that begin with a #
. Commands that must be
run as a normal user are shown on lines that begin with
a $
.
Install the Dependencies.
PostgreSQL: The version of PostgreSQL that is supplied with RHEL 6.x and CentOS 6.x (PostgreSQL 8.4) lacks the features required by GroupServer. You will need to install PostgreSQL 9, including the development libraries using the instruction provided by the PostgreSQL project. Python: The version of Python supplied with RHEL 6.x and CentOS 6.x (Python 2.6) lack the features required by GroupServer. You will need to install Python 2.7 using these instructions from H₂0.ai. Create the two database users specified in
config.cfg
, using createuser:# createuser -D -S -R -l gsadmin # createuser -D -S -R -l gszodbadmin
Create the two databases specified in
config.cfg
using createdb:# createdb -Ttemplate0 -O gsadmin -EUTF-8 groupserver # createdb -Ttemplate0 -O gszodbadmin -EUTF-8 groupserverzodb
Get the Python
virtualenv
package:# easy_install virtualenv
Set up a Python virtual-environment for GroupServer:
$ virtualenv --python=python2.7 --no-site-packages .
Activate the Python virtual-environment (note the dot-space at the start of the command):
$ . bin/activate
Install the
argparse
module:$ easy_install argparse==1.1
Fetch the zc.buildout system that builds GroupServer:
$ easy_install zc.buildout==1.7.1
Run the
buildout
process:$ ./bin/buildout -N
Start Zope¶
Your GroupServer site is supported by Zope. To start Zope 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 site listens to (see Configure GroupServer).
Use Control-c
to stop Zope.
Next steps¶
- Starting and stopping GroupServer has more information on running GroupServer, including running it as a daemon.
- The steps required to configure a proxy is documented in Configuring a web proxy.
- We document the setup required to receive email with GroupServer in Configuring postfix.
- Finally, we outline the steps required to send out the daily digest of topics in Configuring cron.
History¶
Version | Date | Change |
---|---|---|
15.11 | 2015-08-17 | Updating the Sphinx markup, and mentioning the log files |
15.03 | 2015-03-27 | Updating the CentOS install instructions. |
15.03 | 2015-03-25 | Making a note about PostgreSQL 9 on CentOS and RHEL. |
15.03 | 2015-03-06 | Moving the Dependencies and Download sections to Getting GroupServer. |
14.11 | 2014-11-17 | Renaming the Requirements section Dependencies. |
14.11 | 2014-10-30 | Moving the Remove GroupServer section to Remove GroupServer. |
14.11 | 2014-10-30 | Integrating updates and suggestions from Scott Fosseen. |
14.11 | 2014-10-21 | Adding the setup diagram. |
14.11 | 2014-10-14 | Reducing the number of ports to one. |
14.06 | 2014-06-23 | Moving the sections for configuring the proxy and Postfix to their own documents. |
14.03 | 2014-03-25 | Clarifying the Requirements wording. |
14.03 | 2014-03-20 | Updating to Ouzo. |
12.11 | 2012-11-27 | Adding the sections CentOS and RHEL and Configure PostgreSQL. |
12.11 | 2012-11-19 | Adding a link to the Postfix documentation for Ubuntu. |
12.11 | 2012-10-25 | Removing some odd dependencies. |
12.05 | 2012-04-30 | Updating the Configure GroupServer and Run the Installer sections. |
12.05 | 2012-04-24 | Removing unnecessary dependencies, and using
pip in the Run Buildout section. |
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 | Adding 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 dependency 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 | Fixing a typing mistake, and mentioned that the
pgsql_dbname and pgsql_user had to be
different. |
10.09 | 2010-09-01 | Changing how the configuration options are set. |
1.0β² | 2010-07-15 | Improving the buildout instructions. |
1.0β² | 2010-07-07 | Changing 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 | Fixing a typo and adding minor improvements. |
1.0α | 2010-05-01 | Fixing, 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 | Improving the documentation for gs_port and
added documentation for the gs_admin and
gs_user configuration options. |
1.0α | 2010-04-23 | Adding a link to the downloads page. Clarified the security changes that are made to PostgreSQL. |
1.0α | 2010-04-06 | Fixing some quoting in the requirements. |
1.0α | 2010-03-31 | Fixing the Requirements, adding Remove GroupServer and History. |
1.0α | 2010-03-25 | Fixing the config options, added Quick Start. |
1.0α | 2009-10-04 | Updating to reflect the new egg-based system. |
[1] | The cfg files are interpreted by the standard
Python ConfigParser module, which accepts a syntax very
similar to Windows INI files. |
[2] | For more on buildout see Buildout and the Buildout site. |