# Changeset 40551

Ignore:
Timestamp:
06/25/17 06:07:12 (5 years ago)
Message:

[titan] autoupdate wiki files

Location:
wiki/pages
Files:
273 edited

Unmodified
Removed
• ## wiki/pages/CamelCase

 r38413 = !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. == Customizing the Wiki behavior 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. * 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 * http://c2.com/cgi/wiki?WikiCase * http://en.wikipedia.org/wiki/CamelCase ---- See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki
• ## wiki/pages/SandBox

 r40226 = The Sandbox = This is just a page to practice and learn WikiFormatting. Go ahead, edit it freely.
• ## wiki/pages/TicketQuery

 r40226 = !TicketQuery Wiki Macro The !TicketQuery macro lets you display information on tickets within wiki pages. The query language used by the [[TicketQuery]] macro is described in [TracQuery#UsingtheTicketQueryMacro TracQuery] page. == Usage [[MacroList(TicketQuery)]] == Example ||= **Example** =||= **Result** =||= **Macro** =|| |----------------------------------------------------------- ||=Number of [query:status=new&milestone= Triage tickets]: =||\ || **[[TicketQuery(status=new&milestone=,count)]]**||\ || [[TicketQuery(status=new&milestone=,count)]] || |----------------------------------------------------------- ||=Number of new tickets: =||\ || **[[TicketQuery(status=new,count)]]**||\ || [[TicketQuery(status=new,count)]] || |----------------------------------------------------------- ||=Number of reopened tickets: =||\ || **[[TicketQuery(status=reopened,count)]]**||\ || [[TicketQuery(status=reopened,count)]] || |----------------------------------------------------------- ||=Number of assigned tickets: =||\ || **[[TicketQuery(status=assigned,count)]]**||\ || [[TicketQuery(status=assigned,count)]] || |----------------------------------------------------------- ||=Number of invalid tickets: =||\ || **[[TicketQuery(status=closed,resolution=invalid,count)]]**||\ || [[TicketQuery(status=closed,resolution=invalid,count)]] || |----------------------------------------------------------- ||=Number of worksforme tickets: =||\ || **[[TicketQuery(status=closed,resolution=worksforme,count)]]**||\ || [[TicketQuery(status=closed,resolution=worksforme,count)]] || |----------------------------------------------------------- ||=Number of duplicate tickets: =||\ || **[[TicketQuery(status=closed,resolution=duplicate,count)]]**||\ || [[TicketQuery(status=closed,resolution=duplicate,count)]] || |----------------------------------------------------------- ||=Number of wontfix tickets: =||\ || **[[TicketQuery(status=closed,resolution=wontfix,count)]]**||\ || [[TicketQuery(status=closed,resolution=wontfix,count)]] || |----------------------------------------------------------- ||=Number of fixed tickets: =||\ || **[[TicketQuery(status=closed,resolution=fixed,count)]]**||\ || [[TicketQuery(status=closed,resolution=fixed,count)]] || |----------------------------------------------------------- ||=Total number of tickets: =||\ || **[[TicketQuery(count)]]**||\ || [[TicketQuery(count)]] || |----------------------------------------------------------- ||=Number of tickets reported **or** owned by current user: =||\ || **[[TicketQuery(reporter=$USER,or,owner=$USER,count)]]**||\ || [[TicketQuery(reporter=$USER,or,owner=$USER,count)]] || |----------------------------------------------------------- ||=Number of tickets created this month: =||\ || **[[TicketQuery(created=thismonth..,count)]]**||\ || [[TicketQuery(created=thismonth..,count)]] || |----------------------------------------------------------- ||=Last 3 modified tickets: =||\ ||**[[TicketQuery(max=3,order=modified,desc=1,compact)]]**||\ || [[TicketQuery(max=3,order=modified,desc=1,compact)]] || |----------------------------------------------------------- {{{#!th rowspan=2, style="text-align: left;" Details of ticket #1: }}} {{{#!td style="border-bottom: 0;" }}} {{{#!td [[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]] }}} |- {{{#!td colspan=2, style="border-top: 0;" [[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]] }}} |----------------------------------------------------------- == Using the [[TicketQuery]] Macro The [trac:TicketQuery TicketQuery] macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting. Example: {{{ [[TicketQuery(version=0.6|0.7&resolution=duplicate)]] }}} This is displayed as: [[TicketQuery(version=0.6|0.7&resolution=duplicate)]] Just like the [wiki:TracQuery#UsingTracLinks query: wiki links], the parameter of this macro expects a query string formatted according to the rules of the simple [wiki:TracQuery#QueryLanguage ticket query language]. This also displays the link and description of a single ticket: {{{ [[TicketQuery(id=123)]] }}} This is displayed as: [[TicketQuery(id=123)]] A more compact representation without the ticket summaries is: {{{ [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]] }}} This is displayed as: [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]] Finally, if you wish to receive only the number of defects that match the query, use the count parameter: {{{ [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]] }}} This is displayed as: [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]] ---- See also: TracQuery, TracTickets, TracReports, TracGuide
• ## wiki/pages/TitleIndex

 r40226 ''' Index by Title ''' | ''' [RecentChanges Index by Date] ''' [[TitleIndex(format=group,min=4)]]
• ## wiki/pages/TracAccessibility

 r40226 = Accessibility Support in Trac = Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In a Trac session, users can use devices other than a pointing device by enabling keyboard shortcuts through the [/prefs/keybindings Keyboard Shortcuts] preferences panel. Trac supports accessibility keys for the most common operations. The access keys differ by browser and the following work for several browsers, but see [http://en.wikipedia.org/wiki/Access_key#Access_in_different_browsers access in different browsers] for more details. - on Linux platforms, press any of the keys listed below in combination with the  key - on a Mac, use the  +  key instead - on Windows, you need to hit  + + . This works for the most common browsers, such as Firefox, Chrome, Safari and Internet Explorer == Global Access Keys == * 1 - WikiStart * 2 - [TracTimeline Timeline] * 3 - [TracRoadmap Roadmap] * 4 - [TracSearch Search] * 6 - [TracGuide Trac Guide / Documentation] * 7 - [TracTickets New Ticket] * 9 - [/about About Trac] * e - Edit (wiki or report) * r - Preview (wiki or ticket) * f - Search ---- See also: TracGuide

 r40226 = TracAdmin [[PageOutline(2-5, Contents, floated)]] [[TracGuideToc]] Trac is distributed with a powerful command-line configuration tool. This tool can be used  to configure and customize your Trac-installation to better fit your needs. Some of those operations can also be performed via the web administration module. == Usage For nearly every trac-admin command, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example: {{{ trac-admin /path/to/projenv wiki list }}} The only exception is for the help command, but even in this case if you omit the environment, you'll only get a very succinct list of commands (help and initenv), the same list you'd get when invoking trac-admin alone. Also, trac-admin --version will tell you about the Trac version (e.g. 0.12) corresponding to the program. If you want to get a comprehensive list of the available commands and sub-commands, you need to specify an existing environment: {{{ trac-admin /path/to/projenv help }}} Some commands have a more detailed help, which you can access by specifying the command's name as a subcommand for help: {{{ trac-admin /path/to/projenv help }}} === trac-admin initenv === #initenv This subcommand is very important as it's the one used to create a TracEnvironment in the specified . That directory must not exist prior to the call. [[TracAdminHelp(initenv)]] It supports an extra --inherit option, which can be used to specify a global configuration file which can be used to share settings between several environments. You can also inherit from a shared configuration afterwards, by setting the [inherit] file option in the conf/trac.ini file in your newly created environment, but the advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' already specified in the global configuration file will be written in the created environment's conf/trac.ini file. See TracIni#GlobalConfiguration. Note that in version 0.11 of Trac, initenv lost an extra last argument , which was used in previous versions to point to the templates folder. If you are using the one-liner 'trac-admin /path/to/trac/ initenv ' in the above and getting an error that reads ''''Wrong number of arguments to initenv: 4'''', then this is because you're using a trac-admin script from an '''older''' version of Trac. == Interactive Mode When passing the environment path as the only argument, trac-admin starts in interactive mode. Commands can then be executed on the selected environment using the prompt, which offers tab-completion (on non-Windows environments, and when the Python readline module is available) and automatic repetition of the last command issued. Once you're in interactive mode, you can also get help on specific commands or subsets of commands: For example, to get an explanation of the resync command, run: {{{ > help resync }}} To get help on all the Wiki-related commands, run: {{{ > help wiki }}} == Full Command Reference You'll find below the detailed help for all the commands available by default in trac-admin. Note that this may not match the list given by trac-admin help, as the commands  pertaining to components disabled in that environment won't be available and conversely some plugins activated in the environment can add their own commands. [[TracAdminHelp()]] ---- See also: TracGuide, TracBackup, TracPermissions, TracEnvironment, TracIni, [trac:TracMigrate TracMigrate]

• ## wiki/pages/TracFastCgi

 r40226 = 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], 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]. == Simple Apache configuration There are two FastCGI modules commonly available for Apache: mod_fastcgi and mod_fcgid (preferred). The latter is more up-to-date. 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 mod_fastcgi uses FastCgiIpcDir and FastCgiConfig directives that should be added to an appropriate Apache configuration file: {{{ # Enable fastcgi for .fcgi files # (If you're using a distro package for mod_fcgi, something like # this is probably already present) AddHandler fastcgi-script .fcgi FastCgiIpcDir /var/lib/apache2/fastcgi LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so }}} Setting FastCgiIpcDir is optional if the default is suitable. Note that the LoadModule line must be after the IfModule group. Configure ScriptAlias or similar options as described in TracCgi, but calling trac.fcgi instead of trac.cgi. Add the following to the Apache configuration file (below the FastCgiIpcDir line) if you intend to set up the TRAC_ENV as an overall default: {{{ FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac }}} Alternatively, you can serve multiple Trac projects in a directory by adding this: {{{ FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects }}} === 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/ }}} 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. {{{ DefaultInitEnv TRAC_ENV /path/to/env/trac/ }}} === 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: {{{ import os os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir" }}} 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: {{{ ScriptAlias / /srv/tracsite/cgi-bin/trac.fcgi/ }}} == 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: {{{ Host: localhost:4433 Interpreter: /usr/bin/tracd —single-env —daemonize —protocol=scgi —hostname=localhost —port=4433 /path/to/project/ }}} If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''. After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source. The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where$TRAC_LOCAL is a directory defined by the user or the system administrator to place local trac resources). Note:\\ If the tracd process fails to start up, and cherokee displays a 503 error page, you might be missing the [http://trac.saddi.com/flup python-flup] package.\\ Python-flup is a dependency which provides trac with SCGI capability. You can install it on debian based systems with: {{{ sudo apt-get install python-flup }}} == 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 var.fcgi_binary="/path/to/cgi-bin/trac.fcgi" # 0.10 name of prior fcgi executable fastcgi.server = ("/trac" => ("trac" => ("socket" => "/tmp/trac-fastcgi.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV" => "/path/to/projenv") ) ) ) }}} 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: {{{ fastcgi.server = ("/first" => ("first" => ("socket" => "/tmp/trac-fastcgi-first.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV" => "/path/to/projenv-first") ) ), "/second" => ("second" => ("socket" => "/tmp/trac-fastcgi-second.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV" => "/path/to/projenv-second") ) ) ) }}} 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. {{{ #!div class=important '''Note''' It's very important the order on which server.modules are loaded, if mod_auth is not loaded '''BEFORE''' mod_fastcgi, then the server will fail to authenticate the user. }}} For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules: {{{ server.modules              = ( ... "mod_auth", ... ) auth.backend               = "htpasswd" # Separated password files for each project # See "Conditional Configuration" in # http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/configuration.txt $HTTP["url"] =~ "^/first/" { auth.backend.htpasswd.userfile = "/path/to/projenv-first/htpasswd.htaccess" }$HTTP["url"] =~ "^/second/" { auth.backend.htpasswd.userfile = "/path/to/projenv-second/htpasswd.htaccess" } # Enable auth on trac URLs, see # http://trac.lighttpd.net/trac/file/branches/lighttpd-merge-1.4.x/doc/authentication.txt auth.require = ("/first/login" => ("method"  => "basic", "realm"   => "First project", "require" => "valid-user" ), "/second/login" => ("method"  => "basic", "realm"   => "Second project", "require" => "valid-user" ) ) }}} 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 server.modules += ("mod_alias") # Set up an alias for the static resources alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs") # Use negative lookahead, matching all requests that ask for any resource under /trac, EXCEPT in # /trac/chrome/common, and use FastCGI for those $HTTP["url"] =~ "^/trac(?!/chrome/common)" { # Even if you have other fastcgi.server declarations for applications other than Trac, do NOT use += here fastcgi.server = ("/trac" => ("trac" => ("socket" => "/tmp/trac-fastcgi.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV" => "/path/to/projenv") ) ) ) } }}} 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: {{{ # This is for handling multiple projects alias.url = ( "/trac/" => "/path/to/trac/htdocs/" ) fastcgi.server += ("/projects" => ("trac" => ( "socket" => "/tmp/trac.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV_PARENT_DIR" => "/path/to/parent/dir/of/projects/" ) ) ) ) #And here starts the global auth configuration auth.backend = "htpasswd" auth.backend.htpasswd.userfile = "/path/to/unique/htpassword/file/trac.htpasswd"$HTTP["url"] =~ "^/projects/.*/login$" { auth.require = ("/" => ( "method" => "basic", "realm" => "trac", "require" => "valid-user" ) ) } }}} Changing date/time format also supported by lighttpd over environment variable LC_TIME: {{{ fastcgi.server = ("/trac" => ("trac" => ("socket" => "/tmp/trac-fastcgi.sock", "bin-path" => fcgi_binary, "check-local" => "disable", "bin-environment" => ("TRAC_ENV" => "/path/to/projenv", "LC_TIME" => "ru_RU") ) ) ) }}} For details about languages specification see [trac:TracFaq TracFaq] question 2.13. Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects. ] 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 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". {{{ Name: MyTracFCGI Address: uds://tmp/lshttpd/mytracfcgi.sock Max Connections: 10 Environment: TRAC_ENV=/fullpathto/mytracproject/ <--- path to root folder of trac project Initial Request Timeout (secs): 30 Retry Timeout (secs): 0 Persistent Connection Yes Connection Keepalive Timeout: 30 Response Bufferring: No Auto Start: Yes Command: /usr/share/trac/cgi-bin/trac.fcgi <--- path to trac.fcgi Back Log: 50 Instances: 10 }}} 4. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm. {{{ DB Type: Password File Realm Name: MyTracUserDB <--- any name you wish and referenced later User DB Location: /fullpathto/htpasswd <--- path to your htpasswd file }}} 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. {{{ URI: /trac/ <--- URI path to bind to python fcgi app we created Fast CGI App: [VHost Level] MyTractFCGI <--- select the trac fcgi extapp we just created Realm: TracUserDB <--- only if (4) is set. select realm created in (4) }}} 6. Modify /fullpathto/mytracproject/conf/trac.ini {{{ #find/set base_rul, url, and link variables base_url = http://yourdomain.com/trac/ <--- base url to generate correct links to url = http://yourdomain.com/trac/ <--- link of project link = http://yourdomain.com/trac/ <--- link of graphic logo }}} 7. Restart !LiteSpeed, “lswsctrl restart”, and access your new Trac project at: {{{ http://yourdomain.com/trac/ }}} == 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; server_name trac.example; ssl on; ssl_certificate /etc/ssl/trac.example.crt; ssl_certificate_key /etc/ssl/trac.example.key; ssl_session_timeout 5m; ssl_protocols SSLv2 SSLv3 TLSv1; ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; ssl_prefer_server_ciphers on; # it makes sense to serve static resources through Nginx (or ~ [/some/prefix]/chrome/(.*)) location ~ /chrome/(.*) { alias /home/trac/instance/static/htdocs/$1; } # 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 ~ (/.*) { auth_basic            "trac realm"; auth_basic_user_file /home/trac/htpasswd; # socket address fastcgi_pass   unix:/home/trac/run/instance.sock; # python - wsgi specific fastcgi_param HTTPS on; ## WSGI REQUIRED VARIABLES # WSGI application name - trac instance prefix. # (Or fastcgi_param  SCRIPT_NAME  /some/prefix.) fastcgi_param  SCRIPT_NAME        ""; fastcgi_param  PATH_INFO          $1; ## WSGI NEEDED VARIABLES - trac warns about them fastcgi_param REQUEST_METHOD$request_method; fastcgi_param  SERVER_NAME        $server_name; fastcgi_param SERVER_PORT$server_port; fastcgi_param  SERVER_PROTOCOL    $server_protocol; fastcgi_param QUERY_STRING$query_string; # For Nginx authentication to work - do not forget to comment these # lines if not using Nginx for authentication fastcgi_param  AUTH_USER          $remote_user; fastcgi_param REMOTE_USER$remote_user; # for ip to work fastcgi_param REMOTE_ADDR         $remote_addr; # For attchments to work fastcgi_param CONTENT_TYPE$content_type; fastcgi_param    CONTENT_LENGTH   $content_length; } } }}} 1. Modified trac.fcgi: {{{ #!/usr/bin/env python import os sockaddr = '/home/trac/run/instance.sock' os.environ['TRAC_ENV'] = '/home/trac/instance' try: from trac.web.main import dispatch_request import trac.web._fcgi fcgiserv = trac.web._fcgi.WSGIServer(dispatch_request, bindAddress = sockaddr, umask = 7) fcgiserv.run() except SystemExit: raise except Exception, e: print 'Content-Type: text/plain\r\n\r\n', print 'Oops...' print print 'Trac detected an internal error:' print print e print import traceback import StringIO tb = StringIO.StringIO() traceback.print_exc(file=tb) print tb.getvalue() }}} 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 * /home/trac/instance contains a trac environment * /home/trac/htpasswd contains authentication information * /home/trac/run is owned by the same group the nginx runs under * and if your system is Linux the /home/trac/run has setgid bit set (chmod g+s run) * and patch from ticket #T7239 is applied, or you'll have to fix the socket file permissions every time 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 ---- See also:  TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracCgi CGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]
• ## wiki/pages/TracFineGrainedPermissions

 r40226 = Fine grained permissions = [[PageOutline(2-5, Contents, floated)]] [[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. Which policies are currently active is determined by a configuration setting in TracIni: {{{#!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/1.0-stable/sample-plugins/permissions sample-plugins/permissions] for more examples. === !AuthzPolicy === ==== Configuration ==== * 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: {{{#!ini [trac] ... 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: {{{#!ini [components] tracopt.perm.authz_policy.* = enabled }}} ==== Usage Notes ==== 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. The authzpolicy.conf file is a .ini style configuration file: {{{#!ini [wiki:PrivatePage@*] john = WIKI_VIEW, !WIKI_MODIFY jack = WIKI_VIEW * = }}} * 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 explicitly, all versions (@*) is added implicitly. Example: Match the WikiStart page: {{{#!ini [wiki:*] [wiki:WikiStart*] [wiki:WikiStart@*] [wiki: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'''. * 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. || For example, if the authz_file contains: {{{#!ini [wiki:WikiStart@*] * = WIKI_VIEW [wiki:PrivatePage@*] john = WIKI_VIEW * = !WIKI_VIEW }}} and the default permissions are set like this: {{{ john           WIKI_VIEW jack           WIKI_VIEW # anonymous has no WIKI_VIEW }}} Then: * 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 devs = alice, bob [wiki:Dev@*] @admins = TRAC_ADMIN @devs = WIKI_VIEW * = [*] @admins = TRAC_ADMIN * = }}} Then: - everything is blocked (whitelist approach), but - admins get all TRAC_ADMIN everywhere and - devs can view wiki pages. 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 # 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] john = BROWSER_VIEW, FILE_VIEW }}} 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 authz_policy.2.patch, part of [trac:ticket:6680 #6680]. You cannot do the following: {{{#!ini [groups] team1 = a, b, c team2 = d, e, f team3 = g, h, i departmentA = team1, team2 }}} Permission groups are not supported either, so you cannot do the following: {{{#!ini [groups] permission_level_1 = WIKI_VIEW, TICKET_VIEW permission_level_2  = permission_level_1, WIKI_MODIFY, TICKET_MODIFY [*] @team1 = permission_level_1 @team2 = permission_level_2 @team3 = permission_level_2, TICKET_CREATE }}} === !AuthzSourcePolicy  (mod_authz_svn-like permission policy) === #AuthzSourcePolicy 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 [/branches/calc/bug-142] harry = rw sally = r [/branches/calc/bug-142/secret] harry = }}} * '''/''' = ''Everyone has read access by default'' * '''/branches/calc/bug-142''' = ''harry has read/write access, sally read only'' * '''/branches/calc/bug-142/secret''' = ''harry has no access, sally has read access (inherited as a sub folder permission)'' ==== Trac Configuration ==== 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: {{{#!ini authz_module_name = modulename }}} 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 = somemodule ... [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. {{{#!ini [trac] permission_policies = AuthzSourcePolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} ==== Subversion Configuration ==== The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this: {{{#!apache DAV svn SVNParentPath /usr/local/svn # our access control policy AuthzSVNAccessFile /path/to/svnaccessfile }}} 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 log_level = DEBUG log_type = file }}} Display the trac.log to understand what checks are being performed: {{{#!sh tail -n 0 -f log/trac.log | egrep '$perm$|$authz_policy$' }}} See the sourced documentation of the plugin for more info. ---- See also: TracPermissions, [http://trac-hacks.org/wiki/FineGrainedPageAuthzEditorPlugin TracHacks:FineGrainedPageAuthzEditorPlugin] for a simple editor plugin.

 r40226 = Importing ticket data = [[PageOutline]] 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]: 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 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 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. {{{ $bugzilla2trac.py bugzilla2trac - Imports a bug database from Bugzilla into Trac. Usage: bugzilla2trac.py [options] Available Options: --db - Bugzilla's database --tracenv /path/to/trac/env - full path to Trac db environment -h | --host - Bugzilla's DNS host name -u | --user - effective Bugzilla's database user -p | --passwd - Bugzilla's user password -c | --clean - remove current Trac tickets before importing --help | help - this help info Additional configuration options can be defined directly in the script. }}} Currently, the following data is imported from Bugzilla: * bugs * bug activity (field changes) * bug attachments * user names and passwords (put into a htpasswd file) The script provides a number of features to ease the conversion, such as: * 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. == Mantis == [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: script to import the following data from Mantis into Trac: * bugs * bug comments * bug activity (field changes) * attachments (as long as the files live in the mantis db, not on the filesystem) . == !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. 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] == 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 [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 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 [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. ---- See also: * to import/export wiki pages: TracAdmin, * to export tickets: TracTickets, TracQuery • ## wiki/pages/TracIni  r40226 = The Trac Configuration File [[TracGuideToc]] [[PageOutline]] 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. 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 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 }}} Multiple files can be specified using a comma-separated list. Note that you can also specify a global option file when creating a new project, by adding the option --inherit=/path/to/global/trac.ini to [TracAdmin#initenv trac-admin]'s initenv command. If you do not do this but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated conf/trac.ini file and delete the entries that will otherwise override those set in the global file. 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, 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]] ---- See also: TracGuide, TracAdmin, TracEnvironment • ## wiki/pages/TracInstall  r40226 = 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. 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 === Mandatory Dependencies To install Trac, the following software packages must be installed: * [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.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], version 2.0 or later See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details. ==== For the MySQL database #ForMySQL 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 Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database. === Optional Dependencies ==== 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 - [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.6 or >= 1.3, needed for localization support * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9 for WikiRestructuredText. * [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. {{{#!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 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: {{{#!sh easy_install Trac==1.0 }}} - Install latest development version: {{{#!sh easy_install Trac==dev }}} Note that in this case you won't have the possibility to run a localized version of Trac; 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: Assuming you want to have your entire pip installation in /opt/user/trac - {{{#!sh pip install trac psycopg2 }}} or - {{{#!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 [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip. === From source 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 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 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/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 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: 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: {{{#!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 '''Warning:''' Please only use ASCII-characters for account name and project path, unicode characters are not supported there. }}} == Deploying Trac === 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 }}} {{{#!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: - [TracFastCgi FastCGI] - [wiki:TracModWSGI mod_wsgi] - [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 [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 trac-admin /usr/share/trac/projects/my-project deploy /tmp/deploy mv /tmp/deploy/* /usr/share/trac }}} 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). Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself. There are two primary URL paths for static resources - /chrome/common and /chrome/site. Plugins can add their own resources, usually accessible by /chrome/ 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 deploy command: [[TracAdminHelp(deploy)]] The target  will then contain an htdocs directory with: - site/ - a copy of the environment's directory htdocs/ - common/ - the static resources of Trac itself - / - one directory for each resource directory managed by the plugins enabled for this environment ===== Example: Apache and ScriptAlias #ScriptAlias-example Assuming the deployment has been done this way: {{{#!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 Order allow,deny Allow from all }}} If using mod_python, you might want to add this too (otherwise, the alias will be ignored): {{{#!apache SetHandler None }}} 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 Order allow,deny Allow from all }}} 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/ }}} Note that this makes it easy to have a dedicated domain serve those static resources (preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less]). 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. 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, 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// 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 [TracPermissions permissions] to authenticated users to see the full set of features. '' Enjoy! '' [trac:TracTeam The Trac Team] ---- See also: [trac:TracInstallPlatforms TracInstallPlatforms], TracGuide, TracUpgrade, TracPermissions • ## wiki/pages/TracInterfaceCustomization  r40542 = Customizing the Trac Interface [[TracGuideToc]] [[PageOutline]] == 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]. 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. 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 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 alt = My Project width = 300 height = 100 }}} === 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 }}} == 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: {{{#!ini [mainnav] wiki.label = Home tickets.href = /report/24 [metanav] help = disabled }}} See also TracNavigation for a more detailed explanation of the mainnav and metanav terms. == Site Appearance == #SiteAppearance 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: {{{#!xml${select('*|comment()|text()')} ${select('*|text()')} }}} 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. 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): {{{#!xml Please make sure to search for existing tickets before reporting a new one!${select('*')} }}} This example illustrates a technique of using req.environ['PATH_INFO'] to limit scope of changes to one view only. For instance, to make changes in site.html only for timeline and avoid modifying other sections - use  req.environ['PATH_INFO'] == '/timeline' condition in  test. More examples snippets for site.html can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml]. Example snippets for style.css can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss]. Note that the site.html, despite its name, can be put in a shared templates directory, see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global site.html file can be made to include any existing header, footer and newticket snippets. == Project List == #ProjectList You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded, it displays an error message. You can use this as a starting point for your own index template: {{{#!text/html Available Projects

Available Projects

}}} Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11): For [wiki:TracModWSGI mod_wsgi]: {{{#!python os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html' }}} For [wiki:TracFastCgi FastCGI]: {{{#!apache FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template }}} For [wiki:TracModPython mod_python]: {{{#!apache PythonOption TracEnvParentDir /parent/dir/of/projects PythonOption TracEnvIndexTemplate /path/to/template }}} For [wiki:TracCgi CGI]: {{{#!apache SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template }}} For [wiki:TracStandalone], you'll need to set up the TRAC_ENV_INDEX_TEMPLATE environment variable in the shell used to launch tracd: - Unix {{{#!sh $export TRAC_ENV_INDEX_TEMPLATE=/path/to/template }}} - Windows {{{#!sh$ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template }}} == Project Templates The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use a site.html template (see [#SiteAppearance]) whenever possible. Using site.html means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of theme.html or any other Trac template, you need to migrate your modifiations to the newer version. If not, new Trac features or bug fixes may not work as expected. With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ...). The [#ProjectList] template file is called index.html, while the template responsible for main layout is called theme.html. Page assets such as images and CSS style sheets are located in the egg's trac/htdocs directory. However, do not edit templates or site resources inside the Trac egg. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives: * For a modification to one project only, copy the template to project templates directory. * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the [inherit] templates_dir trac.ini option. Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg. Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server. ---- See also TracGuide, TracIni
• ## wiki/pages/TracLanguages

 r40542 ||=Code=||=Name=||=English name=||=Language title=|| ||Ar||العربية||Arabic||لغات أخرى|| ||Ast||asturianu||Asturian||Otres llingües|| ||Az||azərbaycanca||Azeri||Başqa dillərdə|| ||Be||беларуская||Belarusian||Іншыя мовы|| ||Bg||български||Bulgarian||Други езици|| ||Bn||বাংলা||Bengali||অন্যান্য ভাষাসমূহ|| ||Bs||bosanski||Bosnian||Drugim jezicima|| ||Ca||català||Catalan||Altres llengües|| ||Ca-Valencia||valencià||Valencian||Altres llengües|| ||Cs||čeština||Czech||Další jazyky|| ||Da||dansk||Danish||Andre sprog|| ||de||Deutsch||German||Andere Sprachen|| ||gr||Ελληνικά||Greek||Άλλες γλώσσες|| ||en||English||(American) English||Languages|| ||En_AU||Australian||Australian English||Languages|| ||En_GB||British||British||Languages|| ||Es||español||Spanish||Altres idiomas|| ||Et||eesti||Estonian||Teistes keeltes|| ||Eu||euskara||Basque||Beste hizkuntzak|| ||Fa||فارسی||Persian||زبانهای دیگر|| ||Fi||suomi||Finnish||Muilla kielillä|| ||fr||français||French||Autres langues|| ||Gl||galego||Galician||Outras linguas|| ||He||עברית||Hebrew||שפות אחרות|| ||Hi||हिन्दी||Hindi||अन्य भाषाओं|| ||Hr||hrvatski||Croatian||Drugi jezici|| ||Hu||magyar||Hungarian||Más nyelveken|| ||Hy||Հայերեն||Armenian||այլ լեզուներ|| ||Id||Bahasa Indonesia||Indonesian||Bahasa lain|| ||Is||Íslenska||Icelandic||Á öðrum tungumálum|| ||it||italiano||Italian||Altre lingue|| ||Ja||日本語||Japanese||他の言語|| ||Ka||ქართული||Georgian||სხვა ენებზე|| ||Ko||한국어||Korean||다른 언어|| ||Km||ភាសាខ្មែរ||Khmer||ភាសាផ្សេងទៀត|| ||Lt||lietuvių||Lithuanian||Kitomis kalbomis|| ||Lv||latviešu||Latvian||Pārējās valodas|| ||Mk||македонски||Macedonian||Други јазици|| ||Nb||norsk bokmål||Norwegian (Bokmal)||Andre språk|| ||nl||Nederlands||Dutch||Andere talen|| ||pl||polski||Polish||Inne języki|| ||Pt||português||Portuguese||Outras línguas|| ||Pt_BR||português brasileiro||Brazilian Portuguese||Outras línguas|| ||Ro||Română||Romanian||Alte limbi|| ||ru||русский||Russian||Другие языки|| ||Sq||shqip||Albanian||Gjuhët e tjera|| ||Sk||slovenčina||Slovak||Ďalšie jazyky|| ||Sl||slovenščina||Slovenian||Drugi jeziki|| ||Sr||српски||Serbian||Остали језици|| ||Sv||svenska||Swedish||Andra språk|| ||Th||ไทย||Thai||ภาษาอื่น ๆ|| ||Tr||Türkçe||Turkish||Diğer diller|| ||Uk||українська||Ukrainian||Інші мови|| ||Uz||ўзбек тили||Uzbek||Boshqa tillarda|| ||vn||Tiếng Việt||Vietnamese||Ngôn ngữ khác|| ||Zh_CN||简体中文||Chinese (Simplified)||其他语言|| ||Zh_TW||正體中文||Chinese (Traditional)||其他語言||

 r40542 = Trac Links = [[TracGuideToc]] TracLinks are a fundamental feature of Trac, because they allow easy hyperlinking between the various entities in the system—such as tickets, reports, changesets, Wiki pages, milestones, and source files—from anywhere WikiFormatting is used. TracLinks are generally of the form '''type:id''' (where ''id'' represents the number, name or path of the item) though some frequently used kinds of items also have short-hand notations. == Where to use TracLinks == You can use TracLinks in: * Source code (Subversion) commit messages * Wiki pages * Full descriptions for tickets, reports and milestones and any other text fields explicitly marked as supporting WikiFormatting. == Overview == ||= Wiki Markup =||= Display =|| {{{#!td Wiki pages :: CamelCase or wiki:CamelCase Parent page :: [..] Tickets :: #1 or ticket:1 Ticket comments :: comment:1:ticket:2 Reports :: {1} or report:1 Milestones :: milestone:1.0 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path) Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository] Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk] Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default or diff:trunk/trac@3538//sandbox/vc-refactoring@3539 Files :: source:trunk/COPYING, source:/trunk/COPYING@200 (at version 200), source:/trunk/COPYING@200#L25 (at version 200, line 25) }}} {{{#!td Wiki pages :: CamelCase or wiki:CamelCase Parent page :: [..] Tickets :: #1 or ticket:1 Ticket comments :: comment:1:ticket:2 Reports :: {1} or report:1 Milestones :: milestone:1.0 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path) Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository] Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk] Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default or diff:trunk/trac@3538//sandbox/vc-refactoring@3539 Files :: source:trunk/COPYING, source:/trunk/COPYING@200 (at version 200), source:/trunk/COPYING@200#L25 (at version 200, line 25) }}} '''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to pages whose names do not follow WikiPageNames rules, i.e., single words, non-alphabetic characters, etc. See WikiPageNames for more about features specific to links to Wiki page names. {{{#!table class="" |||| Trac links using the full (non-shorthand) notation can also be given a custom link title like this: || {{{#!td {{{ [ticket:1 This is a link to ticket number one] or [[ticket:1|This is another link to ticket number one]]. }}} }}} {{{#!td [ticket:1 This is a link to ticket number one] or [[ticket:1|This is another link to ticket number one]]. }}} |-------------------------------------------------------------------------------------- |||| If the title is omitted, only the id (the part after the colon) is displayed:  || {{{#!td {{{ [ticket:1] or [[ticket:2]] }}} }}} {{{#!td [ticket:1] or [[ticket:2]] }}} |-------------------------------------------------------------------------------------- |||| wiki is the default if the namespace part of a full link is omitted:  || {{{#!td {{{ [SandBox the sandbox] or [[SandBox|the sandbox]] }}} }}} {{{#!td [SandBox the sandbox] or [[SandBox|the sandbox]] }}} |-------------------------------------------------------------------------------------- |||| The short form ''realm:target'' can also be wrapped within a <...> pair, [[br]] which allow for arbitrary characters (i.e. anything but >)  || {{{#!td {{{ }}} }}} {{{#!td }}} }}} TracLinks are a very simple idea, but actually allow quite a complex network of information. In practice, it's very intuitive and simple to use, and we've found the "link trail" extremely helpful to better understand what's happening in a project or why a particular change was made. == Advanced use of TracLinks == === Relative links === To create a link to a [trac:SubWiki SubWiki]-page just use a '/': {{{ WikiPage/SubWikiPage or ./SubWikiPage }}} To link from a [trac:SubWiki SubWiki] page to a parent, simply use a '..': {{{ [..] or [[..]] }}} [..] or [[..]] To link from a [trac:SubWiki SubWiki] page to a [=#sibling sibling] page, use a '../': {{{ [../Sibling see next sibling] or [[../Sibling|see next sibling]] }}} [../Sibling see next sibling] or [[../Sibling|see next sibling]] But in practice you often won't need to add the ../ prefix to link to a sibling page. For resolving the location of a wiki link, it's the target page closest in the hierarchy to the page where the link is written which will be selected. So for example, within a sub-hierarchy, a sibling page will be targeted in preference to a toplevel page. This makes it easy to copy or move pages to a sub-hierarchy by [[WikiNewPage#renaming|renaming]] without having to adapt the links. In order to link explicitly to a [=#toplevel toplevel] Wiki page, use the wiki:/ prefix. Be careful **not** to use the / prefix alone, as this corresponds to the [#Server-relativelinks] syntax and with such a link you will lack the /wiki/ part in the resulting URL. A link such as [../newticket] will stay in the wiki namespace and therefore link to a sibling page. === Link anchors === To create a link to a specific anchor in a page, use '#': {{{ [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]] }}} [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]] Hint: when you move your mouse over the title of a section, a '¶' character will be displayed. This is a link to that specific section and you can use this to copy the #... part inside a relative link to an anchor. To create a link to the first or last occurrence of a term on a page, use a ''pseudo anchor'' starting with '#/' or '#?': {{{ [#/Milestone first occurrence of Milestone] or [#?Milestone last occurrence of Milestone] }}} [#/Milestone first occurrence of Milestone] or [#?Milestone last occurrence of Milestone] This will also highlight all other matches on the linked page. By default only case sensitive matches are considered. To include case insensitive matches append '/i': {{{ [#/Milestone/i first occurrence of Milestone or milestone] or [#?Milestone/i last occurrence of Milestone or milestone] }}} [#/Milestone/i first occurrence of Milestone or milestone] or [#?Milestone/i last occurrence of Milestone or milestone] ''(since Trac 1.0)'' Such anchors can be very useful for linking to specific lines in a file in the source browser: {{{ [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47] }}} [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47] (Hint: The line numbers displayed in the source browser are links to anchors on the respective lines.) Since such links become outdated when the file changes, it can be useful to link using a '#/' pseudo anchor instead: {{{ [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider] }}} [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider] === InterWiki links === Other prefixes can be defined freely and made to point to resources in other Web applications. The definition of those prefixes as well as the URLs of the corresponding Web applications is defined in a special Wiki page, the InterMapTxt page. Note that while this could be used to create links to other Trac environments, there's a more specialized way to register other Trac environments which offers greater flexibility. === InterTrac links === This can be seen as a kind of InterWiki link specialized for targeting other Trac projects. Any type of Trac link can be written in one Trac environment and actually refer to resources in another Trac environment. All that is required is to prefix the Trac link with the name of the other Trac environment followed by a colon. The other Trac environment must be registered on the InterTrac page. A distinctive advantage of InterTrac links over InterWiki links is that the shorthand form of Trac links (e.g. {}, r, #) can also be used. For example if T was set as an alias for Trac, links to Trac tickets can be written #T234, links to Trac changesets can be written [trac 1508]. See InterTrac for the complete details. === Server-relative links === It is often useful to be able to link to objects in your project that have no built-in Trac linking mechanism, such as static resources, newticket, a shared /register page on the server, etc. To link to resources inside the project, use either an absolute path from the project root, or a relative link from the URL of the current page (''Changed in 0.11''): {{{ [/newticket Create a new ticket] or [[//newticket|Create a new ticket]] [/ home] or [[/|home]] }}} Display: [/newticket Create a new ticket] or [[//newticket|Create a new ticket]] [/ home] or [[/|home]] To link to another location on the server (possibly outside the project but on the same host), use the // prefix (''Changed in 0.11''): {{{ [//register Register Here] or [[//register|Register Here]] }}} Display: [//register Register Here] or [[//register|Register Here]] === Quoting space in TracLinks === Immediately after a TracLinks prefix, targets containing space characters should be enclosed in a pair of quotes or double quotes. Examples: * !wiki:"The whitespace convention" * !attachment:'the file.txt' or * !attachment:"the file.txt" * !attachment:"the file.txt:ticket:123" Note that by using [trac:WikiCreole] style links, it's quite natural to write links containing spaces: * ![[The whitespace convention]] * ![[attachment:the file.txt]] === Escaping Links === To prevent parsing of a !TracLink, you can escape it by preceding it with a '!' (exclamation mark). {{{ !NoLinkHere. ![42] is not a link either. }}} Display: !NoLinkHere. ![42] is not a link either. === Parameterized Trac links === Many Trac resources have more than one way to be rendered, depending on some extra parameters. For example, a Wiki page can accept a version or a format parameter, a report can make use of dynamic variables, etc. Trac links can support an arbitrary set of parameters, written in the same way as they would be for the corresponding URL. Some examples: - wiki:WikiStart?format=txt - ticket:1?version=1 - [/newticket?component=module1 create a ticket for module1] - [/newticket?summary=Add+short+description+here create a ticket with URL with spaces] == TracLinks Reference == The following sections describe the individual link types in detail, as well as notes on advanced usage of links. === attachment: links === The link syntax for attachments is as follows: * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current object * !attachment:the_file.txt:wiki:MyPage creates a link to the attachment the_file.txt of the !MyPage wiki page * !attachment:the_file.txt:ticket:753 creates a link to the attachment the_file.txt of the ticket 753 Note that the older way, putting the filename at the end, is still supported: !attachment:ticket:753:the_file.txt. If you'd like to create a direct link to the content of the attached file instead of a link to the attachment page, simply use raw-attachment: instead of attachment:. This can be useful for pointing directly to an HTML document, for example. Note that for this use case, you'd have to allow the web browser to render the content by setting [attachment] render_unsafe_content = yes (see TracIni#attachment-section). Caveat: only do that in environments for which you're 100% confident you can trust the people who are able to attach files, as otherwise this would open up your site to [wikipedia:Cross-site_scripting cross-site scripting] attacks. See also [#export:links]. === comment: links === When you're inside a given ticket, you can simply write e.g. !comment:3 to link to the third change comment. It is possible to link to a comment of a specific ticket from anywhere using one of the following syntax: - comment:3:ticket:123 - ticket:123#comment:3 (note that you can't write #123#!comment:3!) It is also possible to link to the ticket's description using one of the following syntax: - comment:description (within the ticket) - comment:description:ticket:123 - ticket:123#comment:description === htdocs: links === Use htdocs:path/to/file to reference files in the htdocs directory of the Trac environment, the [TracEnvironment#DirectoryStructure web resource directory]. === query: links === See TracQuery#UsingTracLinks and [#ticket:links]. === search: links === See TracSearch#SearchLinks === ticket: links === ''alias:'' bug: Besides the obvious ticket:id form, it is also possible to specify a list of tickets or even a range of tickets instead of the id. This generates a link to a custom query view containing this fixed set of tickets. Example: - ticket:5000-6000 - ticket:1,150 === timeline: links === Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC. Examples: - timeline:2008-01-29 - timeline:2008-01-29T15:48 - timeline:2008-01-29T15:48Z - timeline:2008-01-29T16:48+01 - timeline:2008-01-29T16:48+0100 - timeline:2008-01-29T16:48+01:00 === wiki: links === See WikiPageNames and [#QuotingspaceinTracLinks quoting space in TracLinks] above. It is possible to create a link to a specific page revision using the syntax WikiStart@1. === Version Control related links === It should be noted that multiple repository support works by creating a kind of virtual namespace for versioned files in which the toplevel folders correspond to the repository names. Therefore, in presence of multiple repositories, a ''/path'' specification in the syntax of links detailed below should start with the name of the repository. If omitted, the default repository is used. In case a toplevel folder of the default repository has the same name as a repository, the latter "wins". One can always access such folder by fully qualifying it (the default repository can be an alias of a named repository, or conversely, it is always possible to create an alias for the default repository, ask your Trac administrator). For example, source:/trunk/COPYING targets the path /trunk/COPYING in the default repository, whereas source:/projectA/trunk/COPYING targets the path /trunk/COPYING in the repository named projectA. This can be the same file if 'projectA' is an alias to the default repository or if '' (the default repository) is an alias to 'projectA'. ==== source: links ==== ''aliases:'' browser:, repos: The default behavior for a source:/some/path link is to open the browser in that directory directory if the path points to a directory or to show the latest content of the file. It's also possible to link directly to a specific revision of a file like this: - source:/some/file@123 - link to the file's revision 123 - source:/some/file@head - link explicitly to the latest revision of the file If the revision is specified, one can even link to a specific line number: - source:/some/file@123#L10 - source:/tag/0.10@head#L10 Finally, one can also highlight an arbitrary set of lines: - source:/some/file@123:10-20,100,103#L99 - highlight lines 10 to 20, and lines 100 and 103, and target line 99 - or without version number (the @ is still needed): source:/some/file@:10-20,100,103#L99. Version can be omitted when the path is pointing to a source file that will no longer change (like source:/tags/...), otherwise it's better to specify which lines of //which version// of the file you're talking about Note that in presence of multiple repositories, the name of the repository is simply integrated in the path you specify for source: (e.g. source:reponame/trunk/README). ''(since 0.12)'' ==== export: links ==== To force the download of a file in the repository, as opposed to displaying it in the browser, use the export link.  Several forms are available: * export:/some/file - get the HEAD revision of the specified file * export:123:/some/file - get revision 123 of the specified file * export:/some/file@123 - get revision 123 of the specified file This can be very useful for displaying XML or HTML documentation with correct stylesheets and images, in case that has been checked in into the repository. Note that for this use case, you'd have to allow the web browser to render the content by setting [browser] render_unsafe_content = yes (see TracIni#browser-section), otherwise Trac will force the files to be downloaded as attachments for security concerns. If the path is to a directory in the repository instead of a specific file, the source browser will be used to display the directory (identical to the result of source:/some/dir). ==== log: links ==== The log: links are used to display revision ranges. In its simplest form, it can link to the latest revisions of the specified path, but it can also support displaying an arbitrary set of revisions. - log:/ - the latest revisions starting at the root of the repository - log:/trunk/tools - the latest revisions in trunk/tools - log:/trunk/tools@10000 - the revisions in trunk/tools starting from  revision 10000 - log:@20788,20791:20795 - list revision 20788 and the revisions from 20791 to 20795 - log:/trunk/tools@20788,20791:20795 - list revision 20788 and the revisions from 20791 to 20795 which affect the given path There are short forms for revision ranges as well: - [20788,20791:20795] - [20788,20791:20795/trunk/tools] - r20791:20795 (but not r20788,20791:20795 nor r20791:20795/trunk) Finally, note that in all of the above, a revision range can be written either as x:y or x-y. In the presence of multiple repositories, the name of the repository should be specified as the first part of the path, e.g. log:repos/branches or [20-40/repos]. ---- See also: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki

 r40542 = Trac Logging [[TracGuideToc]] Trac supports logging of system messages using the standard [http://docs.python.org/library/logging.html logging module] that comes with Python. Logging is configured in the [logging] section in [wiki:TracIni#logging-section trac.ini]. == Supported Logging Methods The log method is set using the log_type option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values: '''none'':: Suppress all log messages. '''file''':: Log messages to a file, specified with the log_file option in [wiki:TracIni#logging-section trac.ini]. Relative paths in log_file are resolved relative to the log directory of the environment. '''stderr''':: Output all log entries to console ([wiki:TracStandalone tracd] only). '''syslog''':: (UNIX) Send all log messages to the local syslogd via named pipe /dev/log. By default, syslog will write them to the file /var/log/messages. '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging. == Log Levels The verbosity level of logged messages can be set using the log_level option in [wiki:TracIni#logging-section trac.ini]. The log level defines the minimum level of urgency required for a message to be logged, and those levels are: '''CRITICAL''':: Log only the most critical (typically fatal) errors. '''ERROR''':: Log failures, bugs and errors. '''WARN''':: Log warnings, non-interrupting events. '''INFO''':: Diagnostic information, log information about all processing. '''DEBUG''':: Trace messages, profiling, etc. Additionally, you can  enable logging of SQL statements at debug level. This is turned off by default, as it's very verbose. Set [trac] debug_sql = yes in TracIni to activate. == Log Format The output format for log entries can be specified through the log_format option in [wiki:TracIni#logging-section trac.ini]. The format is a string which can contain any of the [http://docs.python.org/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additonally, the following Trac-specific variables can be used: '''$(basename)s''':: The last path component of the current environment. '''$(path)s''':: The absolute path for the current environment. '''$(project)s''':: The originating project's name. Note that variables are identified using a dollar sign ($(...)s) instead of percent sign (%(...)s). The default format is: {{{#!ini log_format = Trac[$(module)s]$(levelname)s: $(message)s }}} In a multi-project environment where all logs are sent to the same place (e.g. syslog), it makes sense to add the project name. In this example we use basename since that can generally be used to identify a project: {{{#!ini log_format = Trac[$(basename)s:$(module)s]$(levelname)s: $(message)s }}} ---- See also: TracIni, TracGuide, TracEnvironment • ## wiki/pages/TracModPython  r40542 [[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. 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)]] == Simple configuration: single project == #Simpleconfiguration 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: {{{#!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 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+. {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler mod_python.testhandler Order allow,deny Allow from all }}} A simple setup of Trac on mod_python looks like this: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /var/trac/myproject PythonOption TracUriRoot /projects/myproject Order allow,deny Allow from all }}} 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 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. {{{#!apache ... PythonOption PYTHON_EGG_CACHE /tmp ... }}} === 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 ... PythonPath "sys.path + ['/path/to/trac']" ... }}} Be careful about using the !PythonPath directive, and ''not'' SetEnv PYTHONPATH, as the latter won't work. === Setting up multiple projects The Trac mod_python handler supports a configuration option similar to Subversion's SvnParentPath, called TracEnvParentDir: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /var/trac PythonOption TracUriRoot /projects }}} When you request the /projects URL, you will get a listing of all subdirectories of the directory you set as TracEnvParentDir that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment. If you don't want to have the subdirectory listing as your projects home page you can use a {{{#!apache }}} This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder. You can also use the same authentication realm for all of the projects using a  directive: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /var/trac/.htpasswd Require valid-user }}} === 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 SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /var/trac/myproject PythonOption TracUriRoot / AuthType Basic AuthName "MyCompany Trac Server" AuthUserFile /var/trac/myproject/.htpasswd Require valid-user }}} 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, 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 If you get server error pages, you can either check the Apache error log, or enable the PythonDebug option: {{{#!apache ... PythonDebug on }}} For multiple projects, try restarting the server as well. === 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): {{{#!apache #this one for other pages SetHandler mod_python PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /projects PythonOption TracUriRoot / #this one for login page SetHandler mod_python PythonHandler trac.web.modpython_frontend PythonOption TracEnvParentDir /projects PythonOption TracUriRoot / #remove these if you don't want to force SSL RewriteEngine On RewriteCond %{HTTPS} off RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} AuthType Basic AuthName "Trac" AuthUserFile /projects/.htpasswd Require valid-user }}} === Expat-related segmentation faults === #expat This problem will most certainly hit you on Unix when using Python 2.4. 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 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 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. This also works out-of-box, with following trivial config: {{{#!apache SetHandler mod_python PythonInterpreter main_interpreter PythonHandler trac.web.modpython_frontend PythonOption TracEnv /system/path/to/this/directory PythonOption TracUriRoot /path/on/apache AuthType Basic AuthName "ProjectName" AuthUserFile /path/to/.htpasswd Require valid-user }}} 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, 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.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. 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 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" SetHandler None }}} '''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 SetEnv HTTPS 1 .... }}} === 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] • ## wiki/pages/TracModWSGI  r40542 = Trac and mod_wsgi [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance. [[PageOutline(2-3,Overview,inline)]] == The trac.wsgi script Trac can be run on top of mod_wsgi with the help of an application script, which is just a Python file saved with a .wsgi extension. A robust and generic version of this file can be created using the trac-admin deploy  command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache]. If you are using Trac with multiple projects, you can specify their common parent directory using the TRAC_ENV_PARENT_DIR in trac.wsgi: {{{#!python def application(environ, start_request): # Add this to config when you have multiple projects environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') .. }}} === A very basic script In its simplest form, the script could be: {{{#!python import os os.environ['TRAC_ENV'] = '/usr/local/trac/mysite' os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' import trac.web.main application = trac.web.main.dispatch_request }}} The TRAC_ENV variable should naturally be the directory for your Trac environment, and the PYTHON_EGG_CACHE should be a directory where Python can temporarily extract Python eggs. If you have several Trac environments in a directory, you can also use TRAC_ENV_PARENT_DIR instead of TRAC_ENV. On Windows: - If run under the user's session, the Python Egg cache can be found in %AppData%\Roaming, for example: {{{#!python os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs' }}} - If run under a Window service, you should create a directory for Python Egg cache: {{{#!python os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs' }}} === A more elaborate script If you are using multiple .wsgi files (for example one per Trac environment) you must ''not'' use os.environ['TRAC_ENV'] to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment. To solve this problem, use the following .wsgi file instead: {{{#!python import os os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' import trac.web.main def application(environ, start_response): environ['trac.env_path'] = '/usr/local/trac/mysite' return trac.web.main.dispatch_request(environ, start_response) }}} For clarity, you should give this file a .wsgi extension. You should probably put the file in its own directory, since you will expose it to Apache. If you have installed Trac and Python eggs in a path different from the standard one, you should add that path by adding the following code at the top of the wsgi script: {{{#!python import site site.addsitedir('/usr/local/trac/lib/python2.4/site-packages') }}} Change it according to the path you installed the Trac libs at. == Mapping requests to the script After preparing your .wsgi script, add the following to your Apache configuration file, typically httpd.conf: {{{#!apache WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all }}} Here, the script is in a subdirectory of the Trac environment. If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following: {{{#!apache WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all }}} In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the WSGIApplicationGroup directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi. This is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash. After adding this configuration, restart Apache, and then it should work. To test the setup of Apache, mod_wsgi and Python itself (ie. without involving Trac and dependencies), this simple wsgi application can be used to make sure that requests gets served (use as only content in your .wsgi script): {{{#!python def application(environ, start_response): start_response('200 OK',[('Content-type','text/html')]) return ['Hello World!'] }}} For more information about using the mod_wsgi specific directives, see the [http://code.google.com/p/modwsgi/wiki/ mod_wsgi's wiki] and more specifically the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac IntegrationWithTrac] page. == Configuring Authentication The following sections describe different methods for setting up authentication. See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide. === Using Basic Authentication The simplest way to enable authentication with Apache is to create a password file. Use the htpasswd program as follows: {{{#!sh$ htpasswd -c /somewhere/trac.htpasswd admin New password: Re-type new password: Adding password for user admin }}} After the first user, you don't need the "-c" option anymore: {{{#!sh $htpasswd /somewhere/trac.htpasswd john New password: Re-type new password: Adding password for user john }}} ''See the man page for htpasswd for full documentation.'' After you've created the users, you can set their permissions using TracPermissions. Now, you need to enable authentication against the password file in the Apache configuration: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} If you are hosting multiple projects, you can use the same password file for all of them: {{{#!apache AuthType Basic AuthName "Trac" AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} Note that neither a file nor a directory named 'login' needs to exist.[[BR]] See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation. === Using Digest Authentication For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. You have to create your .htpasswd file with the htdigest command instead of htpasswd, as follows: {{{#!sh$ htdigest -c /somewhere/trac.htpasswd trac admin }}} The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive: {{{#!apache AuthType Digest AuthName "trac" AuthDigestDomain /trac AuthUserFile /somewhere/trac.htpasswd Require valid-user }}} For multiple environments, you can use the same LocationMatch as described with the previous method. '''Note: Location cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity. ''' Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system: {{{#!apache LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so }}} See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation. === Using LDAP Authentication Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is more involved (httpd 2.2.x and OpenLDAP: slapd 2.3.19). 1. You need to load the following modules in Apache httpd.conf: {{{#!apache LoadModule ldap_module modules/mod_ldap.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so }}} 1. Your httpd.conf also needs to look something like: {{{#!apache # (if you're using it, mod_python specific settings go here) Order deny,allow Deny from all Allow from 192.168.11.0/24 AuthType Basic AuthName "Trac" AuthBasicProvider "ldap" AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)" authzldapauthoritative Off Require valid-user }}} 1. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL: {{{#!apache AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)" }}} You will also need to provide an account for Apache to use when checking credentials. As this password will be listed in plaintext in the config, you need to use an account specifically for this task: {{{#!apache AuthLDAPBindDN ldap-auth-user@example.com AuthLDAPBindPassword "password" }}} The whole section looks like: {{{#!apache # (if you're using it, mod_python specific settings go here) Order deny,allow Deny from all Allow from 192.168.11.0/24 AuthType Basic AuthName "Trac" AuthBasicProvider "ldap" AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)" AuthLDAPBindDN       ldap-auth-user@company.com AuthLDAPBindPassword "the_password" authzldapauthoritative Off # require valid-user Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com }}} Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to the Global Catalog Server portion of AD. Note the port is 3268, not the normal LDAP 389. The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong. Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login: {{{#!apache Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com }}} See also: - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap. - [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap], documentation for mod_ldap, which provides connection pooling and a shared cache. - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP. === Using SSPI Authentication If you are using Apache on Windows, you can use mod_auth_sspi to provide single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the following to your !VirtualHost: {{{#!apache AuthType SSPI AuthName "Trac Login" SSPIAuth On SSPIAuthoritative On SSPIDomain MyLocalDomain SSPIOfferBasic On SSPIOmitDomain Off SSPIBasicPreferred On Require valid-user }}} Using the above, usernames in Trac will be of the form DOMAIN\username, so you may have to re-add permissions and such. If you do not want the domain to be part of the username, set SSPIOmitDomain On instead. Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338]. See also [trac:TracOnWindows/Advanced]. === Using Apache authentication with the Account Manager plugin's Login form === To begin with, see the basic instructions for using the Account Manager plugin's [http://trac-hacks.org/wiki/AccountManagerPlugin/Modules#LoginModule Login module] and its [http://trac-hacks.org/wiki/AccountManagerPlugin/AuthStores#HttpAuthStore HttpAuthStore authentication module]. '''Note:''' If is difficult to get !HttpAuthStore to work with WSGI when using any Account Manager version prior to acct_mgr-0.4. Upgrading is recommended. Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project: {{{#!ini [components] ; be sure to enable the component acct_mgr.http.HttpAuthStore = enabled [account-manager] ; configure the plugin to use a page that is secured with http authentication authentication_url = /authFile password_store = HttpAuthStore }}} This will generally be matched with an Apache config like: {{{#!apache …HTTP authentication configuration… Require valid-user }}} Note that '''authFile''' need not exist (unless you are using Account Manager older than 0.4). See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server. === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host Per the mod_wsgi documentation linked to above, here is an example Apache configuration that: - serves the Trac instance from a virtualhost subdomain - uses Apache basic authentication for Trac authentication. If you want your Trac to be served from e.g. !http://trac.my-proj.my-site.org, then from the folder e.g. /home/trac-for-my-proj, if you used the command trac-admin the-env initenv to create a folder the-env, and you used trac-admin the-env deploy the-deploy to create a folder the-deploy, then first: Create the htpasswd file: {{{#!sh cd /home/trac-for-my-proj/the-env htpasswd -c htpasswd firstuser ### and add more users to it as needed: htpasswd htpasswd seconduser }}} Keep the file above your document root for security reasons. Create this file e.g. (ubuntu) /etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf with the following content: {{{#!apache WSGIApplicationGroup %{GLOBAL} Order deny,allow Allow from all ServerName trac.my-proj.my-site.org DocumentRoot /home/trac-for-my-proj/the-env/htdocs/ WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi AuthType Basic AuthName "Trac" AuthUserFile /home/trac-for-my-proj/the-env/htpasswd Require valid-user }}} Note: for subdomains to work you would probably also need to alter /etc/hosts and add A-Records to your host's DNS. == Troubleshooting === Use a recent version Please use either version 1.6, 2.4 or later of mod_wsgi. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem, attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [http://code.google.com/p/modwsgi/issues/detail?id=100 #100] and [http://code.google.com/p/modwsgi/issues/detail?id=132 #132]. ''Note: using mod_wsgi 2.5 and Python 2.6.1 gave an Internal Server Error on my system (Apache 2.2.11 and Trac 0.11.2.1). Upgrading to Python 2.6.2 (as suggested [http://www.mail-archive.com/modwsgi@googlegroups.com/msg01917.html here]) solved this for me[[BR]]-- Graham Shanks'' If you plan to use mod_wsgi in embedded mode on Windows or with the MPM worker on Linux, then you will need version 3.4 or greater. See [trac:#10675] for details. === Getting Trac to work nicely with SSPI and 'Require Group' If you have set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your apache configuration, then the SSPIOmitDomain option is probably not working. If it is not working, your usernames in Trac probably look like 'DOMAIN\user' rather than 'user'. This WSGI script 'fixes' that: {{{#!python import os import trac.web.main os.environ['TRAC_ENV'] = '/usr/local/trac/mysite' os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs' def application(environ, start_response): if "\\" in environ['REMOTE_USER']: environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1] return trac.web.main.dispatch_request(environ, start_response) }}} === Trac with PostgreSQL When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as the database, the server ''may'' create a lot of open database connections and thus PostgreSQL processes. A somewhat brutal workaround is to disable connection pooling in Trac. This is done by setting poolable = False in trac.db.postgres_backend on the PostgreSQLConnection class. But it is not necessary to edit the source of Trac. The following lines in trac.wsgi will also work: {{{#!python import trac.db.postgres_backend trac.db.postgres_backend.PostgreSQLConnection.poolable = False }}} or {{{#!python import trac.db.mysql_backend trac.db.mysql_backend.MySQLConnection.poolable = False }}} Now Trac drops the connection after serving a page and the connection count on the database will be kept low. //This is not a recommended approach though. See also the notes at the bottom of the [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac mod_wsgi's IntegrationWithTrac] wiki page.// === Other resources For more troubleshooting tips, see also the [TracModPython#Troubleshooting mod_python troubleshooting] section, as most Apache-related issues are quite similar, plus discussion of potential [http://code.google.com/p/modwsgi/wiki/ApplicationIssues application issues] when using mod_wsgi. The wsgi page also has a [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac Integration With Trac] document. ---- See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]

 r40542 = Trac Navigation The main and meta navigation entries can be customized in some basic ways. The [mainnav] and [metanav] configuration sections can be used to customize the navigation item text and link, change the ordering of the navigation items, or even disable them. === [mainnav] #mainnav-bar [mainnav] corresponds to the '''main navigation bar''', the one containing entries such as ''Wiki'', ''Timeline'', ''Roadmap'', ''Browse Source'' and so on. This navigation bar is meant to access the default page of the main modules enabled in Trac that are accessible for the current user. ** [=#Example Example] ** In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report. {{{#!ini [mainnav] wiki.label = Home tickets.href = /report/24 }}} === [metanav] #metanav-bar [metanav] corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Login'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user. There is one special entry in the  [metanav] section: logout.redirect is the page the user sees after hitting the logout button.  The ''!Help/Guide'' link is also hidden in the following example. [[comment(see also #Trac3808)]] ** Example ** {{{#!ini [metanav] help = disabled logout.redirect = wiki/Logout }}} === URL Formats Possible URL formats for .href or .redirect: || '''config''' || '''redirect to''' || || wiki/Logout || /projects/env/wiki/Logout || || http://hostname/ || http://hostname/ || || /projects || /projects || === Ordering #nav-order The order attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items. Non-negative floating point values may be used for the order attribute. The navigation items will be arranged from left to right in increasing order. Navigation items without an order attribute are sorted alphabetically by name. The default values are: {{{#!ini [mainnav] browser.order = 4 newticket.order = 6 roadmap.order = 3 search.order = 7 tickets.order = 5 timeline.order = 2 wiki.order = 1 [metanav] about.order = 5 help.order = 4 login.order = 1 logout.order = 2 prefs.order = 3 }}} === Context Navigation #ctxtnav-bar Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar. ---- See also: TracInterfaceCustomization, and the [http://trac-hacks.org/wiki/NavAddPlugin TracHacks:NavAddPlugin] or [http://trac-hacks.org/wiki/MenusPlugin TracHacks:MenusPlugin] (still needed for adding entries)

 r40542 = Email Notification of Ticket Changes [[TracGuideToc]] Trac supports notification of ticket changes via email. Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list is set up. Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini]. == Receiving Notification Mails When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket, depending on how notification is configured. === How to use your username to receive notification mails To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page. Alternatively, a default domain name ('''smtp_default_domain''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation. When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''username@EXAMPLE.LOCAL'''). To avoid this being interpreted as an email address, add the Kerberos domain to  ('''ignore_domains'''). === Ticket attachment notifications Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the TicketAttachmentNotifier component must be disabled: {{{#!ini [components] trac.ticket.notification.TicketAttachmentNotifier = disabled }}} == Configuring SMTP Notification '''Important:''' For TracNotification to work correctly, the [trac] base_url option must be set in [wiki:TracIni trac.ini]. === Configuration Options These are the available options for the [notification] section in trac.ini: [[TracIni(notification)]] === Example Configuration (SMTP) {{{#!ini [notification] smtp_enabled = true smtp_server = mail.example.com smtp_from = notifier@example.com smtp_replyto = myproj@projects.example.com smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com }}} === Example Configuration (sendmail) {{{#!ini [notification] smtp_enabled = true email_sender = SendmailEmailSender sendmail_path = /usr/sbin/sendmail smtp_from = notifier@example.com smtp_replyto = myproj@projects.example.com smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com }}} === Subscriber Configuration The default subscriptions are configured in the [notification-subscriber] section in trac.ini: [[TracIni(notification-subscriber)]] Each user can override these defaults in his ''Notifications'' preferences. For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules. === Customizing the e-mail subject The e-mail subject can be customized with the ticket_subject_template option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is: {{{#!genshi $prefix #$ticket.id: $summary }}} The following variables are available in the template: * env: The project environment (see [trac:source:/trunk/trac/env.py env.py]). * prefix: The prefix defined in smtp_subject_prefix. * summary: The ticket summary, with the old value if the summary was edited. * ticket: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg $ticket.milestone. === Customizing the e-mail content The notification e-mail content is generated based on ticket_notify_email.txt in trac/ticket/templates. You can add your own version of this template by adding a ticket_notify_email.txt to the templates directory of your environment. The default looks like this: {{{#!genshi $ticket_body_hdr$ticket_props {% choose ticket.new %}\ {%   when True %}\ $ticket.description {% end %}\ {% otherwise %}\ {% if changes_body %}\${_('Changes (by %(author)s):', author=change.author)} $changes_body {% end %}\ {% if changes_descr %}\ {% if not changes_body and not change.comment and change.author %}\${_('Description changed by %(author)s:', author=change.author)} {%       end %}\ $changes_descr -- {% end %}\ {% if change.comment %}\${changes_body and _('Comment:') or _('Comment (by %(author)s):', author=change.author)} $change.comment {% end %}\ {% end %}\ {% end %}\ --${_('Ticket URL: <%(link)s>', link=ticket.link)} $project.name <${project.url or abs_href()}> $project.descr }}} == Sample Email {{{ #42: testing ---------------------------+------------------------------------------------ Id: 42 | Status: assigned Component: report system | Modified: Fri Apr 9 00:04:31 2004 Severity: major | Milestone: 0.9 Priority: lowest | Version: 0.6 Owner: anonymous | Reporter: jonas@example.com ---------------------------+------------------------------------------------ Changes: * component: changeset view => search system * priority: low => highest * owner: jonas => anonymous * cc: daniel@example.com => daniel@example.com, jonas@example.com * status: new => assigned Comment: I'm interested too! -- Ticket URL: My Project }}} == Customizing e-mail content for MS Outlook MS Outlook normally presents plain text e-mails with a variable-width font, and as a result the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template]. Replace the following second row in the template: {{{$ticket_props }}} with this (requires Python 2.6 or later): {{{ -------------------------------------------------------------------------- {% with pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in [c.strip() for c in ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]]; sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone', 'Component', 'Severity', 'Resolution', 'Keywords'] %}\ ${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)} {% end %}\ -------------------------------------------------------------------------- }}} The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table when using MS Outlook. {{{#!div style="margin: 1em 1.75em; border:1px dotted" {{{#!html #42: testing -------------------------------------------------------------------------- -------------------------------------------------------------------------- Changes: * component: changeset view => search system * priority: low => highest * owner: jonas => anonymous * cc: daniel@example.com => daniel@example.com, jonas@example.com * status: new => assigned Comment: I'm interested too! -- Ticket URL: <http://example.com/trac/ticket/42> My Project <http://myproj.example.com/> }}} }}} **Important**: Only those ticket fields that are listed in sel are part of the HTML mail. If you have defined custom ticket fields which are to be part of the mail, then they have to be added to sel. Example: {{{ sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2'] }}} However, the solution is still a workaround to an automatically HTML-formatted e-mail. == Using GMail as the SMTP relay host Use the following configuration snippet: {{{#!ini [notification] smtp_enabled = true use_tls = true mime_encoding = base64 smtp_server = smtp.gmail.com smtp_port = 587 smtp_user = user smtp_password = password }}} where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com]. Alternatively, you can use smtp_port = 25.[[br]] You should not use smtp_port = 465. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details. == Troubleshooting If you cannot get the notification working, first make sure the log is activated and have a look at the log to find if an error message has been logged. See TracLogging for help about the log feature. Notification errors are not reported through the web interface, so the user who submits a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace. === ''Permission denied'' error Typical error message: {{{#!sh ... File ".../smtplib.py", line 303, in connect raise socket.error, msg error: (13, 'Permission denied') }}} This error usually comes from a security settings on the server: many Linux distributions do not allow the web server (Apache, ...) to post email messages to the local SMTP server. Many users get confused when their manual attempts to contact the SMTP server succeed: {{{#!sh telnet localhost 25 }}} This is because a regular user may connect to the SMTP server, but the web server cannot: {{{#!sh sudo -u www-data telnet localhost 25 }}} In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help in the Trac [trac:MailingList MailingList] archive. Relevant ML threads: * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518 For SELinux in Fedora 10: {{{#!sh$ setsebool -P httpd_can_sendmail 1 }}} === ''Suspected spam'' error Some SMTP servers may reject the notification email sent by Trac. The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' spam detection on sensitive email servers. In such an event, change the default encoding to "quoted-printable" using the mime_encoding option. Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding. ---- See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]
Reporter:jonas@example.com
Owner:anonymous
Type:defect
Status:assigned
Priority:lowest
Milestone:0.9
Component:report system
Severity:major
Resolution:
Keywords:

• ## wiki/pages/TracQuery

 r40542 = Trac Ticket Queries [[TracGuideToc]] In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', which can be used to display tickets that meet specified criteria. To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link. == Filters When you first go to the query page, the default filter will display tickets relevant to you: * If logged in then all open tickets, it will display open tickets assigned to you. * If not logged in but you have specified a name or email address in the preferences, then it will display all open tickets where your email (or name if email not defined) is in the CC list. * If not logged in and no name/email is defined in the preferences, then all open issues are displayed. Current filters can be removed by clicking the button to the left with the minus sign on the label. New filters are added from the pulldown lists at the bottom corners of the filters box; 'And' conditions on the left, 'Or' conditions on the right.  Filters with either a text box or a pulldown menu of options can be added multiple times to perform an ''Or'' on the criteria. You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket. After you have edited your filters, click the ''Update'' button to refresh your results. == Navigating Tickets Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page. You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Query'' links after saving your results. When you return to the query ''any tickets which were edited'' will be displayed with italicized text. If one of the tickets was edited such that [[html(it no longer matches the query criteria )]], the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold. The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again. == Saving Queries Trac allows you to save the query as a named query accessible from the reports module. To save a query ensure that you have ''Updated'' the view and then click the ''Save query'' button displayed beneath the results. You can also save references to queries in Wiki content, as described below. '''Note:''' one way to easily build queries like the ones below, you can build and test the queries in the Custom report module and when ready - click ''Save query''. This will build the query string for you. All you need to do is remove the extra line breaks. '''Note:''' you must have the '''REPORT_CREATE''' permission in order to save queries to the list of default reports. The ''Save query'' button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query. === Using TracLinks You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page. {{{ [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0] }}} Which is displayed as: [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0] This uses a very simple query language to specify the criteria, see [wiki:TracQuery#QueryLanguage Query Language]. Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading ? character: {{{ [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner] }}} Which is displayed as: [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner] === Customizing the ''table'' format You can also customize the columns displayed in the table format (''format=table'') by using ''col=''. You can specify multiple fields and what order they are displayed in by placing pipes (|) between the columns: {{{ [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]] }}} This is displayed as: [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]] ==== Full rows In ''table'' format you can also have full rows by using ''rows='': {{{ [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]] }}} This is displayed as: [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]] == Query Language query: TracLinks and the [[TicketQuery]] macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (&). Each filter consists of the ticket field name, an operator and one or more values. More than one value are separated by a pipe (|), meaning that the filter matches any of the values. To include a literal & or | in a value, escape the character with a backslash (\). The available operators are: || '''=''' || the field content exactly matches one of the values || || '''~=''' || the field content contains one or more of the values || || '''^=''' || the field content starts with one of the values || || '''$=''' || the field content ends with one of the values || All of these operators can also be negated: || '''!=''' || the field content matches none of the values || || '''!~=''' || the field content does not contain any of the values || || '''!^=''' || the field content does not start with any of the values || || '''!$=''' || the field content does not end with any of the values || The date fields created and modified can be constrained by using the = operator and specifying a value containing two dates separated by two dots (..). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be omitted to avoid having to quote the query string. || '''created=2007-01-01..2008-01-01''' || query tickets created in 2007 || || '''created=lastmonth..thismonth''' || query tickets created during the previous month || || '''modified=1weekago..''' || query tickets that have been modified in the last week || || '''modified=..30daysago''' || query tickets that have been inactive for the last 30 days || ---- See also: TracTickets, TracReports, TracGuide, TicketQuery
• ## wiki/pages/TracReports

 r40542 = Trac Reports = [[TracGuideToc]] The Trac reports module provides a simple, yet powerful reporting facility to present information about tickets in the Trac database. Rather than have its own report definition format, TracReports relies on standard SQL SELECT statements for custom report definition. '''Note:''' ''The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.'' ''You can already completely replace the reports module by the query module simply by disabling the former in [wiki:TracIni trac.ini]:'' {{{ [components] trac.ticket.report.* = disabled }}} ''This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.'' A report consists of these basic parts: * '''ID''' — Unique (sequential) identifier * '''Title''' — Descriptive title * '''Description''' — A brief description of the report, in WikiFormatting text. * '''Report Body''' — List of results from report query, formatted according to the methods described below. * '''Footer''' — Links to alternative download formats for this report. == Changing Sort Order == Simple reports - ungrouped reports to be specific - can be changed to be sorted by any column simply by clicking the column header. If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order. == Changing Report Numbering == There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema: * id integer PRIMARY KEY * author text * title text * query text * description text Changing the ID changes the shown order and number in the ''Available Reports'' list and the report's perma-link. This is done by running something like: {{{ update report set id=5 where id=3; }}} Keep in mind that the integrity has to be maintained (i.e., ID has to be unique, and you don't want to exceed the max, since that's managed by SQLite someplace). You may also need to update or remove the report number stored in the report or query. == Navigating Tickets == Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Report'' link to return to the report page. You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets). == Alternative Download Formats == Aside from the default HTML view, reports can also be exported in a number of alternative formats. At the bottom of the report page, you will find a list of available data formats. Click the desired link to download the alternative report format. === Comma-delimited - CSV (Comma Separated Values) === Export the report as plain text, each row on its own line, columns separated by a single comma (','). '''Note:''' The output is fully escaped so carriage returns, line feeds, and commas will be preserved in the output. === Tab-delimited === Like above, but uses tabs (\t) instead of comma. === RSS - XML Content Syndication === All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac. ---- == Creating Custom Reports == ''Creating a custom report requires a comfortable knowledge of SQL.'' '''Note that you need to set up [TracPermissions#Reports permissions] in order to see the buttons for adding or editing reports.''' A report is basically a single named SQL query, executed and presented by Trac.  Reports can be viewed and created from a custom SQL expression directly in the web interface. Typically, a report consists of a SELECT-expression from the 'ticket' table, using the available columns and sorting the way you want it. == Ticket columns == The ''ticket'' table has the following columns: * id * type * time * changetime * component * severity * priority * owner * reporter * cc * version * milestone * status * resolution * summary * description * keywords See TracTickets for a detailed description of the column fields. Example: '''All active tickets, sorted by priority and time''' {{{ SELECT id AS ticket, status, severity, priority, owner, time AS created, summary FROM ticket WHERE status IN ('new', 'assigned', 'reopened') ORDER BY priority, time }}} Dynamic variables can also be used in the report title and description (since 1.1.1). == Advanced Reports: Dynamic Variables == For more flexible reports, Trac supports the use of ''dynamic variables'' in report SQL statements. In short, dynamic variables are ''special'' strings that are replaced by custom data before query execution. === Using Variables in a Query === The syntax for dynamic variables is simple, any upper case word beginning with '$' is considered a variable. Example: {{{ SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY }}} To assign a value to $PRIORITY when viewing the report, you must define it as an argument in the report URL, leaving out the leading '$'. Example: {{{ http://trac.edgewall.org/reports/14?PRIORITY=high }}} To use multiple variables, separate them with an '&'. Example: {{{ http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical }}} === !Special/Constant Variables === There is one dynamic variable whose value is set automatically (the URL does not have to be changed) to allow practical reports. * $USER — Username of logged in user. Example (''List all tickets assigned to me''): {{{ SELECT id AS ticket,summary FROM ticket WHERE owner=$USER }}} == Advanced Reports: Custom Formatting == Trac is also capable of more advanced reports, including custom layouts, result grouping and user-defined CSS styles. To create such reports, we'll use specialized SQL statements to control the output of the Trac report engine. === Special Columns === To format reports, TracReports looks for 'magic' column names in the query result. These 'magic' names are processed and affect the layout and style of the final report. === Automatically formatted columns === * '''ticket''' — Ticket ID number. Becomes a hyperlink to that ticket. * '''id''' — same as '''ticket''' above when '''realm''' is not set * '''realm''' — together with '''id''', can be used to create links to other resources than tickets (e.g. a realm of ''wiki'' and an ''id'' to a page name will create a link to that wiki page) - for some kind of resources, it may be necessary to specify their ''parent'' resources (e.g. for ''changeset'', which ''repos'') and this can be achieved using the '''parent_realm''' and '''parent_id''' columns * '''created, modified, date, time''' — Format cell as a date and/or time. * '''description''' — Ticket description field, parsed through the wiki engine. '''Example:''' {{{ SELECT id AS ticket, created, status, summary FROM ticket }}} Those columns can also be defined but marked as hidden, see [#column-syntax below]. See trac:wiki/CookBook/Configuration/Reports for some example of creating reports for realms other than ''ticket''. === Custom formatting columns === Columns whose names begin and end with 2 underscores (Example: '''__color__''') are assumed to be ''formatting hints'', affecting the appearance of the row. * '''__group__''' — Group results based on values in this column. Each group will have its own header and table. * '''__grouplink__''' — Make the header of each group a link to the specified URL. The URL is taken from the first row of each group. * '''__color__''' — Should be a numeric value ranging from 1 to 5 to select a pre-defined row color. Typically used to color rows by issue priority. {{{ #!html
Defaults: Color 1 Color 2 Color 3 Color 4 Color 5
}}} * '''__style__''' — A custom CSS style expression to use on the  element of the current row. * '''__class__''' — Zero or more space-separated CSS class names to be set on the  element of the current row. These classes are added to the class name derived from __color__ and the odd / even indicator. '''Example:''' ''List active tickets, grouped by milestone, group header linked to milestone page, colored by priority'' {{{ SELECT p.value AS __color__, t.milestone AS __group__, '../milestone/' || t.milestone AS __grouplink__, (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__, t.id AS ticket, summary FROM ticket t,enum p WHERE t.status IN ('new', 'assigned', 'reopened') AND p.name=t.priority AND p.type='priority' ORDER BY t.milestone, p.value, t.severity, t.time }}} '''Note:''' A table join is used to match ''ticket'' priorities with their numeric representation from the ''enum'' table. === Changing layout of report rows === #column-syntax By default, all columns on each row are display on a single row in the HTML report, possibly formatted according to the descriptions above. However, it's also possible to create multi-line report entries. * '''column_''' — ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be continued on a second line. * '''_column_''' — ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row. * '''_column''' — ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML). This can be used to hide any kind of column, even important ones required for identifying the resource, e.g. id as _id will hide the '''Id''' column but the link to the ticket will be present. '''Example:''' ''List active tickets, grouped by milestone, colored by priority, with  description and multi-line layout'' {{{ SELECT p.value AS __color__, t.milestone AS __group__, (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__, t.id AS ticket, summary AS summary_,             -- ## Break line here component,version, severity, milestone, status, owner, time AS created, changetime AS modified,         -- ## Dates are formatted description AS _description_,                    -- ## Uses a full row changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output FROM ticket t,enum p WHERE t.status IN ('new', 'assigned', 'reopened') AND p.name=t.priority AND p.type='priority' ORDER BY t.milestone, p.value, t.severity, t.time }}} === Reporting on custom fields === If you have added custom fields to your tickets (see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy. If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See [trac:TracIniReportCustomFieldSample TracIniReportCustomFieldSample] for some examples. === A note about SQL rewriting #rewriting Beyond the relatively trivial replacement of dynamic variables, the SQL query is also altered in order to support two features of the reports: 1. [#sort-order changing the sort order] 2. pagination support (limitation of the number of result rows displayed on each page) In order to support the first feature, the sort column is inserted in the ORDER BY clause in the first position or in the second position if a __group__ column is specified (an ORDER BY clause is created if needed). In order to support pagination, a LIMIT ... OFFSET ... clause is appended. The query might be too complex for the automatic rewrite to work correctly, resulting in an erroneous query. In this case you still have the possibility to control exactly how the rewrite is done by manually inserting the following tokens: - @SORT_COLUMN@, the place where the name of the selected sort column will be inserted, - @LIMIT_OFFSET@, the place where the pagination support clause will be added Note that if you write them after an SQL comment, --, you'll effectively disable rewriting if this is what you want! Let's take an example, consider the following SQL query: {{{ -- ## 4: Assigned, Active Tickets by Owner ## -- -- -- List assigned tickets, group by ticket owner, sorted by priority. -- SELECT p.value AS __color__, owner AS __group__, id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, changetime AS _changetime, description AS _description, reporter AS _reporter FROM ticket t,enum p WHERE status = 'assigned' AND p.name=t.priority AND p.type='priority' ORDER BY __group__, p.value, severity, time }}} The automatic rewrite will be the following (4 rows per page, page 2, sorted by component): {{{ SELECT p.value AS __color__, owner AS __group__, id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, changetime AS _changetime, description AS _description, reporter AS _reporter FROM ticket t,enum p WHERE status = 'assigned' AND p.name=t.priority AND p.type='priority' ORDER BY __group__ ASC, component ASC,  __group__, p.value, severity, time LIMIT 4 OFFSET 4 }}} The equivalent SQL query with the rewrite tokens would have been: {{{ SELECT p.value AS __color__, owner AS __group__, id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, changetime AS _changetime, description AS _description, reporter AS _reporter FROM ticket t,enum p WHERE status = 'assigned' AND p.name=t.priority AND p.type='priority' ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time @LIMIT_OFFSET@ }}} If you want to always sort first by priority and only then by the user selected sort column, simply use the following ORDER BY clause: {{{ ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time }}} ---- See also: TracTickets, TracQuery, TracGuide, [http://www.sqlite.org/lang_expr.html Query Language Understood by SQLite]

 r40542 = Repository Administration [[PageOutline(2-3)]] == Quick start #QuickStart * Enable the repository connector(s) for the version control system(s) that you will use. * Add repositories through the //Repositories// admin panel, with trac-admin or in the [repositories] section of [wiki:TracIni#repositories-section trac.ini]. * Set up a call to trac-admin $ENV changeset added$REPO $REV in the post-commit hook of each repository. Additionally, add a call to trac-admin$ENV changeset modified $REPO$REV in the post-revprop-change hook of repositories allowing revision property changes. * Make sure the user under which your hooks are run has write access to the Trac environment, or use a tool like sudo to temporarily elevate privileges. == Enabling the components Support for version control systems is provided by optional components distributed with Trac, which are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them. The version control systems can be enabled by adding the following to the [components] section of your [TracIni#components-section trac.ini], or enabling the components in the //Plugins// admin panel. {{{#!ini tracopt.versioncontrol.svn.* = enabled }}} {{{#!ini tracopt.versioncontrol.git.* = enabled }}} == Specifying repositories #Repositories Trac supports multiple repositories per environment, and the repositories may be for different version control system types. Each repository must be defined in a repository configuration provider, the two supported by default are the [#ReposDatabase database store] and the [#ReposTracIni trac.ini configuration file]. A repository should not be defined in multiple configuration providers. It is possible to define aliases of repositories, that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking links to the old name. A number of attributes can be associated with each repository. The attributes define the repository's location, type, name and how it is displayed in the source browser. The following attributes are supported: ||='''Attribute''' =||='''Description''' =|| ||alias ||\ ||A repository having an alias attribute is an alias to a real repository. All TracLinks referencing the alias resolve to the aliased repository. Note that multiple indirection is not supported, so an alias must always point to a real repository. The alias and dir attributes are mutually exclusive. || ||description ||\ ||The text specified in the description attribute is displayed below the top-level entry for the repository in the source browser. It supports WikiFormatting. || ||dir ||\ ||The dir attribute specifies the location of the repository in the filesystem. It corresponds to the value previously specified in the option [trac] repository_dir. The alias and dir attributes are mutually exclusive. || ||hidden ||When set to true, the repository is hidden from the repository index page in the source browser. Browsing the repository is still possible, and links referencing the repository remain valid. || ||sync_per_request||When set to true the repository will be synced on every request. This is not recommended, instead a post-commit hook should be configured to provide [#ExplicitSync explicit synchronization] and sync_per_request should be set to false.|| ||type ||The type attribute sets the type of version control system used by the repository. Trac supports Subversion and Git out-of-the-box, and plugins add support for many other systems. If type is not specified, it defaults to the value of the [trac] repository_type option. || ||url ||The url attribute specifies the root URL to be used for checking out from the repository. When specified, a "Repository URL" link is added to the context navigation links in the source browser, that can be copied into the tool used for creating the working copy. || A repository name and one of alias or dir attributes are mandatory. All others are optional. For some version control systems, it is possible to specify not only the path to the repository in the dir attribute, but also a ''scope'' within the repository. Trac will then only show information related to the files and changesets below that scope. The Subversion backend for Trac supports this. For other types, check the corresponding plugin's documentation. After adding a repository, the cache for that repository must be re-synchronized once with the trac-admin $ENV repository resync command. repository resync :: Re-synchronize Trac with a repository. === In trac.ini #ReposTracIni Repositories and repository attributes can be specified in the [repositories] section of [wiki:TracIni#repositories-section trac.ini]. Every attribute consists of a key structured as {name}.{attribute} and the corresponding value separated with an equal sign (=). The name of the default repository is empty. The main advantage of specifying repositories in trac.ini is that they can be inherited from a global configuration (see the [wiki:TracIni#GlobalConfiguration global configuration] section of TracIni). One drawback is that, due to limitations in the ConfigParser class used to parse trac.ini, the repository name is always all-lowercase. The following example defines two Subversion repositories named project and lib, and an alias to project as the default repository. This is a typical use case where a Trac environment previously had a single repository (the project repository), and was converted to multiple repositories. The alias ensures that links predating the change continue to resolve to the project repository. {{{#!ini [repositories] project.dir = /var/repos/project project.description = This is the ''main'' project repository. project.type = svn project.url = http://example.com/svn/project project.hidden = true lib.dir = /var/repos/lib lib.description = This is the secondary library code. lib.type = svn lib.url = http://example.com/svn/lib .alias = project }}} Note that name.alias = target makes name an alias for the target repo, not the other way around. === In the database #ReposDatabase Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the trac-admin$ENV repository commands. The admin panel shows the list of all repositories defined in the Trac environment. It allows adding repositories and aliases, editing repository attributes and removing repositories. Note that repositories defined in trac.ini are displayed but cannot be edited. The following [wiki:TracAdmin trac-admin] commands can be used to perform repository operations from the command line. repository add [type]:: Add a repository  located at , and optionally specify its type. repository alias :: Create an alias  for the repository . repository remove :: Remove the repository . repository set :: Set the attribute  to  for the repository . Note that the default repository has an empty name, so it will likely need to be quoted when running trac-admin from a shell. Alternatively, the name "(default)" can be used instead, for example when running trac-admin in interactive mode. == Repository caching The Subversion and Git repository connectors support caching, which improves the performance browsing the repository, viewing logs and viewing changesets. Cached repositories must be [#Synchronization synchronized]; either explicit or implicit synchronization can be used. When searching changesets, only cached repositories are searched. Subversion repositories are cached unless the type is direct-svnfs. Git repositories are cached when [git] [wiki:TracIni#git-section cached_repository] is true. == Repository synchronization #Synchronization Prior to 0.12, Trac synchronized its cache with the repository on every HTTP request. This approach is not very efficient and not practical anymore with multiple repositories. For this reason, explicit synchronization through post-commit hooks was added. There is also new functionality in the form of a repository listener extension point ''(IRepositoryChangeListener)'' that is triggered by the post-commit hook when a changeset is added or modified, and can be used by plugins to perform actions on commit. === Mercurial Repositories Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:#9485] for more information. === Explicit synchronization #ExplicitSync This is the preferred method of repository synchronization. It requires setting the sync_per_request attribute to false, and adding a call to trac-admin in the post-commit hook of each repository. Additionally, if a repository allows changing revision metadata, a call to trac-admin must be added to the post-revprop-change hook as well. changeset added [...]:: Notify Trac that one or more changesets have been added to a repository. changeset modified [...]:: Notify Trac that metadata on one or more changesets in a repository has been modified. The  argument can be either a repository name (use "(default)" for the default repository) or the path to the repository. Note that you may have to set the environment variable PYTHON_EGG_CACHE to the same value as was used for the web server configuration before calling trac-admin, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information. ==== Subversion The following examples are complete post-commit and post-revprop-change scripts for Subversion. They should be edited for the specific environment, marked executable (where applicable) and placed in the hooks directory of each repository. On Unix (post-commit): {{{#!sh #!/bin/sh export PYTHON_EGG_CACHE="/path/to/dir" /usr/bin/trac-admin /path/to/env changeset added "$1" "$2" }}} Note: Check with whereis trac-admin, whether trac-admin is really installed under /usr/bin/ or maybe under /usr/local/bin/ and adapt the path. On Windows (post-commit.cmd): {{{#!bat @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2" }}} The post-revprop-change hook for Subversion is very similar. On Unix (post-revprop-change): {{{#!sh #!/bin/sh export PYTHON_EGG_CACHE="/path/to/dir" /usr/bin/trac-admin /path/to/env changeset modified "$1" "$2" }}} On Windows (post-revprop-change.cmd): {{{#!bat @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2" }}} The Unix variants above assume that the user running the Subversion commit has write access to the Trac environment, which is the case in the standard configuration where both the repository and Trac are served by the web server. If you access the repository through another means, for example svn+ssh://, you may have to run trac-admin with different privileges, for example by using sudo. Note that calling trac-admin in your Subversion hooks can slow down the commit and log editing operations on the client side. You might want to use the [trac:source:trunk/contrib/trac-svn-hook contrib/trac-svn-hook] script which starts trac-admin in an asynchronous way. The script also comes with a number of safety checks and usage advices which should make it easier to set up and test your hooks. There's no equivalent trac-svn-hook.bat for Windows yet, but the script can be run by Cygwin's bash. See the [http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook setups. ==== Git Git hooks can be used in the same way for explicit syncing of Git repositories.  If your git repository is one that gets committed to directly on the machine that hosts trac, add the following to the hooks/post-commit file in your git repo (note: this will do nothing if you only update the repo by pushing to it): {{{#!sh #!/bin/sh REV=$(git rev-parse HEAD) trac-admin /path/to/env changeset added$REV }}} Alternately, if your repository is one that only gets pushed to, add the following to the hooks/post-receive file in the repo: {{{#!sh #!/bin/sh tracenv=/path/to/env     # change with your Trac environment's path repos=                   # change with your repository's name while read oldrev newrev refname; do if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then git rev-list --reverse "$newrev" -- else git rev-list --reverse "$newrev" "^$oldrev" -- fi | xargs trac-admin "$tracenv" changeset added "$repos" done }}} The  argument can be either a repository name (use "(default)" for the default repository) or the path to the repository. ==== Mercurial For Mercurial, add the following entries to the .hgrc file of each repository accessed by Trac (if [trac:TracMercurial] is installed in a Trac plugins directory, download [trac:source:mercurial-plugin/tracext/hg/hooks.py hooks.py] and place it somewhere accessible): {{{#!ini [hooks] ; If mercurial-plugin is installed globally commit = python:tracext.hg.hooks.add_changesets changegroup = python:tracext.hg.hooks.add_changesets ; If mercurial-plugin is installed in a Trac plugins directory commit = python:/path/to/hooks.py:add_changesets changegroup = python:/path/to/hooks.py:add_changesets [trac] env = /path/to/env trac-admin = /path/to/trac-admin }}} === Per-request synchronization #PerRequestSync If the post-commit hooks are not available, the environment can be set up for per-request synchronization. In that case, the sync_per_request attribute for each repository in the database and in [wiki:TracIni#trac-section trac.ini] must be set to false. Note that in this case, the changeset listener extension point is not called, and therefore plugins using it will not work correctly. == Automatic changeset references in tickets You can automatically add a reference to the changeset as a ticket comment 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 installing a post-commit hook as described in [#ExplicitSync], 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. {{{#!ini tracopt.ticket.commit_updater.* = enabled }}} For more information, see the documentation of the CommitTicketUpdater component in the //Plugins// admin panel and the [trac:CommitTicketUpdater] page. == Troubleshooting === My trac-post-commit-hook doesn't work anymore #trac-post-commit-hook You must now use the optional components from tracopt.ticket.commit_updater.*, which you can activate through the Plugins panel in the Administrative part of the web interface, or by directly modifying the [TracIni#components-section "[components]"] section in the trac.ini. Be sure to use [#ExplicitSync explicit synchronization] as explained above.
• ## wiki/pages/TracRevisionLog

 r40542 = Viewing Revision Logs = [[TracGuideToc]] When you browse the repository, it is always possible to view the ''Revision Log'' that corresponds to the repository path. This displays a list of the most recent changesets in which the current path or any other path below it has been modified. == The Revision Log Form == It is possible to set the revision at which the revision log should start, using the ''View log starting at'' field. An empty value or a value of ''head'' is interpreted as the newest changeset. It is also possible to specify the revision at which the log should stop, using the ''Back to'' field. By default it is empty, which means the revision log will show the latest 100 revisions. Also, there are three modes of operation of the revision log. By default, the revision log ''stops on copy'', which means that whenever an ''Add'', ''Copy'' or ''Rename'' operation is detected, no older revision will be shown. That's very convenient when working with branches, as one only sees the history corresponding to what has been done on the branch. It is also possible to indicate that one wants to see what happened before a ''Copy'' or ''Rename'' change, by selecting the ''Follow copies'' mode. This will cross all copies or renames changes. Each time the name of the path changes, there will be an additional indentation level. That way, the changes on the different paths are easily grouped together visually. It is even possible to go past an ''Add'' change, in order to see if there has been a ''Delete'' change on that path, before that ''Add''. This mode corresponds to the mode called ''Show only adds, moves and deletes''. This operation can be quite resource intensive and therefore take some time to be shown on screen. Finally, there's also a checkbox ''Show full log messages'', which controls whether the full content of the commit log message should be displayed for each change, or only a shortened version of it. == The Revision Log Information == For each revision log entry, the following columns are displayed: 1. The first column contains a pair of radio buttons and should be used for selecting the ''old'' and the ''new'' revisions that will be used for [wiki:TracRevisionLog#viewingtheactualchanges viewing the actual changes]. 1. A color code (similar to the one used for the [wiki:TracChangeset#ChangesetHeader changesets]) indicating kind of change. Clicking on this column refreshes the revision log so that it restarts with this change. 1. The '''Revision''' number, displayed as @xyz. This is a link to the TracBrowser, using the displayed revision as the base line. Next to it, you can see a little "wheel" icon [[Image(htdocs:../common/changeset.png)]],  which is clickable and leads to the TracChangeset view for that revision. 1. The '''Date''' at which the change was made. The date is displayed as the time elapsed from the date of the revision. The time elapsed is displayed as the number of hours, days, weeks, months, or years. 1. The '''Author''' of the change. 1. The '''Log Message''', which contains either the truncated or full commit log message, depending on the value of the ''Show full log messages'' checkbox in the form above. == Inspecting Changes Between Revisions == The ''View changes...'' buttons (placed above and below the list of changes, on the left side) will show the set of differences corresponding to the aggregated changes starting from the ''old'' revision (first radio-button) to the ''new'' revision (second radio-button), in the TracChangeset view. Note that the ''old'' revision doesn't need to be actually ''older'' than the ''new'' revision: it simply gives a base for the diff. It's therefore entirely possible to easily generate a ''reverse diff'', for reverting what has been done in the given range of revisions. Finally, if the two revisions are identical, the corresponding changeset will be shown. This has the same effect as clicking on the !ChangeSet number. == Alternative Formats == === The !ChangeLog Text === At the bottom of the page, there's a ''!ChangeLog'' link that will show the range of revisions as currently shown, but as a simple text, matching the usual conventions for !ChangeLog files. === RSS Support === The revision log also provides a RSS feed to monitor the changes. To subscribe to a RSS feed for a file or directory, open its revision log in the browser and click the orange 'XML' icon at the bottom of the page. For more information on RSS support in Trac, see TracRss. ---- See also: TracBrowser, TracChangeset, TracGuide
 r40542 = The Trac Roadmap [[TracGuideToc]] The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project. == The Roadmap View A roadmap is a list of future milestones. The roadmap can be filtered to show or hide ''completed milestones'' and ''milestones with no due date''. In the case that both ''show completed milestones'' and ''hide milestones with no due date'' are selected, ''completed'' milestones with no due date will be shown. == The Milestone View A milestone is a future timeframe in which tickets are expected to be solved. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar. It is possible to further [trac:TracRoadmapCustomGroups customise the ticket grouping] and have multiple ticket statuses shown on the progress bar. It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to [wiki:TracQuery custom queries] listing corresponding tickets. == Roadmap Administration With appropriate permissions it is possible to add, modify and remove milestones using either the web interface (roadmap and milestone pages), web administration interface or by using trac-admin. '''Note:''' Milestone descriptions can not currently be edited using 'trac-admin'. == iCalendar Support The Roadmap supports the [http://www.ietf.org/rfc/rfc2445.txt iCalendar] format to keep track of planned milestones and related tickets from your favorite calendar software. Many calendar applications support the iCalendar specification including * [http://www.apple.com/ical/ Apple iCal] for Mac OS X * the cross-platform [http://www.mozilla.org/projects/calendar/ Mozilla Calendar] * [http://chandlerproject.org Chandler] * [http://kontact.kde.org/korganizer/ Korganizer], the calendar application of the [http://www.kde.org/ KDE] project * [https://wiki.gnome.org/Apps/Evolution Evolution] * [http://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files and appears as a new static calendar in Outlook * [https://www.google.com/calendar/ Google Calendar] To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied. '''Note:''' For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself and associated with a milestone. '''Note:''' To include the milestones in Google Calendar you might need to rewrite the URL. {{{ RewriteEngine on RewriteRule ([^/.]+)/roadmap/([^/.]+)/ics /$1/roadmap?user=$2&format=ics }}} More information about iCalendar can be found at [http://en.wikipedia.org/wiki/ICalendar Wikipedia]. ---- See also: TracTickets, TracReports, TracQuery, [trac:TracRoadmapCustomGroups]
 r40542 = Using Search Trac has built-in search functionality to search for occurrences of keywords and substrings in wiki pages, tickets and changeset properties, such as author, revision and log messages. Apart from the [search: Search module], you will also find a small search field above the navigation bar at all time. It provides convenient access to the search module from all pages. The search results show the most recent modifications ranked first rather than the most relevant result. == Quick searches For quick access to project resources, the quick-search field at the top of every page can be used to enter a [TracLinks wiki link], which will take you directly to the resource identified by that link: * ![42] -- Opens change set 42 * !#42 -- Opens ticket number 42 * !{1} -- Opens report 1 * /trunk -- Opens the browser for the trunk directory in the default repository * /repos1/trunk -- Opens the browser for the trunk directory in the repos1 repository == Advanced === Disabling Quickjump To disable the Quickjump feature for a keyword start the query with an exclamation mark (!): use !TracGuide to search for occurrences of the literal word !TracGuide. === Search Links From the Wiki, it is possible to link to a specific search, using search: links: * search:?q=crash will search for the string "crash" * search:?q=trac+link&wiki=on will search for "trac" and "link" in wiki pages only ---- See also: TracGuide, TracLinks, TracQuery
 r40542 = Tracd Tracd is a lightweight standalone Trac web server. It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer. == Pros * Fewer dependencies: You don't need to install apache or any other web-server. * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin). == Cons * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd. * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead, or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy. == Usage examples A single project on port 8080. (http://localhost:8080/) {{{#!sh $tracd -p 8080 /path/to/project }}} Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use the --hostname option. {{{#!sh$ tracd --hostname=localhost -p 8080 /path/to/project }}} With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/) {{{#!sh $tracd -p 8080 /path/to/project1 /path/to/project2 }}} You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the different projects unique. So if you use /project1/path/to and /project2/path/to, you will only see the second project. An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the -e option. The example above could be rewritten: {{{#!sh$ tracd -p 8080 -e /path/to }}} To exit the server on Windows, be sure to use CTRL-BREAK -- using CTRL-C will leave a Python process running in the background. == Installing as a Windows Service === Option 1 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run: {{{#!cmd C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" " net start tracd }}} '''DO NOT''' use {{{tracd.exe}}}.  Instead register {{{python.exe}}} directly with {{{tracd-script.py}}} as a parameter.  If you use {{{tracd.exe}}}, it will spawn the python process without SRVANY's knowledge.  This python process will survive a {{{net stop tracd}}}. If you want tracd to start automatically when you boot Windows, do: {{{#!cmd sc config tracd start= auto }}} The spacing here is important. {{{#!div Once the service is installed, it might be simpler to run the Registry Editor rather than use the reg add command documented above.  Navigate to:[[BR]] HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters Three (string) parameters are provided: ||!AppDirectory ||C:\Python26\ || ||Application ||python.exe || ||!AppParameters ||scripts\tracd-script.py -p 8080 ... || Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point. (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.) }}} For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run: {{{#!cmd "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py " net start tracd }}} === Option 2 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service. === Option 3 also cygwin's cygrunsrv.exe can be used: {{{#!sh $cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'$ net start tracd }}} == Using Authentication Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives) Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like ext2 or ext3 on Linux, or HFS+ on OSX). Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace --auth with --basic-auth in the command line. The general format for using authentication is: {{{#!sh $tracd -p port --auth="base_project_dir,password_file_path,realm" project_path }}} where: * '''base_project_dir''': the base directory of the project specified as follows: * when serving multiple projects: ''relative'' to the project_path * when serving only a single project (-s): the name of the project directory Don't use an absolute path here as this won't work. ''Note:'' This parameter is case-sensitive even for environments on Windows. * '''password_file_path''': path to the password file * '''realm''': the realm name (can be anything) * '''project_path''': path of the project * **--auth** in the above means use Digest authentication, replace --auth with --basic-auth if you want to use Basic auth. Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name. Examples: {{{#!sh$ tracd -p 8080 \ --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1 }}} Of course, the password file can be be shared so that it is used for more than one project: {{{#!sh \$ tracd -p 8080 \ --auth="p