| 26 | | |
| 27 | | |
| 28 | | |
| 29 | | |
| 30 | | |
| 31 | | == Installing Trac on Gentoo for multiples projects == |
| 32 | | |
| 33 | | |
| 34 | | I wanted to use Trac for each development project I had, and configure the Apache 2 webserver on my Gentoo Linux box to create a (name-based) virtual host that would hold every Trac instance (more information on virtual hosts can be found here). The following is what I did, as root, to make the whole thing work. |
| 35 | | |
| 36 | | Say the development vhost is known as dev.domain.tld. Basically I wanted to access to each project website via http://dev.domain.tld/projectX/. |
| 37 | | |
| 38 | | === 1. Emerging Trac === |
| 39 | | |
| 40 | | Since mod_python support is a new feature of 0.7.1 and is still experimental, I'm not going to use it and I'll stick with a simple CGI installation. You'll see that using a CGI installation together with webapp-config on a single vhost causes a restriction: the version of every Trac instance has to be unique. Using mod_python may throw away this restriction, I'll update this document as soon as I test it. |
| 41 | | {{{ |
| 42 | | emerge trac |
| 43 | | }}} |
| 44 | | Obviously, I had to edit /etc/portage/package.keywords to make stuff available to Portage, because I'm running a stable (x86) version of Gentoo. |
| 45 | | |
| 46 | | {{{ |
| 47 | | app-text/silvercity ~x86 |
| 48 | | dev-libs/clearsilver ~x86 |
| 49 | | www-apps/trac ~x86 |
| 50 | | }}} |
| 51 | | |
| 52 | | === 2. Installing each instance of Trac === |
| 53 | | |
| 54 | | Say I have now a bunch of projects, known as project1, project2, ... I use the webapp-config tool to install each instance of Trac 0.7.1: |
| 55 | | {{{ |
| 56 | | webapp-config -I -h dev.domain.tld -d project1/trac trac 0.7.1 |
| 57 | | webapp-config -I -h dev.domain.tld -d project2/trac trac 0.7.1 |
| 58 | | ... |
| 59 | | }}} |
| 60 | | |
| 61 | | Don't forget the /trac part for the directory path. |
| 62 | | |
| 63 | | For each project, symlinks (or hardlinks, depending on your webapp-config configuration) are created in /var/www/dev.domain.tld/htdocs/projectX/trac/ and /var/www/dev.domain.tld/htdocs/projectX/trac/css/, making images and css files available in the web space, under http://dev.domain.tld/projectX/trac/ and http://dev.domain.tld/projectX/trac/css/. Symlinks are known to work with Trac. |
| 64 | | |
| 65 | | Furthermore, a symlink (or hardlink) to trac.cgi is created each time in /var/www/dev.domain.tld/cgi-bin/, regardless of the instance. This webapp-config issue can be restricting if you want to install different versions of Trac on the same vhost, because this way you get only one trac.cgi per vhost. As a result, you need to install the same version of Trac everywhere on your vhost. |
| 66 | | |
| 67 | | === 3. Setting up Subversion repositories and Trac environments === |
| 68 | | |
| 69 | | Now, let's create Subversion repositories, one for each project we have. |
| 70 | | ==== 3.1. Creating Subversion repositories ==== |
| 71 | | |
| 72 | | Let's say we want our repositories to live under /var/svn/. Issue the following commands to create a repository for project1: |
| 73 | | {{{ |
| 74 | | svnadmin create /var/svn/project1 |
| 75 | | chown -R apache /var/svn/project1 |
| 76 | | }}} |
| 77 | | Changing the ownership of the repository is important: as svn commits will be handled by Apache, the apache user needs to have write access to the repository. |
| 78 | | |
| 79 | | Also, if you built Subversion from Apache 2.0.50, you may want to do the following (that's because APR from Apache 2.0.50 has a bug and set created directories to 1755 instead of regular 0755): |
| 80 | | {{{ |
| 81 | | find /var/svn/project1 -type d -exec chmod 755 {} \; |
| 82 | | }}} |
| 83 | | Repeat these steps for each project you have. |
| 84 | | |
| 85 | | ==== 3.2. Creating Trac environments ==== |
| 86 | | |
| 87 | | Each project needs a Trac environment too, and we want them to live under /var/lib/trac/. If it doesn't already exist, we create the directory: |
| 88 | | {{{ |
| 89 | | mkdir /var/lib/trac/ |
| 90 | | }}} |
| 91 | | Then we create a Trac environment for project1 by doing: |
| 92 | | {{{ |
| 93 | | trac-admin /var/lib/trac/project1/ initenv |
| 94 | | }}} |
| 95 | | Just answer the question to fill you needs, and indicates the right Subversion repository created in the previous step. Adjust the ownership of var/lib/trac/project1/, because Trac needs to write in it: |
| 96 | | {{{ |
| 97 | | chown -R apache /var/lib/trac/project1/ |
| 98 | | }}} |
| 99 | | Repeat the above steps for each project you have. |
| 100 | | |
| 101 | | === 4. Configuring Apache === |
| 102 | | |
| 103 | | Here is my configuration for the name-based vhost. |
| 104 | | ==== 4.1. Vhost configuration ==== |
| 105 | | |
| 106 | | The first part of the configuration is relative to the vhost itself: |
| 107 | | {{{ |
| 108 | | <VirtualHost *:80> |
| 109 | | ServerName dev.domain.tld |
| 110 | | DocumentRoot /var/www/dev.domain.tld/htdocs |
| 111 | | |
| 112 | | <Directory /var/www/dev.domain.tld/htdocs> |
| 113 | | AllowOverride all |
| 114 | | Options +Indexes +FollowSymLinks |
| 115 | | |
| 116 | | <IfModule mod_access.c> |
| 117 | | Order Deny,Allow |
| 118 | | </IfModule> |
| 119 | | </Directory> |
| 120 | | |
| 121 | | <Directory /var/www/dev.domain.tld/cgi-bin> |
| 122 | | Options +FollowSymLinks |
| 123 | | |
| 124 | | <IfModule mod_access.c> |
| 125 | | Order Deny,Allow |
| 126 | | </IfModule> |
| 127 | | </Directory> |
| 128 | | }}} |
| 129 | | Here I set the name-based vhost and the access policies. Note that +Indexes on htdocs/ isn't needed; however, in case webapp-config created symlinks, +FollowSymLinks is necessary, both on htdocs/ and cgi-bin/. |
| 130 | | |
| 131 | | ==== 4.2. Per-project configuration ==== |
| 132 | | |
| 133 | | Next, there are per-project specific directives that define a project. This example has to be repeated for each project. |
| 134 | | {{{ |
| 135 | | ### |
| 136 | | ### project1 |
| 137 | | ### |
| 138 | | Alias /project1/dox /var/www/dev.domain.tld/htdocs/project1/dox |
| 139 | | |
| 140 | | <Location /project1/svn> |
| 141 | | <IfDefine SVN> |
| 142 | | DAV svn |
| 143 | | SVNPath /var/svn/project1 |
| 144 | | SVNIndexXSLT /project1/trac/svnindex.xsl |
| 145 | | </IfDefine> |
| 146 | | |
| 147 | | <LimitExcept GET PROPFIND OPTIONS REPORT> |
| 148 | | AuthType Basic |
| 149 | | AuthName "project1::svn" |
| 150 | | |
| 151 | | <IfModule mod_auth_ldap.c> |
| 152 | | AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one |
| 153 | | Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld |
| 154 | | </IfModule> |
| 155 | | </LimitExcept> |
| 156 | | </Location> |
| 157 | | |
| 158 | | <Location /project1> |
| 159 | | SetEnv TRAC_ENV "/var/lib/trac/project1" |
| 160 | | </Location> |
| 161 | | |
| 162 | | <Location /project1/login> |
| 163 | | AuthType Basic |
| 164 | | AuthName "project1::trac" |
| 165 | | |
| 166 | | <IfModule mod_auth_ldap.c> |
| 167 | | AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one |
| 168 | | Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld |
| 169 | | </IfModule> |
| 170 | | </Location> |
| 171 | | |
| 172 | | Alias /project1/trac /var/www/dev.domain.tld/htdocs/project1/trac |
| 173 | | ScriptAlias /project1 /var/www/dev.domain.tld/cgi-bin/trac.cgi |
| 174 | | }}} |
| 175 | | As you can see, I make a big use of Locations and Aliases. Now, some comments. |
| 176 | | |
| 177 | | ===== 4.2.1. Trac stuff ===== |
| 178 | | |
| 179 | | We need several directives to make Trac work. The first thing is to set the TRAC_ENV environment variable. This variable indicates to trac.cgi the location of the Trac environment corresponding to project1 in the filesystem. Actually, I'm storing every Trac environment under /var/lib/trac/, so the projectX Trac environment can be found under /var/lib/trac/projectX/. |
| 180 | | |
| 181 | | That's why we set the TRAC_ENV for the entire /project1 web space, with the following: |
| 182 | | {{{ |
| 183 | | <Location /project1> |
| 184 | | SetEnv TRAC_ENV "/var/lib/trac/project1" |
| 185 | | </Location> |
| 186 | | }}} |
| 187 | | Then we redirect every request for /project1/* to trac.cgi with the ScriptAlias directive: |
| 188 | | {{{ |
| 189 | | ScriptAlias /project1 /var/www/dev.domain.tld/cgi-bin/trac.cgi |
| 190 | | }}} |
| 191 | | This needs to be placed at the very end of the project configuration, because it is a default redirection for every request made to /project1/*. Special configuration for some URIs will be placed before this directive to be taken in account. |
| 192 | | |
| 193 | | A needed escaping URI is /project1/login, used by Trac to authenticate users. I've set a Location for it, and placed the authentication stuff inside: |
| 194 | | {{{ |
| 195 | | <Location /project1/login> |
| 196 | | AuthType Basic |
| 197 | | AuthName "project1::trac" |
| 198 | | |
| 199 | | <IfModule mod_auth_ldap.c> |
| 200 | | AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one |
| 201 | | |
| 202 | | Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld |
| 203 | | </IfModule> |
| 204 | | </Location> |
| 205 | | }}} |
| 206 | | AuthType, AuthName and Require directives are needed, then you may use the user referential you want (here I'm using a LDAP server). I'm telling Apache that a user may authenticate if he belongs to the project1 group. This way, you can create groups for each project you have, and make users belong to the groups corresponding to the projects they work on. |
| 207 | | |
| 208 | | The last thing to make Trac work is to map a URI to the images and css files location, again to escape the trac.cgi handler. |
| 209 | | {{{ |
| 210 | | Alias /project1/trac /var/www/dev.domain.tld/htdocs/project1/trac |
| 211 | | }}} |
| 212 | | As we installed the Trac instance to /project1/trac it should work. Well, actually we need to modify the trac.ini configuration file for Trac, in order to change the way URIs are generated. Just edit /var/lib/trac/project1/conf/trac.ini: |
| 213 | | {{{ |
| 214 | | htdocs_location = /project1/trac |
| 215 | | }}} |
| 216 | | Ok, that should be enough to use Trac. Point a browser to http://dev.domain.tld/project1 and voila. |
| 217 | | |
| 218 | | ===== 4.2.2. External components to Trac ===== |
| 219 | | |
| 220 | | Then I felt the need to add external pages to Trac, like a Doxygen component that would contain the generated documentation from the code source of project1. I wanted to find this documentation under /project1/dox. |
| 221 | | |
| 222 | | We need to escape trac.cgi again, by setting a new Alias before the ScriptAlias directive. There we map the /project1/dox web space to the /var/www/dev.domain.tld/htdocs/project1/dox file space. |
| 223 | | {{{ |
| 224 | | Alias /project1/dox /var/www/dev.domain.tld/htdocs/project1/dox |
| 225 | | }}} |
| 226 | | By the way, I've automated the creation of the Doxygen documentation by using the post-commit hook of Subversion, and doing a checkout followed by a "doxygenation" inside /var/www/dev.domain.tld/htdocs/project1/dox. |
| 227 | | |
| 228 | | Last but not least, I wanted to make the Subversion repository accessible via /project1/svn, with anonymous checkouts and authenticated commits. We need a Location to place the mod_dav_svn stuff and the authentication directives. |
| 229 | | {{{ |
| 230 | | <Location /project1/svn> |
| 231 | | <IfDefine SVN> |
| 232 | | DAV svn |
| 233 | | SVNPath /var/svn/project1 |
| 234 | | SVNIndexXSLT /project1/trac/svnindex.xsl |
| 235 | | </IfDefine> |
| 236 | | |
| 237 | | <LimitExcept GET PROPFIND OPTIONS REPORT> |
| 238 | | AuthType Basic |
| 239 | | AuthName "project1::svn" |
| 240 | | |
| 241 | | <IfModule mod_auth_ldap.c> |
| 242 | | AuthLDAPURL ldap://ldap.domain.tld:389/ou=users,dc=domain,dc=tld?uid?one |
| 243 | | Require group cn=project1,ou=dev,ou=groups,dc=domain,dc=tld |
| 244 | | </IfModule> |
| 245 | | </LimitExcept> |
| 246 | | </Location> |
| 247 | | }}} |
| 248 | | As you can see, I'm storing my Subversion repositories under /var/svn/, so I set the name of the project1 repository to /var/svn/project1. Obviously, it is the filepath I will use when I create the project1 Trac environment. |
| 249 | | |
| 250 | | Instructions for limiting the write access to the repository can be found on the SVN Book. I'm using the same authentication scheme than the previous one, to be consistent between Trac users and SVN users. |
| 251 | | |
| 252 | | ===== 4.2.3. Integrating these external components inside Trac ===== |
| 253 | | |
| 254 | | We can use the per-project templates of Trac to integrate, for example, the Doxygen documentation inside Trac. They are located under /var/lib/trac/project1/templates/. We may want to insert a link to /project1/dox in the header, and have the following site_header.cs: |
| 255 | | {{{ |
| 256 | | <?cs |
| 257 | | #################################################################### |
| 258 | | # Site header - Contents are automatically inserted above Trac HTML |
| 259 | | ?> |
| 260 | | <div> |
| 261 | | <a id="dox" href="/<?cs var:project.name?>/dox">Doxygen documentation</a> |
| 262 | | </div> |
| 263 | | }}} |
| 264 | | And why not using a per-project css file? Let's edit site_css.cs: |
| 265 | | {{{ |
| 266 | | <?cs |
| 267 | | ################################################################## |
| 268 | | # Site CSS - Place custom CSS, including overriding styles here. |
| 269 | | ?> |
| 270 | | @import url("<?cs var:htdocs_location ?>css/<?cs var:project.name?>.css"); |
| 271 | | }}} |
| 272 | | This way, we can create a /var/www/dev.domain.tld/htdocs/project1/trac/css/project1.css file (among with symlinks), and personalize the Trac layout. These per-projects file won't be deleted by webapp-config, so it's a good thing. |
| 273 | | |
| 274 | | === 5. Conclusion === |
| 275 | | |
| 276 | | By copy/pasting the configuration for one project, we can set up as many projects as we want, each with their own web space, Subversion access, authentication scheme (users referential and authentication method) and layout. |
| 277 | | |
| 278 | | Corrections and suggestions about this documentation are welcome. |
