HowTo/ProjectSetup

New Project Setup

This document covers basic infrastructure setup for OpenGeo projects. This assumes a Trac environment will be set up and SVN will be used to manage code. Though Trac setup is described first, if your project will use a subversion repository, read the section on SVN first. Trac can be configured to work with svn before or after the initial setup.

Trac

Basic Setup

This assumes your project will be accessible on the web with a URL like

http://projects.opengeo.org/[PROJECT]

Make sure to replace [PROJECT] with the name of your project!

You also must have appropriate permissions on projects.opengeo.org to do this. You may need to prefix commands with sudo.

cd /var/www/projects.opengeo.org/trac
trac-admin [PROJECT] initenv --inherit=/var/www/projects.opengeo.org/shared/trac/conf/trac.ini

At this point, you'll be prompted for some project detail (name, database connection, etc.) Accept the defaults (by pressing Enter) when you don't know better (database connection string, repository type). Leave the path to repository blank if you don't plan on using svn or haven't set up a repository yet.

Finally, give apache permission to write to your new project environment and "upgrade" to take advantage of a couple plugins.

chown -R apache [PROJECT]
trac-admin [PROJECT] upgrade

At this point, assuming all went well, you should be able to view your new project at this URL:

http://projects.opengeo.org/[PROJECT].

Users, Permissions, Admin

Users

By default, anybody listed in the shared password file can log in to your new project site. You can find a list of these users with the following:

cat /var/www/shared/htpasswd

If you are listed among those users, the login page (http://projects.opengeo.org/[PROJECT]/login) should log you in. If you are not listed among those users, the register page (http://projects.opengeo.org/[PROJECT]/register) should allow you to register as a user.

Permissions

A new Trac environment won't have a user with admin privileges yet. Adding an admin user (or group) is your last task at the command line. After this, all Trac admin can be done through the web. It's a good idea to give more than one person admin rights to the new environment.

Note that if you want to add groups with specific permissions, this has nothing to do with groups listed in the shared group file (/var/www/shared/htgroup). Since Trac manages its own permissions, it maintains separate groups.

Since we're just giving out a single permission here, it's easy enough to do this with individual users (groups in Trac make sense when you want to share multiple permissions with multiple people).

trac-admin [PROJECT] permission add [YOURUSERNAME] TRAC_ADMIN

Replace [PROJECT] with your project name and [YOURUSERNAME] with your username (from /var/www/shared/htpasswd). If you want to add permissions for more users, you can do so here or through the web later.

By default, anonymous users can view most aspects of Trac projects (tickets, reports, wiki, timeline, milestones, etc). Also by default, authenticated users can create and modify tickets and wiki pages. You can configure these permissions through the web.

Admin

At this point, you are ready to start editing content and configuring Trac through the web. Log in (http://projects.opengeo.org/[PROJECT]/login) and find the admin link (http://projects.opengeo.org/[PROJECT]/admin).

The admin pages let you control everything else you'll want to do with your Trac site.

Email notification

The global configuration sends email to ticket owners, reporters, and updaters assuming they have provided an email address under their "preferences" for each Trac instance. If you want to configure a single Trac instance differently from the global configuration, add a [notification] section to your trac.ini (/var/www/projects.opengeo.org/trac/[PROJECT]/conf/trac.ini) that contains values different from what you find in the same section of the global trac.ini (/var/www/projects.opengeo.org/shared/trac/conf/trac.ini). Mail is sent from ak+trac at openplans dot org by default. This may change in the future.

Subversion

This section assumes you want a subversion repository hosted by Apache on arachnia at a URL like http://svn.opengeo.org/[PROJECT]. All commands must be run with sufficient privileges (prefix with sudo if needed).

Basic Setup

Create a new repository and set apache as owner.

cd /var/www/svn.opengeo.org
svnadmin create [PROJECT]
chown -R apache [PROJECT]

Configure Apache

Edit the configuration for the svn.opengeo.org virtual host to include a location block that captures requests to your new repository ( http://svn.opengeo.org/[PROJECT]).

emacs /etc/apache2/sites-available/svn.opengeo.org

Paste in the following block somewhere sensible:

        <Location /[PROJECT]>
                DAV svn
                SVNPath /sites/svn.opengeo.org/[PROJECT]
                # Limit write permission to list of valid users.
                <LimitExcept GET PROPFIND OPTIONS REPORT>
                      # Require SSL connection for password protection.
                      # SSLRequireSSL
                        AuthType Basic
                        AuthName "[PROJECT] Subversion Repository"
                        AuthGroupFile /sites/shared/htgroup
                        AuthUserFile /sites/shared/htpasswd
                        Require group opengeo_admin
                </LimitExcept>
        </Location>

(Throughout all instructions, make sure to replace [PROJECT] with the name of your project.)

Restart Apache.

/etc/init.d/httpd restart

Your new repository should be browseable at http://svn.opengeo.org/[PROJECT]. Members of the opengeo_admin group have commit rights, but everybody else can do checkouts etc. If you want to restrict access in a different way, you can add a group to /var/www/shared/htgroup and edit the Apache config accordingly.

Removing Trac Environments and SVN Repos

Remove the directories containing Trac environments and svn repositories.

rm -rf /var/www/svn.opengeo.org/[PROJECT]
rm -rf /var/www/projects.opengeo.org/trac/[PROJECT]

Edit /etc/apache2/sites-available/svn_opengeo_org to remove the block on your repository (the block starting with <Location /[PROJECT]>).