Changes between Version 334 and Version 335 of TracInstall

Timestamp:

Feb 27, 2011, 2:15:14 PM (13 years ago)

Author:

Christian Boos

Comment:

Moved TracCgi@51#MappingStaticResources to TracInstall#MappingStaticResources

TracInstall

@@ -286 +286 @@
 }}}
 
+
+==== Mapping Static Resources ====
+
+Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance).
+
+Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself.
+
+There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources usually accessible by `/chrome/plugin` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
+
+===== Example: Apache and `ScriptAlias` =====
+
+Add the following snippet to Apache configuration '''before''' the `ScriptAlias` for the CGI script, changing paths to match your deployment:
+{{{
+Alias /trac/chrome/common /path/to/trac/htdocs/common
+Alias /trac/chrome/site /path/to/trac/htdocs/site
+<Directory "/path/to/www/trac/htdocs">
+  Order allow,deny
+  Allow from all
+</Directory>
+}}}
+
+If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
+{{{
+<Location "/trac/chrome/common/">
+  SetHandler None
+</Location>
+}}}
+
+Note that we mapped `/trac` part of the URL to the `trac.cgi` script, and the path `/chrome/common` is the path you have to append to that location to intercept requests to the static resources. 
+
+For example, if Trac is mapped to `/cgi-bin/trac.cgi` on your server, the URL of the Alias should be `/cgi-bin/trac.cgi/chrome/common`, like so:
+
+{{{
+Alias /cgi-bin/trac.cgi/chrome/common /path/to/trac/htdocs/common
+}}}
+
+Similarly, if you have static resources in a project's htdocs directory (which is referenced by /chrome/site URL in themes), you can configure Apache to serve those resources (again, put this '''before''' the `ScriptAlias` for the CGI script, and adjust names and locations to match your installation):
+
+{{{
+Alias /trac/chrome/site /path/to/projectenv/htdocs
+<Directory "/path/to/projectenv/htdocs">
+  Order allow,deny
+  Allow from all
+</Directory>
+}}}
+
+Alternatively to hacking `/trac/chrome/site`, you can directly specify path to static resources using `htdocs_location` configuration option in [wiki:TracIni trac.ini]:
+{{{
+[trac]
+htdocs_location = http://yourhost.example.org/trac-htdocs
+}}}
+
+Trac will then use this URL when embedding static resources into HTML pages. Of course, you still need to make the Trac `htdocs` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
+{{{
+$ ln -s /path/to/www/trac/htdocs /var/www/yourhost.example.org/trac-htdocs
+}}}
+
+Note that in order to get this `htdocs` directory, you need first to extract the relevant Trac resources using the `deploy` command of TracAdmin:
+[[TracAdminHelp(deploy)]]
+
+
 ==== Setting up the Plugin Cache ====