# Changeset 37343 for wiki

Ignore:
Timestamp:
03/12/16 20:47:19 (6 years ago)
Message:

[titan] autoupdate wiki files

Location:
wiki/pages
Files:
54 edited

Unmodified
Removed
• ## wiki/pages/CamelCase

 r26484 = !CamelCase = New words created by smashing together capitalized words. = !CamelCase New wiki links are automatically created when concatenating capitalized words, such that for example the word 'Camel' and the word 'Case' concatenated form a link to this CamelCase page. CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links. !CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links. == Customizing the Wiki behavior == == Customizing the Wiki behavior Some people dislike linking by CamelCase.  While Trac remains faithful to the original Wiki style, it provides a number of ways to accomodate users with different preferences: * There's an option (ignore_missing_pages in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to simply ignore links to missing pages when the link is written using the CamelCase style, instead of that word being replaced by a gray link followed by a question mark.[[BR]] That can be useful when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them. While Trac remains faithful to the original Wiki style, it provides a number of ways to accommodate users with different preferences: * To prevent the creation of a new link of a camel-cased word, prefix with '!': !CamelCase. * To ignore links to missing pages when the link is written using the CamelCase style, that word can instead be replaced by a gray link followed by a question mark. This is useful in cases when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them. This option can be set in ignore_missing_pages in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni. * There's an option (split_page_names in the  [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to automatically insert space characters between the words of a CamelCase link when rendering the link. * Creation of explicit Wiki links is also easy, see WikiPageNames for details. * In addition, Wiki formatting can be disabled completely in some places (e.g. when rendering commit log messages). See wiki_format_messages in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni. * Wiki formatting can be disabled completely in some places, for example when rendering commit log messages. See wiki_format_messages in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni. See TracIni for more information on the available options. == More information on !CamelCase == == More information on !CamelCase * http://c2.com/cgi/wiki?WikiCase

 r26484 [[PageOutline]] = Trac with FastCGI = = Trac with FastCGI [[TracGuideToc]] [[PageOutline(2-5, Contents, floated)]] [http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers. Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server running with (mod_wsgi supports the WSGIDaemonProcess with user / group parameters to achieve the same effect). Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], ie run with different permissions than the web server runs with. mod_wsgi supports the WSGIDaemonProcess with user / group parameters to achieve the same effect. '''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement Socket.fromfd, which is used by _fcgi.py. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI]. [[PageOutline(2-3,Overview,inline)]] == Simple Apache configuration == == Simple Apache configuration There are two FastCGI modules commonly available for Apache: mod_fastcgi and The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache. Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. (Connection reset by peer: mod_fcgid: error reading data from FastCGI server) === Set up with mod_fastcgi === Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. Connection reset by peer: mod_fcgid: error reading data from FastCGI server. === Set up with mod_fastcgi mod_fastcgi uses FastCgiIpcDir and FastCgiConfig directives that should be added to an appropriate Apache configuration file: {{{ }}} === Set up with mod_fcgid === Configure ScriptAlias (see TracCgi for details), but call trac.fcgi instead of trac.cgi. Note that slash at the end - it is important. === Set up with mod_fcgid Configure ScriptAlias (see TracCgi for details), but call trac.fcgi instead of trac.cgi: {{{ ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/ }}} To set up Trac environment for mod_fcgid it is necessary to use DefaultInitEnv directive. It cannot be used in Directory or Location context, so if you need to support multiple projects, try alternative environment setup below. Note the slash at the end. To set up Trac environment for mod_fcgid it is necessary to use DefaultInitEnv directive. It cannot be used in Directory or Location context, so if you need to support multiple projects, try alternative environment setup below. {{{ }}} === alternative environment setup === A better method to specify path to Trac environment is to embed the path into trac.fcgi script itself. That doesn't require configuration of server environment variables, works for both FastCgi modules (and for [http://www.lighttpd.net/ lighttpd] and CGI as well): === alternative environment setup A better method to specify path to the Trac environment is to embed the path into trac.fcgi script itself. That doesn't require configuration of the server environment variables, works for both [trac:FastCgi] modules as well as for [http://www.lighttpd.net/ lighttpd] and CGI: {{{ import os os.environ['TRAC_ENV'] = "/path/to/projectenv" }}} or or: {{{ import os }}} With this method different projects can be supported by using different .fcgi scripts with different ScriptAliases. With this method different projects can be supported by using different .fcgi scripts with different ScriptAliases. See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this: }}} == Simple Cherokee Configuration == == Simple Cherokee Configuration The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process. You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down. First set up an information source in cherokee-admin with a local interpreter. First set up an information source in cherokee-admin with a local interpreter: {{{ }}} == Simple Lighttpd Configuration == The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd]. lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance environments.  It has a very low memory footprint compared to other web servers and takes care of CPU load. For using trac.fcgi(prior to 0.11) / fcgi_frontend.py (0.11) with lighttpd add the following to your lighttpd.conf: == Simple Lighttpd Configuration The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ Lighttpd]. Lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance environments. It has a very low memory footprint compared to other web servers and takes care of CPU load. For using trac.fcgi(prior to 0.11) / fcgi_frontend.py (0.11) with Lighttpd add the following to your lighttpd.conf: {{{ #var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory }}} Note that you will need to add a new entry to fastcgi.server for each separate Trac instance that you wish to run. Alternatively, you may use the TRAC_ENV_PARENT_DIR variable instead of TRAC_ENV as described above, and you may set one of the two in trac.fcgi instead of in lighttpd.conf using bin-environment (as in the section above on Apache configuration). Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in lighttpd 1.5, and under lighttpd 1.4.23 or later the workaround is to add "fix-root-scriptname" => "enable" as a parameter of fastcgi.server. Note that you will need to add a new entry to fastcgi.server for each separate Trac instance that you wish to run. Alternatively, you may use the TRAC_ENV_PARENT_DIR variable instead of TRAC_ENV as described above, and you may set one of the two in trac.fcgi instead of in lighttpd.conf using bin-environment, as in the section above on Apache configuration. Note that Lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in Lighttpd 1.5, and under Lighttpd 1.4.23 or later the workaround is to add "fix-root-scriptname" => "enable" as a parameter of fastcgi.server. For using two projects with lighttpd add the following to your lighttpd.conf: ) }}} Note that field values are different.  If you prefer setting the environment variables in the .fcgi scripts, then copy/rename trac.fcgi, e.g., to first.fcgi and second.fcgi, and reference them in the above settings. Note that the above will result in different processes in any event, even if both are running from the same trac.fcgi script. Note that field values are different. If you prefer setting the environment variables in the .fcgi scripts, then copy/rename trac.fcgi, eg to first.fcgi and second.fcgi, and reference them in the above settings. Note that the above will result in different processes in any event, even if both are running from the same trac.fcgi script. {{{ ) }}} Note that lighttpd (I use version 1.4.3) stopped if password file doesn't exist. Note that lighttpd doesn't support 'valid-user' in versions prior to 1.3.16. Conditional configuration is also useful for mapping static resources, i.e. serving out images and CSS directly instead of through FastCGI: }}} Note that Lighttpd (v1.4.3) stops if the password file doesn't exist. Note that Lighttpd doesn't support 'valid-user' in versions prior to 1.3.16. Conditional configuration is also useful for mapping static resources, ie serving out images and CSS directly instead of through FastCGI: {{{ # Aliasing functionality is needed } }}} The technique can be easily adapted for use with multiple projects by creating aliases for each of them, and wrapping the fastcgi.server declarations inside conditional configuration blocks. Also there is another way to handle multiple projects and it's to use TRAC_ENV_PARENT_DIR instead of TRAC_ENV and use global auth, let's see an example: }}} Changing date/time format also supported by lighttpd over environment variable LC_TIME Changing date/time format also supported by lighttpd over environment variable LC_TIME: {{{ fastcgi.server = ("/trac" => ] Relaunch lighttpd, and browse to http://yourhost.example.org/trac to access Trac. Note about running lighttpd with reduced permissions: If nothing else helps and trac.fcgi doesn't start with lighttpd settings server.username = "www-data", server.groupname = "www-data", then in the bin-environment section set PYTHON_EGG_CACHE to the home directory of www-data or some other directory accessible to this account for writing. == Simple !LiteSpeed Configuration == Relaunch Lighttpd and browse to http://yourhost.example.org/trac to access Trac. Note about running Lighttpd with reduced permissions: If nothing else helps and trac.fcgi doesn't start with Lighttpd settings server.username = "www-data", server.groupname = "www-data", then in the bin-environment section set PYTHON_EGG_CACHE to the home directory of www-data or some other directory accessible to this account for writing. == Simple !LiteSpeed Configuration The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.litespeedtech.com/ LiteSpeed]. !LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments. 1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first. 2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your trac project will be accessible via: 1. Please make sure you have a working install of a Trac project. Test install with "tracd" first. 2. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your Trac project will be accessible via: {{{ http://yourdomain.com/trac/ }}} 3. Go “!TracVhost → External Apps” tab and create a new “External Application”. 3. Go "!TracVhost → External Apps" tab and create a new "External Application". {{{ Name: MyTracFCGI }}} 4. Optional. If you need to use htpasswd based authentication. Go to “!TracVhost → Security” tab and create a new security “Realm”. 4. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm. {{{ If you don’t have a htpasswd file or don’t know how to create the entries within one, go to http://sherylcanter.com/encrypt.php, to generate the user:password combos. 5. Go to “!PythonVhost → Contexts” and create a new “FCGI Context”. 5. Go to "!PythonVhost → Contexts" and create a new FCGI Context. {{{ }}} == Simple Nginx Configuration == == Simple Nginx Configuration Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately. 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32 {{{ {{{ server { listen       10.9.8.7:443; ssl_prefer_server_ciphers   on; # (Or ^/some/prefix/(.*). if ($uri ~ ^/(.*)) { set$path_info /$1; # it makes sense to serve static resources through Nginx (or ~ [/some/prefix]/chrome/(.*)) location ~ /chrome/(.*) { alias /home/trac/instance/static/htdocs/$1; } # it makes sense to serve static resources through Nginx location /chrome/ { alias /home/trac/instance/static/htdocs/; } # You can copy this whole location to location [/some/prefix]/login # You can copy this whole location to location [/some/prefix](/login) # and remove the auth entries below if you want Trac to enforce # authorization where appropriate instead of needing to authenticate # for accessing the whole site. # (Or location /some/prefix.) location / { # (Or ~ location /some/prefix(/.*).) location ~ (/.*) { auth_basic            "trac realm"; auth_basic_user_file /home/trac/htpasswd; # (Or fastcgi_param  SCRIPT_NAME  /some/prefix.) fastcgi_param  SCRIPT_NAME        ""; fastcgi_param  PATH_INFO          $path_info; fastcgi_param PATH_INFO$1; ## WSGI NEEDED VARIABLES - trac warns about them } }}} 2. Modified trac.fcgi: {{{ 1. Modified trac.fcgi: {{{ #!/usr/bin/env python import os }}} 3. reload nginx and launch trac.fcgi like that: {{{ 1. reload nginx and launch trac.fcgi like that: {{{#!sh trac@trac.example ~ $./trac-standalone-fcgi.py }}} The above assumes that: * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory. * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory * /home/trac/instance contains a trac environment * /home/trac/htpasswd contains authentication information Unfortunately nginx does not support variable expansion in fastcgi_pass directive. Thus it is not possible to serve multiple trac instances from one server block. If you worry enough about security, run trac instances under separate users. Another way to run trac as a FCGI external application is offered in ticket #T6224 Thus it is not possible to serve multiple Trac instances from one server block. If you worry enough about security, run Trac instances under separate users. Another way to run Trac as a FCGI external application is offered in ticket #T6224 ---- • ## wiki/pages/TracFineGrainedPermissions  r26484 = Fine grained permissions = [[PageOutline(2-5, Contents, floated)]] = Fine grained permissions = Before Trac 0.11, it was only possible to define fine-grained permissions checks on the repository browser sub-system. Since 0.11, there's a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resources, even at the level of specific versions of such resources. Note that for Trac 0.12, authz_policy has been integrated as an optional module (in tracopt.perm.authz_policy.*), so it's installed by default and can simply be activated via the //Plugins// panel in the Trac administration module. [[TracGuideToc]] There is a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resource, even at the level of specific versions of such resources. That mechanism is authz_policy, which is an optional module in tracopt.perm.authz_policy.*, so it is installed by default. It can be activated via the //Plugins// panel in the Trac administration module. == Permission Policies == A great diversity of permission policies can be implemented, and Trac comes with a few examples. A great diversity of permission policies can be implemented and Trac comes with a few examples. Which policies are currently active is determined by a configuration setting in TracIni: e.g. {{{ [trac] permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} This lists the [#AuthzSourcePolicy] described below as the first policy, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments. Among the possible optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See [trac:source:branches/0.12-stable/tracopt/perm/authz_policy.py authz_policy.py] for details. {{{#!ini [trac] permission_policies = ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} This lists the [#ReadonlyWikiPolicy] which controls readonly access to wiki pages, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments. Among the optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See [trac:source:branches/1.0-stable/tracopt/perm/authz_policy.py authz_policy.py] for details. Another popular permission policy [#AuthzSourcePolicy], re-implements the pre-0.12 support for checking fine-grained permissions limited to Subversion repositories in terms of the new system. See also [trac:source:branches/0.12-stable/sample-plugins/permissions sample-plugins/permissions] for more examples. See also [trac:source:branches/1.0-stable/sample-plugins/permissions sample-plugins/permissions] for more examples. === !AuthzPolicy === ==== Configuration ==== * Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12). * Copy authz_policy.py into your plugins directory (only for Trac 0.11). * Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the file contains non-ASCII characters, the UTF-8 encoding should be used. * Update your trac.ini: 1. modify the [TracIni#trac-section permission_policies] entry in the [trac] section {{{ 1. modify the [TracIni#trac-section permission_policies] entry in the [trac] section: {{{#!ini [trac] ... permission_policies = AuthzPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} 1. add a new [authz_policy] section {{{ permission_policies = AuthzPolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} 1. add a new [authz_policy] section: {{{#!ini [authz_policy] authz_file = /some/trac/env/conf/authzpolicy.conf }}} 1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the [components] section {{{ 1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the [components] section: {{{#!ini [components] ... # Trac 0.12 tracopt.perm.authz_policy.* = enabled # for Trac 0.11 use this #authz_policy.* = enabled }}} }}} ==== Usage Notes ==== Note that the order in which permission policies are specified is quite critical, as policies will be examined in the sequence provided. Note the order in which permission policies are specified: policies are implemented in the sequence provided and therefore may override earlier policy specifications. A policy will return either True, False or None for a given permission check. True is returned if the policy explicitly grants the permission. False is returned if the policy explicitly denies the permission. None is returned if the policy is unable to either grant or deny the permission. NOTE: Only if the return value is None will the ''next'' permission policy be consulted. If none of the policies explicitly grants the permission, the final result will be False (i.e. permission denied). NOTE: Only if the return value is None will the ''next'' permission policy be consulted. If none of the policies explicitly grants the permission, the final result will be False, i.e. permission denied. The authzpolicy.conf file is a .ini style configuration file: {{{ {{{#!ini [wiki:PrivatePage@*] john = WIKI_VIEW, !WIKI_MODIFY * = }}} * Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form: * Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form: {{{ :@[/:@ ...] }}} Resources are ordered left to right, from parent to child. If any component is inapplicable, * is substituted. If the version pattern is not specified explicitely, all versions (@*) is added implicitly Example: Match the WikiStart page {{{ Resources are ordered left to right, from parent to child. If any component is inapplicable, * is substituted. If the version pattern is not specified explicitly, all versions (@*) is added implicitly. Example: Match the WikiStart page: {{{#!ini [wiki:*] [wiki:WikiStart*] }}} Example: Match the attachment wiki:WikiStart@117/attachment/FOO.JPG@* on WikiStart {{{ Example: Match the attachment wiki:WikiStart@117/attachment:FOO.JPG@* on WikiStart: {{{#!ini [wiki:*] [wiki:WikiStart*] [wiki:WikiStart@*] [wiki:WikiStart@*/attachment/*] [wiki:WikiStart@117/attachment/FOO.JPG] }}} * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''. * Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''. [wiki:WikiStart@*/attachment:*] [wiki:WikiStart@117/attachment:FOO.JPG] }}} * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''. * Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''. * If a key (username) is prefixed with a @, it is treated as a group. * If a value (permission) is prefixed with a !, the permission is denied rather than granted. The username will match any of 'anonymous', 'authenticated', or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature || * If a value (permission) is prefixed with a !, the permission is denied rather than granted. The username will match any of 'anonymous', 'authenticated', or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature. || For example, if the authz_file contains: {{{ {{{#!ini [wiki:WikiStart@*] * = WIKI_VIEW Then: * All versions of WikiStart will be viewable by everybody (including anonymous) * All versions of WikiStart will be viewable by everybody, including anonymous * !PrivatePage will be viewable only by john * other pages will be viewable only by john and jack Groups: {{{ {{{#!ini [groups] admins = john, jack Some repository examples (Browse Source specific): {{{ {{{#!ini # A single repository: [repository:test_repo@*] john = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW for the entire test_repo # The default repository (requires Trac 1.0.2 or later): [repository:@*] john = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW for the entire default repository # All repositories: [repository:*@*] jack = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW for all repositories }}} Very fine grain repository access: {{{ # Jack has BROWSER_VIEW and FILE_VIEW for all repositories }}} Very granular repository access: {{{#!ini # John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only [repository:test_repo@*/source:trunk/src/some/location/*@*] john = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only [repository:test_repo@*/source:trunk/src/some/location/*@1] john = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only [repository:test_repo@*/source:trunk/src/some/location/somefile@*] john = BROWSER_VIEW, FILE_VIEW # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only [repository:test_repo@*/source:trunk/src/some/location/somefile@1] Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list. ==== Missing Features ==== Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see forgotten authz_policy.2.patch part of [trac:ticket:6680 #6680]). Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see authz_policy.2.patch, part of [trac:ticket:6680 #6680]. You cannot do the following: {{{ {{{#!ini [groups] team1 = a, b, c }}} Permission groups are not supported either. You cannot do the following: {{{ Permission groups are not supported either, so you cannot do the following: {{{#!ini [groups] permission_level_1 = WIKI_VIEW, TICKET_VIEW === !AuthzSourcePolicy (mod_authz_svn-like permission policy) === #AuthzSourcePolicy At the time of this writing, the old fine grained permissions system from Trac 0.11 and before used for restricting access to the repository has been converted to a permission policy component, but from the user point of view, this makes little if no difference. That kind of fine-grained permission control needs a definition file, which is the one used by Subversion's mod_authz_svn. More information about this file format and about its usage in Subversion is available in the [http://svnbook.red-bean.com/en/1.5/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book. At the time of this writing, the old granular permissions system from Trac 0.11 and before used for restricting access to the repository has been converted to a permission policy component. But from the user's point of view, this makes little if any difference. That kind of granular permission control needs a definition file, which is the one used by Subversion's mod_authz_svn. More information about this file format and about its usage in Subversion is available in the [http://svnbook.red-bean.com/en/1.5/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book. Example: {{{ {{{#!ini [/] * = r ==== Trac Configuration ==== To activate fine grained permissions you __must__ specify the {{{authz_file}}} option in the {{{[trac]}}} section of trac.ini. If this option is set to null or not specified the permissions will not be used. {{{ [trac] To activate granular permissions you __must__ specify the {{{authz_file}}} option in the [svn] section of trac.ini. If this option is set to null or not specified, the permissions will not be used. {{{#!ini [svn] authz_file = /path/to/svnaccessfile }}} If you want to support the use of the [''modulename'':/''some''/''path''] syntax within the authz_file, add {{{ If you want to support the use of the [''modulename'':/''some''/''path''] syntax within the authz_file, add: {{{#!ini authz_module_name = modulename }}} where ''modulename'' refers to the same repository indicated by the repository_dir entry in the [trac] section. As an example, if the repository_dir entry in the [trac] section is {{{/srv/active/svn/blahblah}}}, that would yield the following: {{{ [trac] where ''modulename'' refers to the same repository indicated by the .dir entry in the [repositories] section. As an example, if the somemodule.dir entry in the [repositories] section is /srv/active/svn/somemodule, that would yield the following: {{{ #!ini [svn] authz_file = /path/to/svnaccessfile authz_module_name = blahblah authz_module_name = somemodule ... repository_dir = /srv/active/svn/blahblah }}} where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[blahblah:/some/path]}}}. [repositories] somemodule.dir = /srv/active/svn/somemodule }}} where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[somemodule:/some/path]}}}. '''Note:''' Usernames inside the Authz file __must__ be the same as those used inside trac. As of version 0.12, make sure you have ''!AuthzSourcePolicy'' included in the permission_policies list in trac.ini, otherwise the authz permissions file will be ignored. {{{ [trac] permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy {{{#!ini [trac] permission_policies = AuthzSourcePolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this: {{{ {{{#!apache DAV svn }}} For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess] For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess]. === ReadonlyWikiPolicy Since 1.1.2, the read-only attribute of wiki pages is enabled and enforced when ReadonlyWikiPolicy is in the list of active permission policies. The default for new Trac installations in 1.1.2 and later is: {{{ [trac] permission_policies = ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} When upgrading from earlier versions of Trac, ReadonlyWikiPolicy will be appended to the list of permission_policies when upgrading the environment, provided that permission_policies has the default value. If any non-default permission_polices are active, ReadonlyWikiPolicy **will need to be manually added** to the list. A message will be echoed to the console when upgrading the environment, indicating if any action needs to be taken. **!ReadonlyWikiPolicy must be listed //before// !DefaultPermissionPolicy**. The latter returns True to allow modify, delete or rename actions when the user has the respective WIKI_* permission, without consideration for the read-only attribute. The ReadonlyWikiPolicy returns False to deny modify, delete and rename actions on wiki pages when the page has the read-only attribute set and the user does not have WIKI_ADMIN, regardless of WIKI_MODIFY, WIKI_DELETE and WIKI_RENAME permissions. It returns None for all other cases. When active, the [#AuthzPolicy] should therefore come before ReadonlyWikiPolicy, allowing it to grant or deny the actions on individual resources, which is the usual ordering for AuthzPolicy in the permission_policies list. {{{ [trac] permission_policies = AuthzPolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} The placement of [#AuthzSourcePolicy] relative to ReadonlyWikiPolicy does not matter since they don't perform checks on the same realms. For all other permission policies, the user will need to decide the proper ordering. Generally, if the permission policy should be capable of overriding the check performed by ReadonlyWikiPolicy, it should come before ReadonlyWikiPolicy in the list. If the ReadonlyWikiPolicy should override the check performed by another permission policy, as is the case for DefaultPermissionPolicy, then ReadonlyWikiPolicy should come first. == Debugging permissions In trac.ini set: {{{ {{{#!ini [logging] log_file = trac.log }}} And watch: {{{ Display the trac.log to understand what checks are being performed: {{{#!sh tail -n 0 -f log/trac.log | egrep '$perm$|$authz_policy$' }}} to understand what checks are being performed. See the sourced documentation of the plugin for more info. See the sourced documentation of the plugin for more info. ---- • ## wiki/pages/TracGuide  r26484 * TracSupport — How to get more information If you are looking for a good place to ask a question about Trac, look no further than the [http://trac.edgewall.org/wiki/MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers. If you are looking for a good place to ask a question about Trac, look no further than the [trac:MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers. • ## wiki/pages/TracImport  r26484 [[PageOutline]] By means of migrating from other issue-tracking systems, perform some external actions over tickets or simply synchronize different data bases, there are some available tools, plug-ins or scripts which lets you import or up-date tickets into Trac. Below, follows a collection of some of those. To migrate issue tickets from other issue-tracking systems or perform housekeeping actions on tickets or simply synchronize different databases, there are some tools, plug-ins and scripts available, which let you import or update tickets into Trac. == !TicketImportPlugin == [http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin] :: mainly, but not only, this plug-in lets you import or up-date into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel file'''. [http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin]: this plug-in lets you import or update into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel spreadsheet'''. == !ExportImportXlsPlugin == [http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin] :: this plug-in add an admin panel for export and import tickets via '''XLS file'''. * It depends on the python packages xlwt/rxld. [http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin]: this plug-in adds an admin panel for exporting and importing tickets via '''XLS file'''. Requires the python packages xlwt/rxld. == Bugzilla == [http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin] :: integrates Bugzilla into Trac keeping TracLinks Ticket data can be imported from Bugzilla using the [http://trac.edgewall.org/browser/trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution. [http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin]: integrates Bugzilla issue data into Trac keeping TracLinks. Ticket data can be imported from Bugzilla using the [trac:browser:trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution. {{{ Currently, the following data is imported from Bugzilla: * bugs * bug activity (field changes) The script provides a number of features to ease the conversion, such as: * PRODUCT_KEYWORDS: Trac doesn't have the concept of products, so the script provides the ability to attach a ticket keyword instead. * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp. * STATUS_KEYWORDS: Attach ticket keywords for the Bugzilla statuses not available in Trac. By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords. * PRODUCT_KEYWORDS: Trac has no concept of products, so the script provides the ability to attach a ticket keyword instead. * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp. * STATUS_KEYWORDS: Attach ticket keywords for the Bugzilla statuses not available in Trac. By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords. For more details on the available options, see the configuration section at the top of the script. === Known Issues === {{{ #!comment Don't merge this section in the default page }}} [[TicketQuery(keywords=~bugzilla,status=!closed)]] The adequate milestone for valid bugzilla2trac issue is usually ''Not applicable'', which means that fixes to the contributed script are not planned for a particular Trac release, but can happen anytime. == Jira == [http://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration] :: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that: - Parses the Jira backup XML file - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords [http://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration]: provides tools to import Atlassian Jira backup files into Trac. The plug-in consists of a Python 3.1 commandline tool that: - Parses the Jira backup XML file. - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]. - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords. == Mantis == [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript] :: script to import from Mantis into Trac the following data: [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: script to import the following data from Mantis into Trac: * bugs * bug comments == !PlanetForge == [http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin] :: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Still has no 'import' feature. [http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin]: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Has no 'import' feature. == Scarab == [http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript] :: script that migrates Scarab issues to Trac tickets * Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] [http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript]: script that migrates Scarab issues to Trac tickets. Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] == Sourceforge == [http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript] :: importer of !SourceForge's new backup file (originated from #Trac3521) Also, ticket data can be imported from Sourceforge using the [http://trac.edgewall.org/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution. [http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript]: importer of !SourceForge's new backup file (originated from #Trac3521). Also, ticket data can be imported from Sourceforge using the [trac:browser:trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution. == Other == Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import into them from your application. Since Trac uses a SQL database to store the data, you can also custom-import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import them from your application. === Comma delimited file - CSV === See [http://trac.edgewall.org/attachment/wiki/TracSynchronize/csv2trac.2.py csv2trac.2.py] for details. This approach is particularly useful if one needs to enter a large number of tickets by hand. (note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases) Comments on script: The script has an error on line 168, ('Ticket' needs to be 'ticket'). Also, the listed values for severity and priority are swapped. See [trac:attachment:csv2trac.2.py:wiki:TracSynchronize csv2trac.2.py] for details. This approach is particularly useful if you need to enter a large number of tickets by hand. Note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases. Comments on script: The script has an error on line 168: 'Ticket' needs to be 'ticket'. Also, the listed values for severity and priority are swapped. ---- • ## wiki/pages/TracIni  r26484 = The Trac Configuration File = ''[Note To Editors] Please discuss documentation changes in the [#Discussion] section. Even better, send us [TracDev/SubmittingPatches documentation patches] against the ''code'' (i.e. where the configuration entries are documented), either on Trac-dev or on new tickets. '' = The Trac Configuration File [[TracGuideToc]] [[PageOutline]] Trac configuration is done by editing the '''trac.ini''' config file, located in /conf/trac.ini. Changes to the configuration are usually reflected immediately, though changes to the [components] or [logging] sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present. Trac is configured by editing the **trac.ini** file, located in the /conf directory. The trac.ini configuration file and its parent directory should be writable by the web server. The trac.ini configuration file and its parent directory should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches. Trac monitors the timestamp of the file to trigger a complete environment reload and flush its caches when the timestamp changes. Most changes to the configuration will be reflected immediately, though changes to the [components] or [logging] sections will require restarting the web server. You may also need to restart the web server after creating a [#GlobalConfiguration global configuration] file when none was previously present. == Global Configuration == == Global Configuration In versions prior to 0.11, the global configuration was by default located in $prefix/share/trac/conf/trac.ini or /etc/trac/trac.ini, depending on the distribution. If you're upgrading, you may want to specify that file to inherit from.  Literally, when you're upgrading to 0.11, you have to add an [inherit] section to your project's trac.ini file. Additionally, you have to move your customized templates and common images from $prefix/share/trac/... to the new location. Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows: {{{ Configuration can be shared among environments using one or more global configuration files. Options in the global configuration will be merged with the environment-specific options, with local options overriding global options. The global configuration file is specified as follows: {{{#!ini [inherit] file = /path/to/global/trac.ini There are two more entries in the [[#inherit-section| [inherit] ]] section, templates_dir for sharing global templates and plugins_dir, for sharing plugins. Those entries can themselves be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another [inherit] file there. Note that the templates found in the templates/ directory of the TracEnvironment have precedence over those found in [inherit] templates_dir. In turn, the latter have precedence over the installed templates, so be careful about what you put there, notably if you override a default template be sure to refresh your modifications when you upgrade to a new version of Trac (the preferred way to perform TracInterfaceCustomization being still to write a custom plugin doing an appropriate ITemplateStreamFilter transformation). Note that the templates found in the templates/ directory of the TracEnvironment have precedence over those found in [inherit] templates_dir. In turn, the latter have precedence over the installed templates, so be careful about what you put there. Notably, if you override a default template, refresh your modifications when you upgrade to a new version of Trac. The preferred way to perform TracInterfaceCustomization is still to write a custom plugin doing an appropriate ITemplateStreamFilter transformation. == Reference for settings This is a brief reference of available configuration options, and their default settings. Documentation improvements should be discussed on the [trac:MailingList#Trac-dev trac-dev mailing list] or described in a [trac:NewTicket ticket]. Even better, [trac:TracDev/SubmittingPatches submit a patch] against the docstrings in the code. {{{ #!comment Please don't waste your time by editing the HTML code below, changes won't be picked up. Instead, follow the above guidance for suggesting documentation improvements. }}} [[TracIni]] • ## wiki/pages/TracInstall  r26484 = Trac Installation Guide for 1.0 = = Trac Installation Guide for 1.1 [[TracGuideToc]] Trac is written in the Python programming language and needs a database, [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], or [http://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://genshi.edgewall.org Genshi] templating system. Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default english version, as usual. If you're interested in contributing new translations for other languages or enhance the existing translations, then please have a look at [[trac:TracL10N]]. What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to '''first read through these general instructions''' to get a good understanding of the tasks involved. Trac can also be localized, and there is probably a translation available in your language. If you want to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version. If you're interested in contributing new translations for other languages or enhancing the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N]. What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms], please '''first read through these general instructions''' to get a good understanding of the tasks involved. [[PageOutline(2-3,Installation Steps,inline)]] == Dependencies == == Dependencies === Mandatory Dependencies To install Trac, the following software packages must be installed: * [http://www.python.org/ Python], version >= 2.5 and < 3.0 (note that we dropped the support for Python 2.4 in this release) * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6, or better yet, [http://pypi.python.org/pypi/distribute distribute] * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 (unreleased version 0.7dev should work as well) You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL. * [http://www.python.org/ Python], version >= 2.6 and < 3.0 (note that we dropped the support for Python 2.5 in this release) * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6 * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL. ==== For the SQLite database #ForSQLite As you must be using Python 2.5, 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the sqlite3 module). However, if you'd like, you can download the latest and greatest version of [[trac:Pysqlite]] from [http://code.google.com/p/pysqlite/downloads/list google code], where you'll find the Windows installers or the tar.gz archive for building from source: {{{$ tar xvfz .tar.gz $cd$ python setup.py build_static install }}} This will download the latest SQLite code and build the bindings. SQLite 2.x is no longer supported. A known bug PySqlite versions 2.5.2-4 prohibits upgrade of trac databases from 0.11.x to 0.12. Please use versions 2.5.5 and newer or 2.5.1 and older. See #9434 for more detail. See additional information in [trac:PySqlite PySqlite]. As you must be using Python 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the sqlite3 module). Optionally, you may install a newer version of [pypi:pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details. ==== For the PostgreSQL database #ForPostgreSQL You need to install the database and its Python bindings: * [http://www.postgresql.org/ PostgreSQL], version 8.0 or later * [http://pypi.python.org/pypi/psycopg2 psycopg2] * [http://pypi.python.org/pypi/psycopg2 psycopg2], version 2.0 or later See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details. ==== For the MySQL database #ForMySQL Trac can now work quite well with MySQL, provided you follow the guidelines. Trac works well with MySQL, provided you follow the guidelines: * [http://mysql.com/ MySQL], version 5.0 or later * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later It is '''very''' important to read carefully the [trac:MySqlDb] page before creating the database. Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database. === Optional Dependencies ==== Version Control System ==== ===== Subversion ===== * [http://subversion.apache.org/ Subversion], 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. TracSubversion points you to [http://alagazam.net Algazam], which works for me under Python 2.6.) Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer ctype-style bindings. '''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. ===== Others ===== Support for other version control systems is provided via third-parties. See [trac:PluginList] and [trac:VersionControlSystem]. ==== Web Server ==== A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server ] section below. Alternatively you configure Trac to run in any of the following environments. ==== Subversion [http://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings. There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. [trac:TracSubversion] points you to [http://alagazam.net Alagazam], which works for me under Python 2.6.) For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page. {{{#!div style="border: 1pt dotted; margin: 1em" **Note:** * Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer ctype-style bindings. * If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. }}} ==== Git [http://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page. ==== Other Version Control Systems Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem]. ==== Web Server A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below. Alternatively you can configure Trac to run in any of the following environments: * [http://httpd.apache.org/ Apache] with - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac - [http://modpython.org/ mod_python 3.3.1], deprecated: see TracModPython) - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac]. - [http://modpython.org/ mod_python 3.5.0], see TracModPython * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi) * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp]) * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI]) * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script is highly discouraged''', better use one of the previous options. ==== Other Python Packages ==== * [http://babel.edgewall.org Babel], version >= 0.9.5, needed for localization support (unreleased version 1.0dev should work as well) ==== Other Python Packages * [http://babel.edgewall.org Babel], version 0.9.6 or >= 1.3, needed for localization support * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9 for WikiRestructuredText. * [http://pygments.pocoo.org Pygments] for [wiki:TracSyntaxColoring syntax highlighting]. [http://silvercity.sourceforge.net/ SilverCity] and/or [http://gnu.org/software/enscript/enscript.html Enscript] may still be used but are deprecated and you really should be using Pygments. * [http://pygments.org Pygments] for [TracSyntaxColoring syntax highlighting]. * [http://pytz.sf.net pytz] to get a complete list of time zones, otherwise Trac will fall back on a shorter list from an internal time zone implementation. '''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel]. Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing'' (there are even some pages that are still talking about Trac 0.8!). == Installing Trac == {{{#!div style="border: 1pt dotted; margin: 1em" **Attention**: The available versions of these dependencies are not necessarily interchangeable, so please pay attention to the version numbers. If you are having trouble getting Trac to work, please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel]. }}} Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''. == Installing Trac The [TracAdmin trac-admin] command-line tool, used to create and maintain [TracEnvironment project environments], as well as the [TracStandalone tracd] standalone server are installed along with Trac. There are several methods for installing Trac. === Using easy_install One way to install Trac is using [http://pypi.python.org/pypi/setuptools setuptools]. With setuptools you can install Trac from the subversion repository; Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools]. A few examples: - install Trac 1.0: {{{ - Install Trac 1.0: {{{#!sh easy_install Trac==1.0 }}} (NOT YET ENABLED) - install latest development version 1.0dev: {{{ - Install latest development version: {{{#!sh easy_install Trac==dev }}} either use a released version or install from source More information can be found on the [trac:setuptools] page. {{{#!div style="border: 1pt dotted; margin: 1em" **Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable PKG_RESOURCES_CACHE_ZIP_MANIFESTS must be set in order to avoid significant performance degradation. More information may be found in the sections on [#RunningtheStandaloneServer Running The Standalone Server] and [#RunningTraconaWebServer Running Trac on a Web Server]. }}} === Using pip 'pip' is an easy_install replacement that is very useful to quickly install python packages. To get a trac installation up and running in less than 5 minutes: To get a Trac installation up and running in less than 5 minutes: Assuming you want to have your entire pip installation in /opt/user/trac - {{{ pip -E /opt/user/trac install trac psycopg2 {{{#!sh pip install trac psycopg2 }}} or - {{{ pip -E /opt/user/trac install trac mysql-python }}} Make sure your OS specific headers are available for pip to automatically build PostgreSQL (libpq-dev) or MySQL (libmysqlclient-dev) bindings. pip will automatically resolve all dependencies (like Genshi, pygments, etc.) and download the latest packages on pypi.python.org and create a self contained installation in /opt/user/trac. {{{#!sh pip install trac mysql-python }}} Make sure your OS specific headers are available for pip to automatically build PostgreSQL (libpq-dev) or MySQL (libmysqlclient-dev) bindings. pip will automatically resolve all dependencies (like Genshi, pygments, etc.), download the latest packages from pypi.python.org and create a self contained installation in /opt/user/trac. All commands (tracd, trac-admin) are available in /opt/user/trac/bin. This can also be leveraged for mod_python (using PythonHandler directive) and mod_wsgi (using WSGIDaemonProcess directive) Additionally, you can install several trac plugins (listed [http://pypi.python.org/pypi?:action=search&term=trac&submit=search here]) through pip. Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip. === From source Of course, using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. Trac-1.0.tar.gz), or you can get the source directly from the repository (see Trac:SubversionRepository for details). {{{ Using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. Trac-1.0.tar.gz) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details. {{{#!sh $python ./setup.py install }}} ''You'll need root permissions or equivalent for this step.'' This will byte-compile the python source code and install it as an .egg file or folder in the site-packages directory of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates. The script will also install the [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments], as well as the [wiki:TracStandalone tracd] standalone server. If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the install (or simply redo the install once again afterwards if you realize Babel was not yet installed): {{{ ''You will need root permissions or equivalent for this step.'' This will byte-compile the Python source code and install it as an .egg file or folder in the site-packages directory of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates. If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the install (or simply redo the install once again afterwards if you realize Babel was not yet installed): {{{#!sh$ python ./setup.py install }}} Alternatively, you can do a bdist_egg and copy the .egg from dist/ to the place of your choice, or you can create a Windows installer (bdist_wininst). === Advanced Options === Alternatively, you can run bdist_egg and copy the .egg from dist/ to the place of your choice, or you can create a Windows installer (bdist_wininst). === Using installer On Windows, Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32-bit and 64-bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation. === Using package manager Trac may be available in your platform's package repository. Note however, that the version provided by your package manager may not be the latest release. === Advanced easy_install Options To install Trac to a custom location, or find out about other advanced installation options, run: {{{ {{{#!sh easy_install --help }}} Also see [http://docs.python.org/inst/inst.html Installing Python Modules] for detailed information. Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information. Specifically, you might be interested in: {{{ {{{#!sh easy_install --prefix=/path/to/installdir }}} or, if installing Trac to a Mac OS X system: {{{ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages }}} Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.6/site-packages }}} by default The above will place your tracd and trac-admin commands into /usr/local/bin and will install the Trac libraries and dependencies into /Library/Python/2.5/site-packages, which is Apple's preferred location for third-party Python application installations. == Creating a Project Environment == A [TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable [TracIni configuration file], and various other files and directories. A new environment is created using [wiki:TracAdmin trac-admin]: {{{ or, if installing Trac on a Mac OS X system: {{{#!sh easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages }}} {{{#!div style="border: 1pt dotted; margin: 1em" **Mac OS X Note:** On Mac OS X 10.6,  running easy_install trac will install into /usr/local and /Library/Python/2.6/site-packages by default. The tracd and trac-admin commands will be placed in /usr/local/bin and will install the Trac libraries and dependencies into /Library/Python/2.6/site-packages, which is Apple's preferred location for third-party Python application installations. }}} == Creating a Project Environment A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is a directory that contains a human-readable [TracIni configuration file], and other files and directories. A new environment is created using [TracAdmin trac-admin]: {{{#!sh $trac-admin /path/to/myproject initenv }}} [TracAdmin trac-admin] will prompt you for the information it needs to create the environment, such as the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for one of these options, just press  to use the default value. Using the default database connection string in particular will always work as long as you have SQLite installed. For the other [DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point. Since 0.12, Trac doesn't ask for a [TracEnvironment#SourceCodeRepository source code repository] anymore when creating an environment. Repositories can be [TracRepositoryAdmin added] afterward, or the version control support can be disabled completely if you don't need it. Also note that the values you specify here can be changed later by directly editing the [TracIni conf/trac.ini] configuration file. [TracAdmin trac-admin] will prompt you for the information it needs to create the environment: the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for any of these options, just press  to use the default value. Using the default database connection string will always work as long as you have SQLite installed. For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point. Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file. {{{#!div style="border: 1pt dotted; margin: 1em" **Filesystem Warning:** When selecting the location of your environment, make sure that the filesystem on which the environment directory resides supports sub-second timestamps (i.e. **not** ext2 or ext3 on Linux, or HFS+ on OSX), as the modification time of the conf/trac.ini file will be monitored to decide whether an environment restart is needed or not. A too coarse-grained timestamp resolution may result in inconsistencies in Trac < 1.0.2. The best advice is to opt for a platform with sub-second timestamp resolution, regardless of the Trac version. }}} Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run trac-admin ... initenv as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user apache and group apache, enter: {{{ # chown -R apache.apache /path/to/myproject }}} {{{#!sh$ chown -R apache:apache /path/to/myproject }}} The actual username and groupname of the apache server may not be exactly apache, and are specified in the Apache configuration file by the directives User and Group (if Apache httpd is what you use). {{{#!div class=important }}} == Deploying Trac === Running the Standalone Server === After having created a Trac environment, you can easily try the web interface by running the standalone server [wiki:TracStandalone tracd]: {{{ === Running the Standalone Server After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]: {{{#!sh $tracd --port 8000 /path/to/myproject }}} Then, fire up a browser and visit http://localhost:8000/. You should get a simple listing of all environments that tracd knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this: {{{ {{{#!sh$ tracd -s --port 8000 /path/to/myproject }}} === Running Trac on a Web Server === {{{#!div style="border: 1pt dotted; margin: 1em" **Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable PKG_RESOURCES_CACHE_ZIP_MANIFESTS must be set in order to avoid significant performance degradation. The environment variable can be set system-wide, or for just the user that runs the tracd process. There are several ways to accomplish this in addition to what is discussed here, and depending on the distribution of your OS. To be effective system-wide a shell script with the export statement may be added to /etc/profile.d. To be effective for a user session the export statement may be added to ~/.profile. {{{#!sh export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 }}} Alternatively, the variable can be set in the shell before executing tracd: {{{#!sh $PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject }}} }}} === Running Trac on a Web Server Trac provides various options for connecting to a "real" web server: - [wiki:TracFastCgi FastCGI] - [TracFastCgi FastCGI] - [wiki:TracModWSGI mod_wsgi] - //[wiki:TracModPython mod_python] (no longer recommended, as mod_python is not actively maintained anymore)// - //[wiki:TracCgi CGI] (should not be used, as the performance is far from optimal)// - [TracModPython mod_python] - //[TracCgi CGI] (should not be used, as the performance is far from optimal)// Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc. ==== Generating the Trac cgi-bin directory ==== #cgi-bin In order for Trac to function properly with FastCGI you need to have a trac.fcgi file and for mod_wsgi a trac.wsgi file. These are Python scripts which load the appropriate Python code. They can be generated using the deploy option of [wiki:TracAdmin trac-admin]. There is, however, a bit of a chicken-and-egg problem. The [wiki:TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this: {{{ ==== Generating the Trac cgi-bin directory #cgi-bin In order for Trac to function properly with FastCGI you need to have a trac.fcgi file and for mod_wsgi a trac.wsgi file. These are Python scripts which load the appropriate Python code. They can be generated using the deploy option of [TracAdmin trac-admin]. There is, however, a bit of a chicken-and-egg problem. The [TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this: {{{#!sh mkdir -p /usr/share/trac/projects/my-project trac-admin /usr/share/trac/projects/my-project initenv mv /tmp/deploy/* /usr/share/trac }}} ==== Mapping Static Resources ==== Don't forget to check that the web server has the execution right on scripts in the /usr/share/trac/cgi-bin directory. ==== 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). There are two primary URL paths for static resources - /chrome/common and /chrome/site. Plugins can add their own resources, usually accessible by /chrome/ path, so its important to override only known paths and not try to make universal /chrome alias for everything. Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the [TracAdmin trac-admin] deploy command: Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the TracAdmin deploy command: [[TracAdminHelp(deploy)]] - / - one directory for each resource directory managed by the plugins enabled for this environment ===== Example: Apache and ScriptAlias ===== #ScriptAlias-example ===== Example: Apache and ScriptAlias #ScriptAlias-example Assuming the deployment has been done this way: {{{$ trac-admin /var/trac/env deploy /path/to/trac/htdocs/common {{{#!sh $trac-admin /var/trac/env deploy /path/to/shared/trac }}} Add the following snippet to Apache configuration ''before'' the ScriptAlias or WSGIScriptAlias (which map all the other requests to the Trac application), changing paths to match your deployment: {{{ {{{#!apache Alias /trac/chrome/common /path/to/trac/htdocs/common Alias /trac/chrome/site /path/to/trac/htdocs/site If using mod_python, you might want to add this too (otherwise, the alias will be ignored): {{{ {{{#!apache SetHandler None }}} Note that we mapped /trac part of the URL to the trac.*cgi script, and the path /trac/chrome/common is the path you have to append to that location to intercept requests to the static resources. Note that we mapped the /trac part of the URL to the trac.*cgi script, and the path /trac/chrome/common is the path you have to append to that location to intercept requests to the static resources. Similarly, if you have static resources in a project's htdocs directory (which is referenced by /trac/chrome/site URL in themes), you can configure Apache to serve those resources (again, put this ''before'' the ScriptAlias or WSGIScriptAlias for the .*cgi scripts, and adjust names and locations to match your installation): {{{ {{{#!apache Alias /trac/chrome/site /path/to/projectenv/htdocs }}} Alternatively to aliasing /trac/chrome/common, you can tell Trac to generate direct links for those static resources (and only those), using the [[wiki:TracIni#trac-section| [trac] htdocs_location]] configuration setting: {{{ Alternatively to aliasing /trac/chrome/common, you can tell Trac to generate direct links for those static resources (and only those), using the [[TracIni#trac-section| [trac] htdocs_location]] configuration setting: {{{#!ini [trac] htdocs_location = http://static.example.org/trac-common/ Of course, you still need to make the Trac htdocs/common 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: {{{ {{{#!sh$ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common }}} ==== Setting up the Plugin Cache ==== Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions on how to set environment variables. == Configuring Authentication == Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the .../login URL is hit (the virtual path of the "login" button). Trac will automatically pick the REMOTE_USER variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info. ==== Setting up the Plugin Cache Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions on how to set environment variables. == Configuring Authentication Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the .../login URL is hit (the virtual path of the "login" button). Trac will automatically pick the REMOTE_USER variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info. The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. Please refer to one of the following sections: * TracStandalone#UsingAuthentication if you use the standalone server, tracd. * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: mod_wsgi of course, but the same instructions applies also for mod_python, mod_fcgi or mod_fastcgi. * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: mod_wsgi, mod_python, mod_fcgi or mod_fastcgi. * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx) [trac:TracAuthenticationIntroduction] also contains some useful information for beginners. == Granting admin rights to the admin user Grant admin rights to user admin: {{{ {{{#!sh $trac-admin /path/to/myproject permission add admin TRAC_ADMIN }}} This user will have an "Admin" entry menu that will allow you to admin your trac project. == Finishing the install === Automatic reference to the SVN changesets in Trac tickets === You can configure SVN to automatically add a reference to the changeset into the ticket comments, whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas: * '''Refs #123''' - to reference this changeset in #123 ticket * '''Fixes #123''' - to reference this changeset and close #123 ticket with the default status ''fixed'' This functionality requires a post-commit hook to be installed as described in [wiki:TracRepositoryAdmin#ExplicitSync TracRepositoryAdmin], and enabling the optional commit updater components by adding the following line to the [components] section of your [wiki:TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel. {{{ tracopt.ticket.commit_updater.* = enabled }}} For more information, see the documentation of the CommitTicketUpdater component in the "Plugins" admin panel. === Using Trac === This user will have an //Admin// navigation item that directs to pages for administering your Trac project. == Configuring Trac TracRepositoryAdmin provides information on configuring version control repositories for your project. == Using Trac Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc. Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features. Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [TracPermissions permissions] to authenticated users to see the full set of features. '' Enjoy! '' • ## wiki/pages/TracInterfaceCustomization  r26484 = Customizing the Trac Interface = = Customizing the Trac Interface [[TracGuideToc]] [[PageOutline]] == Introduction == This page is meant to give users suggestions on how they can customize the look of Trac. Topics on this page cover editing the HTML templates and CSS files, but not the program code itself. The topics are intended to show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page. == Introduction This page gives suggestions on how to customize the look of Trac. Topics include editing the HTML templates and CSS files, but not the program code itself. The topics show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page. == Project Logo and Icon == The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [wiki:TracIni trac.ini]. == Project Logo and Icon The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [wiki:TracIni trac.ini]. The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. (''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder'') The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. ''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder''. ''Note: you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.'' '''Note''': you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration. Now configure the appropriate section of your [wiki:TracIni trac.ini]: === Logo === Change the src setting to site/ followed by the name of your image file. The width and height settings should be modified to match your image's dimensions (the Trac chrome handler uses "site/" for files within the project directory htdocs, and "common/" for the common htdocs directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'. === Logo Change the src setting to site/ followed by the name of your image file. The width and height settings should be modified to match your image's dimensions. The Trac chrome handler uses "site/" for files within the project directory htdocs, and "common/" for the common htdocs directory belonging to a Trac installation. Note that 'site/' is not a placeholder for your project name, it is the literal prefix that should be used. For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'. {{{ {{{#!ini [header_logo] src = site/my_logo.gif }}} === Icon === Icons should be a 32x32 image in .gif or .ico format. Change the icon setting to site/ followed by the name of your icon file. Icons will typically be displayed by your web browser next to the site's URL and in the Bookmarks menu. === Icon Icons are small images displayed by your web browser next to the site's URL and in the Bookmarks menu. Icons should be a 32x32 image in .gif or .ico format. Change the icon setting to site/ followed by the name of your icon file: {{{ {{{#!ini [project] icon = site/my_icon.ico }}} Note though that this icon is ignored by Internet Explorer, which only accepts a file named favicon.ico at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from trac.ini as follows: == Custom Navigation Entries The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them, but not for adding new ones. {{{ [project] icon = /favicon.ico }}} Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension. {{{ [project] icon = /favicon.ico? }}} == Custom Navigation Entries == The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones). In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report . {{{ In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report: {{{#!ini [mainnav] wiki.label = Home == Site Appearance == #SiteAppearance Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work. Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as site.html inside your projects templates/ directory (each Trac project can have their own site.html), eg /path/to/env/templates/site.html: Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as site.html inside your projects templates/ directory (each Trac project can have their own site.html), e.g. {{{/path/to/env/templates/site.html}}}: {{{ #!xml {{{#!xml${select('*|comment()|text()')} }}} Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example ${href.chrome('site/style.css')} attribute references a CSS file placed into environment's htdocs/ directory. In a similar fashion ${chrome.htdocs_location} is used to specify the common htdocs/ directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting. Notice that XSLT bears some similarities with Genshi templates. However, there are some Trac specific features, for example the ${href.chrome('site/style.css')} attribute references style.css in the environment's htdocs/ directory. In a similar fashion ${chrome.htdocs_location} is used to specify the common htdocs/ directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-section|[trac] htdocs_location]] configuration setting. site.html is one file to contain all your modifications. It usually works using the py:match directive (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find and modify them. site.html is one file to contain all your modifications. It usually works using the py:match directive (element or attribute), and it allows you to modify the page as it renders. The matches hook onto specific sections depending on what it tries to find and modify them. See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example site.html. A site.html can contain any number of such py:match sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there. Example snippet of adding introduction text to the new ticket form (but not shown during preview): Example snippets for style.css can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss]. If the environment is upgraded from 0.10 and a site_newticket.cs file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a 
block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others: {{{ #!xml
• ## wiki/pages/TracModPython

 r26484 = Trac and mod_python = [[TracGuideToc]] = Trac and mod_python Mod_python is an [https://httpd.apache.org/ Apache] module that embeds the Python interpreter within the server, so that web-based applications in Python will run many times faster than traditional CGI and will have the ability to retain database connections. Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably, especially compared to [TracCgi CGI], and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy. {{{#!div class="important" ** A Word of Warning ** As of 16^th^ June 2010, the mod_python project is officially dead.  If you are considering using mod_python for a new installation, '''please don't'''!  There are known issues which will not be fixed and there are now better alternatives.  Check out the main TracInstall pages for your target version for more information. }}} These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but you'll be totally on your own. These instructions are for Apache 2. If you are using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but that is a deprecated setup. [[PageOutline(2-3,Overview,inline)]] If you just installed mod_python, you may have to add a line to load the module in the Apache configuration: {{{ {{{#!apache LoadModule python_module modules/mod_python.so }}} ''Note: The exact path to the module depends on how the HTTPD installation is laid out.'' On Debian using apt-get {{{ '''Note''': The exact path to the module depends on how the HTTPD installation is laid out. On Debian using apt-get: {{{#!sh apt-get install libapache2-mod-python libapache2-mod-python-doc }}} (Still on Debian) after you have installed mod_python, you must enable the modules in apache2 (equivalent of the above Load Module directive): {{{ Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive: {{{#!sh a2enmod python }}} On Fedora use, using yum: {{{ {{{#!sh yum install mod_python }}} You can test your mod_python installation by adding the following to your httpd.conf.  You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+. {{{ #!xml You can test your mod_python installation by adding the following to your httpd.conf. You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+. {{{#!apache SetHandler mod_python A simple setup of Trac on mod_python looks like this: {{{ #!xml {{{#!apache SetHandler mod_python }}} The option '''TracUriRoot''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''TracUriRoot''' option.  You will notice that the Location and '''TracUriRoot''' have the same path. The options available are {{{ # For a single project PythonOption TracEnv /var/trac/myproject # For multiple projects PythonOption TracEnvParentDir /var/trac/myprojects # For the index of multiple projects PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html # A space delimitted list, with a "," between key and value pairs. PythonOption TracTemplateVars key1,val1 key2,val2 # Useful to get the date in the wanted order PythonOption TracLocale en_GB.UTF8 # See description above PythonOption TracUriRoot /projects/myproject }}} === Python Egg Cache === Compressed python eggs like Genshi are normally extracted into a directory named .python-eggs in the users home directory. Since apache's home usually is not writable an alternate egg cache directory can be specified like this: {{{ The option '''TracUriRoot''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''TracUriRoot''' option. You will notice that the Location and '''TracUriRoot''' have the same path. The options available are: {{{#!apache # For a single project PythonOption TracEnv /var/trac/myproject # For multiple projects PythonOption TracEnvParentDir /var/trac/myprojects # For the index of multiple projects PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html # A space delimitted list, with a "," between key and value pairs. PythonOption TracTemplateVars key1,val1 key2,val2 # Useful to get the date in the wanted order PythonOption TracLocale en_GB.UTF8 # See description above PythonOption TracUriRoot /projects/myproject }}} === Python Egg Cache Compressed Python eggs like Genshi are normally extracted into a directory named .python-eggs in the users home directory. Since Apache's home usually is not writeable, an alternate egg cache directory can be specified like this: {{{#!apache PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache }}} or you can uncompress the Genshi egg to resolve problems extracting from it. === Configuring Authentication === Or you can uncompress the Genshi egg to resolve problems extracting from it. === Configuring Authentication See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page. == Advanced Configuration === Setting the Python Egg Cache === If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a ''500 internal server error'' and/or a complaint in the syslog. {{{ #!xml === Setting the Python Egg Cache If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a 500 internal server error and/or a complaint in the syslog. {{{#!apache ... }}} === Setting the !PythonPath === If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler  using the PythonPath directive: {{{ #!xml === Setting the !PythonPath If the Trac installation isn't installed in your Python path, you will have to tell Apache where to find the Trac mod_python handler  using the PythonPath directive: {{{#!apache ... Be careful about using the !PythonPath directive, and ''not'' SetEnv PYTHONPATH, as the latter won't work. === Setting up multiple projects === === Setting up multiple projects The Trac mod_python handler supports a configuration option similar to Subversion's SvnParentPath, called TracEnvParentDir: {{{ #!xml {{{#!apache SetHandler mod_python If you don't want to have the subdirectory listing as your projects home page you can use a {{{ #!xml {{{#!apache }}} You can also use the same authentication realm for all of the projects using a  directive: {{{ #!xml {{{#!apache AuthType Basic }}} === Virtual Host Configuration === Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like !http://trac.mycompany.com): {{{ #!xml === Virtual Host Configuration Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like http://trac.mycompany.com: {{{#!apache DocumentRoot /var/www/myproject ServerName trac.mycompany.com This does not seem to work in all cases. What you can do if it does not: * Try using  instead of  * may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to python and authentication does not work (i.e. you get the infamous Authentication information missing error). If this applies to you, try using a sub-directory for trac instead of the root (i.e. /web/ and /web/login instead of / and /login). * Try using  instead of . *  may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to Python and authentication does not work, ie you get the infamous Authentication information missing error. If this is the case, try using a sub-directory for Trac instead of the root, ie /web/ and /web/login instead of / and /login. * Depending on apache's NameVirtualHost configuration, you may need to use  instead of . For a virtual host that supports multiple projects replace "TracEnv" /var/trac/myproject with "TracEnvParentDir" /var/trac/ Note: !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment". == Troubleshooting == In general, if you get server error pages, you can either check the Apache error log, or enable the PythonDebug option: {{{ #!xml For a virtual host that supports multiple projects replace TracEnv /var/trac/myproject with TracEnvParentDir /var/trac. '''Note''': !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment". == Troubleshooting If you get server error pages, you can either check the Apache error log, or enable the PythonDebug option: {{{#!apache ... For multiple projects, try restarting the server as well. === Login Not Working === === Login Not Working If you've used  directive, it will override any other directives, as well as . The workaround is to use negation expression as follows (for multi project setups): {{{ #!xml {{{#!apache #this one for other pages PythonOption TracEnvParentDir /projects PythonOption TracUriRoot / #this one for login page This problem will most certainly hit you on Unix when using Python 2.4. In Python 2.4, some version of Expat (an XML parser library written in C) is used, and if Apache is using another version, this results in segmentation faults. As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. See Graham Dumpleton's detailed [http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash explanation and workarounds] for the issue. === Form submission problems === In Python 2.4, some version of [http://expat.sourceforge.net/ Expat] (an XML parser library written in C) is used and if Apache is using another version, this results in segmentation faults. As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. This problem has not been reported for Python 2.5+, so best to upgrade. === Form submission problems If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource. === Problem with virtual host configuration === If the directive is used, setting the DocumentRoot may result in a ''403 (Forbidden)'' error. Either remove the DocumentRoot directive, or make sure that accessing the directory it points is allowed (in a corresponding  block). Using together with SetHandler resulted in having everything handled by mod_python, which leads to not being able download any CSS or images/icons. I used SetHandler None to circumvent the problem, though I do not know if this is the most elegant solution. === Problem with zipped egg === It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an ImportError: No module named trac in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify, try installing Trac using the --always-unzip option, like this: {{{ === Problem with virtual host configuration If the directive is used, setting the DocumentRoot may result in a ''403 (Forbidden)'' error. Either remove the DocumentRoot directive, or make sure that accessing the directory it points is allowed, in a corresponding  block. Using together with SetHandler resulted in having everything handled by mod_python, which leads to not being able to download any CSS or images/icons. Use SetHandler None to circumvent the problem, though this may not be the most elegant solution. === Problem with zipped egg It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an ImportError: No module named trac in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify this, try installing Trac using the --always-unzip option: {{{#!sh easy_install --always-unzip Trac-0.12b1.zip }}} === Using .htaccess === === Using .htaccess Although it may seem trivial to rewrite the above configuration as a directory in your document root with a .htaccess file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation. It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :) A success story: For me it worked out-of-box, with following trivial config: {{{#!xml It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. This also works out-of-box, with following trivial config: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter }}} The TracUriRoot is obviously the path you need to enter to the browser to get to the trac (e.g. domain.tld/projects/trac) === Additional .htaccess help === If you are using the .htaccess method you may have additional problems if your trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file: {{{ The TracUriRoot is obviously the path you need to enter to the browser to get to Trac, eg domain.tld/projects/trac. === Additional .htaccess help If you are using the .htaccess method you may have additional problems if your Trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file: {{{#!apache RewriteEngine Off === Platform specific issues ==== Win32 Issues ==== If you run trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this. ==== OS X issues ==== When using mod_python on OS X you will not be able to restart Apache using apachectl restart. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here]. ==== SELinux issues ==== If Trac reports something like: ''Cannot get shared lock on db.lock'' The security context on the repository may need to be set: {{{ ==== Win32 Issues If you run Trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this. ==== OS X issues When using mod_python on OS X you will not be able to restart Apache using apachectl restart. This is apparently fixed in mod_python 3.2, so please upgrade mod_python to fix this. ==== SELinux issues If Trac reports something like: Cannot get shared lock on db.lock, then the security context on the repository may need to be set: {{{#!sh chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY }}} See also [http://subversion.tigris.org/faq.html#reposperms] ==== FreeBSD issues ==== Pay attention to the version of the installed mod_python and sqlite packages. Ports have both the new and old ones, but earlier versions of pysqlite and mod_python won't integrate as the former requires threaded support in python, and the latter requires a threadless install. If you compiled and installed apache2, apache wouldn´t support threads (cause it doesn´t work very well on FreeBSD). You could force thread support when running ./configure for apache, using --enable-threads, but this isn´t recommendable. The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line {{{ See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?] ==== FreeBSD issues The FreeBSD ports have both the new and old versions of mod_python and SQLite, but earlier versions of pysqlite and mod_python won't integrate: * pysqlite requires threaded support in Python * mod_python requires a threadless install. Apache2 does not automatically support threads on FreeBSD. You could force thread support when running ./configure for Apache, using --enable-threads, but this isn´t recommended. The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line: {{{#!sh export LD_PRELOAD=/usr/lib/libc_r.so }}} ==== Fedora 7 Issues ==== Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd === Subversion issues === If you get the following Trac Error Unsupported version control system "svn" only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. (The better way is to add a link to the bindings in the Python site-packages directory, or create a .pth file in that directory.) If this is not the case, it's possible that you're using Subversion libraries that are binary incompatible with the apache ones (an incompatibility of the apr libraries is usually the cause). In that case, you also won't be able to use the svn modules for Apache (mod_dav_svn). You also need a recent version of mod_python in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter: {{{ ==== Fedora 7 Issues Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd. === Subversion issues If you get the following Trac error Unsupported version control system "svn" only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. A better way is to add a link to the bindings in the Python site-packages directory, or create a .pth file in that directory. If this is not the case, it's possible that you are using Subversion libraries that are binary incompatible with the Apache ones and an incompatibility of the apr libraries is usually the cause. In that case, you also won't be able to use the svn modules for Apache (mod_dav_svn). You also need a recent version of mod_python in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. Version 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter: {{{#!apache PythonInterpreter main_interpreter }}} This is anyway the recommended workaround for other well-known issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue. === Page layout issues === If the formatting of the Trac pages look weird chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your apache configuration: {{{ #!xml This is also the recommended workaround for other issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue. === Page layout issues If the formatting of the Trac pages look weird, chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your Apache configuration: {{{#!apache Alias /myproject/css "/usr/share/trac/htdocs/css" }}} Note: For the above configuration to have any effect it must be put after the configuration of your project root location, i.e. {{{}}}. Also, setting PythonOptimize On seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, it is probably a good idea to leave it Off. === HTTPS issues === If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your apache configuration: {{{ #!xml '''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{}}}. Also, setting PythonOptimize On seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, leave it Off. === HTTPS issues If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your Apache configuration: {{{#!apache DocumentRoot /var/www/myproject ServerName trac.mycompany.com }}} === Segmentation fault with php5-mhash or other php5 modules === You may encounter segfaults (reported on debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See debian bug report [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487] Some people also have troubles when using php5 compiled with its own 3rd party libraries instead of system libraries. Check here [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault] === Segmentation fault with php5-mhash or other php5 modules You may encounter segfaults (reported on Debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report]. Some people also have troubles when using PHP5 compiled with its own third party libraries instead of system libraries. Check [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault Django segmentation fault]. ---- See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI],  [trac:TracNginxRecipe TracNginxRecipe] See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]