[[PageOutline(2-5,Contents,pullout)]]
= Experimental Trac multi-project support =

== Description ==

Still developing this concept. Currently it has the following functionality:
 * lets you create new projects from a web GUI
 *  handles serving them, similar to how TRAC_ENV_PARENT_DIR works, except looks nicer and has permission controls

'''Note''': What is in subversion is currently usable, but there isn't (yet) much documentation. If you would like to try this out you should probably try finding me on #trac (I am usually on as coderanger).

'''Another Note:''' Not compatible with 0.11. The warning in setup.py isn't a joke. Really.

== Known Issues ==
In order to add projects right now, create a prototype containing only `DoNothing`. You still need to make the Trac environment and other things using {{{trac-admin}}} for now.

To create your prototype, once you've installed !TracForge, 

   1. go to the "Project Prototypes" panel of your master project's !TracForge admin panels
   1. click "New Prototype"
   1. click the X button on the resulting !MakeTracEnvironment box
   1. select !DoNothing from the popup menu
   1. hit the "+" button in the resulting "!DoNothing box"
   1. fill in the name of your prototype (e.g "add existing project") in the "Name" field
   1. click "save"

'''Note:''' The "Project Prototypes" admin panel requires !JavaScript

MySQL support is not planned yet.

== Installation ==
=== Multi-project Support ===
First designate one env to be the master. This will manage SSO, and  
hold the central roles and permissions. This is also commonly the  
aggregate trac if you are using the [wiki:TracForgePlugin#DataSubscription data subscription system], but it  
doesn't need to be.

On the master env, activate these components in the section named 'components':
{{{
#!ini
tracforge.* = enabled
tracforge.linker.* = disabled
tracforge.linker.auth.tracforgecookiemunger = enabled
tracforge.subscriptions.* = disabled
}}}

On each client env activate these:
{{{
#!ini
trac.web.auth.loginmodule = disabled
tracforge.admin.perm.* = enabled
tracforge.linker.* = enabled
tracforge.perms.* = enabled
}}}
'''NOTE''': The last module was not previously listed for clients, please make sure to add it when upgrading to a newer version of !TracForge. [[BR]]
'''ANOTHER NOTE''': If you are using [wiki:AccountManagerPlugin AccountManager], make sure it is disabled in all clients.

In the master be sure you set `base_url`. You will also need some kind of authentication setup on the master, either the default HTTP auth system or the AccountManagerPlugin are popular choices (I recommend the latter).

For all envs set this in `[trac]`:
{{{
#!ini
permission_store = TracForgePermissionModule
}}}
and add this in `[tracforge]`:
{{{
#!ini
master_path = /path/to/master/env
}}}

That should be all config changes you need. If you want to use the  
data subscription system, just enable `tracforge.subscriptions.*` on  
all envs.

To setup the !TracForge system, go into WebAdmin on the master, and  
there should be a !TracForge Project Admin screen. In there add each  
of your projects. For now !TracForge cannot actually create the  
projects, so make them the normal way and then just enter them into  
!TracForge (see [wiki:TracForgePlugin#KnownIssues above] about prototypes). 
Once that is done you should be able to add central roles  
and permissions. Permissions work exactly the same way as normal,  
with the central ones combined with the per-project permissions.  
Roles show up as groups, so you can do something like give the group  
"member" the permission WIKI_MODIFY, and then add some users as  
members to a project. The "*" project on the roles screen means that  
user will have the given role on all projects (very handy for  
configuring global admin accounts).

==== Project Index ====
!TracForge now can handle displaying the project index, and dispatching
to subordinate environments (in a similar fashion a `TRAC_ENV_PARENT_DIR`
setup). To use this you just need to setup the master environment normally, 
but do not setup anything in the webserver for the `TRAC_ENV_PARENT_DIR`.
One advantage this has over the built-in system is that it can control access
using Trac permissions, specifically `PROJECT_VIEW`. This check is done against 
the project they are trying to access, not the master. The project index will
also be filtered so they can only see projects they can access.

=== Data Subscription ===
There isn't much configuration to the subscription system. It should  
autodetect all sibling envs (envs sharing the same enclosing folder),  
and let you add subscriptions from one env to another. Changesets  
work very well, and tickets are mostly working (though there is no  
support for attachments yet).

== Permissions Management ==

The TracForgePlugin adds a "global" permissions system on top of per-project permissions, and also provides some extra permission flags.

The global permissions system works in exactly the same way as the per-project permissions system -- you can create groups and map groups and users to any of the usual [http://trac.edgewall.org/wiki/TracPermissions Trac permissions].  Any permissions you set at this level will be available to all projects as though you set that permission in every single project.

You need to be careful with the global permissions, though, because you can't "negate" a permission.  If you grant, say, {{{WIKI_VIEW}}} to {{{anonymous}}} in the Tracforge permissions, then everyone will be able to view all your wikis, and there's nothing you can do in each client project to stop that.  It's probably best to stick to granting perms to certain really-global groups.

Tracforge provides three new permission flags:

|| {{{TRACFORGE_ADMIN}}} || (Master only) Access the Tracforge !admin pages, to set global permissions and create new projects ||
|| {{{TRACFORGE_CREATE}}} || (Master only) Create new Trac projects (it's not actually used anywhere though, but since project creation is broken anyway, it's not such a big deal) ||
|| {{{PROJECT_VIEW}}} || (All projects) The project is visible in the "Project Index" list available from the 'Projects' link in the title bar ||



== Bugs/Feature Requests == 

Existing bugs and feature requests for TracForgePlugin are 
[report:9?COMPONENT=TracForgePlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=TracForgePlugin&owner=coderanger new ticket].

== Download ==

Download the zipped source from [download:tracforgeplugin here].

== Source ==

You can check out TracForgePlugin from [http://trac-hacks.org/svn/tracforgeplugin here] using Subversion, or [source:tracforgeplugin browse the source] with Trac.

There is also an [http://theshed.hezmatt.org/mattshacks/tracforge/bugfixes (unofficial) darcs repository] containing some additional bugfixes which aren't in trunk yet.  This branch will always follow the trunk, but with added bugfixes that are in use on at least one production !TracForge instance.  You can also [http://theshed.hezmatt.org/mattshacks/tracforge/_patches/bugfixes see all the patches currently in this branch].

== Example ==

Nothing yet.

== Recent Changes ==

[[ChangeLog(tracforgeplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:coderanger] [[BR]]
'''Maintainer:''' ''none'' [[BR]]
'''Contributors:'''