- Timestamp:
- 03/12/16 20:47:19 (8 years ago)
- Location:
- wiki/pages
- Files:
-
- 54 edited
Legend:
- Unmodified
- Added
- Removed
-
wiki/pages/CamelCase
r26484 r37343 1 = !CamelCase =2 New w ords created by smashing together capitalized words.1 = !CamelCase 2 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. 3 3 4 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.4 !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. 5 5 6 == Customizing the Wiki behavior ==6 == Customizing the Wiki behavior 7 7 8 Some people dislike linking by CamelCase. While Trac remains faithful to the original Wiki style, it provides a number of ways to accomodate users with different preferences:9 * T here's an option (`ignore_missing_pages` in the [wiki:TracIni#wiki-section "[wiki]"] section of TracIni) to simply ignore links to missing pages when the link is written using the CamelCase style, instead of that word being replaced by a gray link followed by a question mark.[[BR]]10 That can be useful when CamelCase style is used to name code artifacts like class names and there's no corresponding page for them.8 While Trac remains faithful to the original Wiki style, it provides a number of ways to accommodate users with different preferences: 9 * To prevent the creation of a new link of a camel-cased word, prefix with '!': `!CamelCase`. 10 * 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. 11 11 * 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. 12 12 * Creation of explicit Wiki links is also easy, see WikiPageNames for details. 13 * In addition, Wiki formatting can be disabled completely in some places (e.g. when rendering commit log messages). See `wiki_format_messages` in the [wiki:TracIni#changeset-section "[changeset]"] section of TracIni.13 * 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. 14 14 15 15 See TracIni for more information on the available options. 16 16 17 == More information on !CamelCase ==17 == More information on !CamelCase 18 18 19 19 * http://c2.com/cgi/wiki?WikiCase -
wiki/pages/InterMapTxt
r26484 r37343 39 39 40 40 {{{ 41 PEP http://www.python.org/peps/pep-$1.html # Python Enhancement Proposal 41 PEP http://www.python.org/dev/peps/pep-$1/ # Python Enhancement Proposal 42 PythonBug http://bugs.python.org/issue$1 # Python Issue #$1 43 Python-issue http://bugs.python.org/issue$1 # Python Issue #$1 44 PythonWiki https://wiki.python.org/moin/ # Python Wiki 45 46 42 47 Trac-ML http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/ # Message $1 in Trac Mailing List 43 48 trac-dev http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/ # Message $1 in Trac Development Mailing List 44 49 50 apidoc http://www.edgewall.org/docs/trac-trunk/html/$1.html # $1 in the API documentation for Trac 51 apiref http://www.edgewall.org/docs/trac-trunk/epydoc/$1.html # $1 in the Epydoc API reference for Trac 52 53 bitten http://bitten.edgewall.org/intertrac/ # Bitten's Trac 54 45 55 Mercurial http://www.selenic.com/mercurial/wiki/index.cgi/ # the wiki for the Mercurial distributed SCM 46 RFC http://rfc.net/rfc$1.html # IETF's RFC $1 56 hg http://www.selenic.com/hg/rev/$1?rev=$2 # Changeset $1 $2 in Mercurial repository 57 hg-issue http://mercurial.selenic.com/bts/issue # Issue $1 in Mercurial BTS 58 59 RFC http://tools.ietf.org/html/rfc$1 # IETF's RFC $1 60 ISO http://en.wikipedia.org/wiki/ISO_ # ISO Standard $1 in Wikipedia 61 kb http://support.microsoft.com/kb/$1/en-us/ # Article $1 in Microsoft's Knowledge Base 62 63 pypi http://pypi.python.org/pypi/ # $1 package in the Python Package Index 64 CheeseShop http://pypi.python.org/pypi/ # $1 package in the Python Package Index 65 peak http://peak.telecommunity.com/DevCenter/ # $1 in Python Enterprise Application Kit's Wiki 66 setuptools-issue http://bugs.python.org/setuptools/issue # issue$1 in legacy Setuptools tracker 67 pypa-setuptools-issue https://bitbucket.org/pypa/setuptools/issue/ # issue #$1 in BitBucket Setuptools tracker 68 69 SQLite http://www.sqlite.org/cvstrac/wiki?p=$1 # $1 page in the CvsTrac for SQLite 70 SQLiteTkt http://www.sqlite.org/cvstrac/tktview?tn=$1 # Ticket $1 in the CvsTrac for SQLite 71 72 mysql-bugs http://bugs.mysql.com/bug.php?id= # Bug #$1 in MySQL's bug database 73 mysql-issue http://bugs.mysql.com/bug.php?id= # Bug #$1 in MySQL's bug database 74 75 MODPYTHON http://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance 76 mod-python-issue http://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance 77 78 SvnWiki http://www.orcaware.com/svn/wiki/ # Subversion Wiki 79 svnissue http://subversion.tigris.org/issues/show_bug.cgi?id= # Subversion issue #$1 80 svn-issue http://subversion.tigris.org/issues/show_bug.cgi?id= # Subversion issue #$1 81 svncset http://svn.collab.net/viewvc/svn?view=revision&revision= # Subversion [$1] 82 83 mod-wsgi http://code.google.com/p/modwsgi/wiki/ # mod_wsgi Wiki on Google Code 84 mod-wsgi-issue http://code.google.com/p/modwsgi/issues/detail?id= # mod_wsgi Issue Tracker on Google Code 85 86 chromium-issue http://code.google.com/p/chromium/issues/detail?id= 87 88 Django http://code.djangoproject.com/intertrac/ # Django's Trac 89 AgileTrac http://www.agile-trac.org/intertrac/ # Plugin adding Iterations to Trac 90 91 CreoleWiki http://wikicreole.org/wiki/ 92 Creole1Wiki http://wikicreole.org/wiki/ 93 Creole2Wiki http://wiki.wikicreole.org/ 94 95 MediaWiki http://www.mediawiki.org/wiki/ 96 97 SO http://stackoverflow.com/questions/ # Question $1 in StackOverflow 98 99 Transifex https://www.transifex.com/projects/p/trac/ 100 101 kwquery /query?group=status&keywords=~ # Custom query for tickets matching keyword $1 47 102 48 103 # … … 55 110 DebianBug http://bugs.debian.org/ 56 111 DebianPackage http://packages.debian.org/ 112 DebianPTS http://packages.qa.debian.org/ 57 113 Dictionary http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query= 58 114 Google http://www.google.com/search?q= 115 lmgtfy http://lmgtfy.com/?q= # Well, just search for "$1", follow the link to see how to do it... 59 116 GoogleGroups http://groups.google.com/group/$1/msg/$2 # Message $2 in $1 Google Group 117 gdiscussion https://groups.google.com/d/topic/$1/$2/discussion # Discussion $2 in $1 Google 118 gmessage https://groups.google.com/d/msg/$1/$2 # Message $2 in $1 Google Group 119 gforum https://groups.google.com/forum/#!forum/$1 # Forum $1 in Google Groups 60 120 JargonFile http://downlode.org/perl/jargon-redirect.cgi?term= 61 121 MeatBall http://www.usemod.com/cgi-bin/mb.pl? 62 122 MetaWiki http://sunir.org/apps/meta.pl? 63 123 MetaWikiPedia http://meta.wikipedia.org/wiki/ 64 MoinMoin http://moinmoin.wikiwikiweb.de/ 124 MoinMoin http://moinmo.in/ 125 TracHacks http://trac-hacks.org/wiki/ 126 OSM http://www.openstreetmap.org/wiki/ 65 127 WhoIs http://www.whois.sc/ 66 128 Why http://clublet.com/c/c/why? 67 c2Wiki 129 c2Wiki http://c2.com/cgi/wiki? 68 130 WikiPedia http://en.wikipedia.org/wiki/ 69 131 }}} 132 133 134 ---- 135 See also: InterWiki, InterTrac -
wiki/pages/InterTrac
r26484 r37343 1 = InterTrac Links =1 = InterTrac Links 2 2 3 Trac supports a convenient way to refer to resources of other Trac servers, from within the Wiki markup , since version 0.10.3 Trac supports a convenient way to refer to resources of other Trac servers, from within the Wiki markup. An !InterTrac link can be seen as a scoped TracLinks. It is used for referring to a Trac resource located in another Trac environment. A resource can be a wiki page, changeset, ticket or milestone. 4 4 5 == Definitions == 6 7 An InterTrac link can be seen as a scoped TracLinks. 8 It is used for referring to a Trac resource 9 (Wiki page, changeset, ticket, ...) located in another 10 Trac environment. 11 12 == List of Active InterTrac Prefixes == 5 == List of Active InterTrac Prefixes 13 6 14 7 [[InterTrac]] 15 8 16 == Link Syntax ==9 == Link Syntax 17 10 18 Simply use the name of the other Trac environment as a prefix, 19 followed by a colon, ending with the resource located in the other environment. 11 Simply use the name of the other Trac environment as a prefix, followed by a colon, ending with the resource located in the other environment. 20 12 21 13 {{{ … … 25 17 The other resource is specified using a regular TracLinks, of any flavor. 26 18 27 That target environment name is either the real name of the 28 environment, or an alias for it. 19 That target environment name is either the real name of the environment or an alias for it. 29 20 The aliases are defined in `trac.ini` (see below). 30 21 The prefix is case insensitive. 31 22 32 If the InterTrac link is enclosed in square brackets (like `[th:WikiExtrasPlugin]`), the InterTrac prefix is removed in the displayed link , like a normal link resolver would be (i.e. the above would be displayed as `WikiExtrasPlugin`).23 If the InterTrac link is enclosed in square brackets (like `[th:WikiExtrasPlugin]`), the InterTrac prefix is removed in the displayed link like a normal link resolver would be, ie the above would be displayed as `WikiExtrasPlugin`. 33 24 34 For convenience, there's also some alternative short-hand form, 35 where one can use an alias as an immediate prefix 36 for the identifier of a ticket, changeset or report: 37 (e.g. `#T234`, `[T1508]`, `[trac 1508]`, ...) 25 For convenience, there's also some alternative short-hand form, where one can use an alias as an immediate prefix for the identifier of a ticket, changeset or report, eg `#T234`, `[T1508]`, `[trac 1508]`. 38 26 39 == Examples ==27 == Examples 40 28 41 29 It is necessary to setup a configuration for the InterTrac facility. … … 43 31 44 32 Example configuration: 45 {{{ 46 ... 33 {{{#!ini 47 34 [intertrac] 48 35 # -- Example of setting up an alias: … … 55 42 56 43 The `.url` is mandatory and is used for locating the other Trac. 57 This can be a relative URL in case that Trac environment is located 58 on the same server. 44 This can be a relative URL in case that Trac environment is located on the same server. 59 45 60 The `.title` information will be used for providing an useful tooltip 61 when moving the cursor over an InterTrac links. 62 63 Finally, the `.compat` option can be used to activate or disable 64 a ''compatibility'' mode: 65 * If the targeted Trac is running a version below [trac:milestone:0.10 0.10] 66 ([trac:r3526 r3526] to be precise), then it doesn't know how to dispatch an InterTrac 67 link, and it's up to the local Trac to prepare the correct link. 68 Not all links will work that way, but the most common do. 69 This is called the compatibility mode, and is `true` by default. 70 * If you know that the remote Trac knows how to dispatch InterTrac links, 71 you can explicitly disable this compatibility mode and then ''any'' 72 TracLinks can become an InterTrac link. 46 The `.title` information will be used for providing an useful tooltip when moving the cursor over an InterTrac links. 73 47 74 48 Now, given the above configuration, one could create the following links: … … 84 58 * `trac:changeset:1912` trac:changeset:1912 85 59 * `[T1912]` [T1912] 86 * to the log range [3300:3330]: '''(Note: the following ones need `trac.compat=false`)'''60 * to the log range [3300:3330]: 87 61 * `trac:log:@3300:3330` trac:log:@3300:3330 88 * `[trac 3300:3330]` [trac 3300:3330] 89 * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (''since 0.11; note that the ''remote'' Trac has to run0.11 for this to work'')62 * `[trac 3300:3330]` [trac 3300:3330] 63 * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (note that the ''remote'' Trac has to run Trac >= 0.11 for this to work'') 90 64 91 The generic form `intertrac_prefix:module:id` is translated 92 to the corresponding URL `<remote>/module/id`, shorthand links 93 are specific to some modules (e.g. !#T234 is processed by the 94 ticket module) and for the rest (`intertrac_prefix:something`), 95 we rely on the TracSearch#quickjump facility of the remote Trac. 65 The generic form `intertrac_prefix:module:id` is translated to the corresponding URL `<remote>/module/id`, shorthand links are specific to some modules (e.g. !#T234 is processed by the ticket module) and for the rest (`intertrac_prefix:something`), we rely on the TracSearch#quickjump facility of the remote Trac. 96 66 97 67 ---- -
wiki/pages/InterWiki
r26484 r37343 1 = Support for InterWiki links =1 = Support for InterWiki links 2 2 3 ''(since [trac:milestone:0.10 0.10])'' 3 == Definition 4 4 5 == Definition == 5 An InterWiki link can be used for referring to a Wiki page located in another Wiki system, and by extension, to any object located in any other Web application, provided a simple URL mapping can be done. 6 6 7 An InterWiki link can be used for referring to a Wiki page 8 located in another Wiki system, and by extension, to any object 9 located in any other Web application, provided a simple URL 10 mapping can be done. 7 At the extreme, InterWiki prefixes can even be used to simply introduce links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn]. 11 8 12 At the extreme, InterWiki prefixes can even be used to simply introduce 13 links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn]. 14 15 == Link Syntax == 9 == Link Syntax 16 10 17 11 {{{ … … 19 13 }}} 20 14 21 The link is composed by the targeted Wiki (or system) name, 22 followed by a colon (e.g. `MeatBall:`), 23 followed by a page specification in the target. 15 The link is composed by the targeted Wiki (or system) name, followed by a colon, eg `MeatBall:`, followed by a page specification in the target. 24 16 Note that, as for InterTrac prefixes, '''InterWiki prefixes are case insensitive'''. 25 17 26 18 The target Wiki URL is looked up in the `[interwiki]` section of TracIni or in the InterMapTxt wiki page, modeled after MeatBall:InterMapTxt. If a prefix is defined in both the `[interwiki]` section and InterMapTxt, the `[interwiki]` section takes precedence. 27 19 28 In addition to traditional InterWiki links, where the target 29 is simply ''appended'' to the URL, 30 Trac supports parametric InterWiki URLs: 31 identifiers `$1`, `$2`, ... in the URL 32 will be replaced by corresponding arguments. 33 The argument list is formed by splitting the page identifier 34 using the ":" separator. 20 In addition to traditional InterWiki links, where the target is simply ''appended'' to the URL, Trac supports parametric InterWiki URLs: 21 identifiers `$1`, `$2`, ... in the URL will be replaced by corresponding arguments. 22 The argument list is formed by splitting the page identifier using the ":" separator. 35 23 36 === [interwiki] === 24 === [interwiki] 25 37 26 Every option in the `[interwiki]` section in TracIni defines one InterWiki prefix. The option name defines the prefix. The option value defines the URL, optionally followed by a description separated from the URL by whitespace. Parametric URLs are supported as well. 38 27 … … 45 34 }}} 46 35 47 == Examples ==36 == Examples 48 37 49 38 If the following is an excerpt of the InterMapTxt page: … … 73 62 74 63 Then, 75 * `MoinMoin:InterWikiMap` should be rendered as MoinMoin:InterWikiMap 76 and the ''title'' for that link would be "!InterWikiMap in !MoinMoin" 77 * `Trac-ML:4346` should be rendered as Trac-ML:4346 78 and the ''title'' for that link would be "Message 4346 in Trac Mailing List" 64 * `MoinMoin:InterWikiMap` should be rendered as MoinMoin:InterWikiMap and the ''title'' for that link would be "!InterWikiMap in !MoinMoin" 65 * `Trac-ML:4346` should be rendered as Trac-ML:4346 and the ''title'' for that link would be "Message 4346 in Trac Mailing List" 79 66 80 67 ---- -
wiki/pages/PageTemplates
r26484 r37343 1 = Wiki Page Templates = 2 3 ''(since [http://trac.edgewall.org/milestone/0.11 0.11])'' 1 = Wiki Page Templates 4 2 5 3 The default content for a new wiki page can be chosen from a list of page templates. 6 4 7 5 That list is generated from all the wiki pages having a name starting with ''PageTemplates/''. 8 The initial content of a new page will simply be the content of the chosen template page, or a blank page if the special ''(blank page)'' entry is selected. When there are no wiki pages with the ''PageTemplates/'' prefix, the initial content will always be the blank page and the list selector will not be shown (i.e. this matches the behavior we had up to now).6 The initial content of a new page will simply be the content of the chosen template page, or a blank page if the special ''(blank page)'' entry is selected. When there are no wiki pages with the ''PageTemplates/'' prefix, the initial content will always be the blank page and the list selector will not be shown, ie this matches the behavior we had up to now. 9 7 10 8 To create a new template, simply create a new page having a name starting with ''PageTemplates/''. 11 9 12 (Hint: one could even create a ''!PageTemplates/Template'' for facilitating the creation of new templates!) 10 Hint: one could even create a ''!PageTemplates/Template'' for facilitating the creation of new templates! 13 11 14 After the first template has been created, a drop-down selection box will automatically appear on any new wiki pages that are created. 12 After the first template has been created, a drop-down selection box will automatically appear on any new wiki pages that are created. By default it is located on the right side of the 'Create this page' button. The default selection will be ''blank page'', or ''!DefaultPage'' if ''!PageTemplates/DefaultPage'' exists. 15 13 16 14 Available templates: 17 15 [[TitleIndex(PageTemplates/)]] 16 18 17 ---- 19 18 See also: TracWiki -
wiki/pages/TracAccessibility
r26484 r37343 1 1 = Accessibility Support in Trac = 2 2 3 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 Trac, we work to assure users may interact with devices other than a pointing device.3 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. 4 4 5 The keyboard shortcuts must be enabled for a session through the [/prefs/keybindings Keyboard Shortcuts] preferences panel. 6 7 Trac supports accessibility keys for the most common operations. 8 - on Linux platforms, press any of the keys listed below in combination with the `<Alt>` key 9 - on a Mac, use the `<ctrl>` key instead 10 - on Windows, you need to hit `<Shift> + <Alt> + <Key>`. This works for most browsers (Firefox, Chrome, Safari and Internet Explorer) 5 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. 6 - on Linux platforms, press any of the keys listed below in combination with the `<Alt>` key 7 - on a Mac, use the `<Ctrl>` + `<Opt>` key instead 8 - on Windows, you need to hit `<Shift> + <Alt> + <Key>`. This works for the most common browsers, such as Firefox, Chrome, Safari and Internet Explorer 11 9 12 10 == Global Access Keys == 13 11 14 12 * `1` - WikiStart 15 * `2` - [ wiki:TracTimeline Timeline]16 * `3` - [ wiki:TracRoadmap Roadmap]17 * `4` - [ wiki:TracSearch Search]18 * `6` - [ wiki:TracGuide Trac Guide / Documentation]19 * `7` - [ wiki:TracTickets New Ticket]13 * `2` - [TracTimeline Timeline] 14 * `3` - [TracRoadmap Roadmap] 15 * `4` - [TracSearch Search] 16 * `6` - [TracGuide Trac Guide / Documentation] 17 * `7` - [TracTickets New Ticket] 20 18 * `9` - [/about About Trac] 21 * ` 0` - This page22 * ` e` - Edit this page19 * `e` - Edit (wiki or report) 20 * `r` - Preview (wiki or ticket) 23 21 * `f` - Search 24 22 -
wiki/pages/TracAdmin
r26484 r37343 1 = TracAdmin = 1 = TracAdmin 2 3 [[PageOutline(2-5, Contents, floated)]] 2 4 [[TracGuideToc]] 3 5 4 6 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. 5 7 6 Some of those operations can also be performed via the ''Admin'' web interface, an updated version of the [trac:WebAdmin] plugin now integrated within Trac (since version 0.11).8 Some of those operations can also be performed via the web administration module. 7 9 8 == Usage ==10 == Usage 9 11 10 12 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: … … 33 35 [[TracAdminHelp(initenv)]] 34 36 35 It supports an extra `--inherit` option, which can be used to specify a global configuration file which can be used 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.37 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. 36 38 See TracIni#GlobalConfiguration. 37 39 38 40 Note that in version 0.11 of Trac, `initenv` lost an extra last argument `<templatepath>`, 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 <projectname> <db> <repostype> <repospath>`' 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. 39 41 40 == Interactive Mode ==42 == Interactive Mode 41 43 42 44 When passing the environment path as the only argument, `trac-admin` starts in interactive mode. … … 56 58 }}} 57 59 58 == Full Command Reference ==60 == Full Command Reference 59 61 60 62 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 <yourenv> 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. -
wiki/pages/TracBackup
r26484 r37343 1 = Trac Backup = 1 = Trac Backup 2 2 3 [[TracGuideToc]] 3 4 4 Since Trac uses a database backend, some extra care is required to safely create a backup of a [wiki:TracEnvironment project environment]. Luckily, [wiki:TracAdmin trac-admin] has a command to make backups easier: `hotcopy`.5 Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the database. Backups can be created using the `hotcopy` command in [wiki:TracAdmin trac-admin]. 5 6 6 ''Note: Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.'' 7 '''Note''': Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers. 7 8 8 == Creating a Backup ==9 == Creating a Backup 9 10 10 To create a backup of a live TracEnvironment, simply run: 11 {{{ 12 13 $ trac-admin /path/to/projenv hotcopy /path/to/backupdir 14 11 To create a backup of a live TracEnvironment simply run: 12 {{{#!sh 13 $ trac-admin /path/to/projenv hotcopy /path/to/backupdir 15 14 }}} 16 15 17 [wiki:TracAdmin trac-admin] will lock the database while copying. ''16 [wiki:TracAdmin trac-admin] will lock the database while copying. 18 17 19 18 The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`. 20 19 21 Please , note, that hotcopy command does not overwrite target directory and when such exists, hotcopy ends witherror: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198].20 Please note, the `hotcopy` command will not overwrite a target directory and when such exists, the operation ends with an error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:ticket:3198 #3198]. 22 21 23 === Restoring a Backup ===22 === Restoring a Backup 24 23 25 Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the SQLite database. 24 To restore an environment from a backup, stop the process running Trac, ie the Web server or [wiki:TracStandalone tracd], restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service. 26 25 27 To restore an environment from a backup, stop the process running Trac (i.e. the Web server or [wiki:TracStandalone tracd]), restore the contents of your backup (path/to/backupdir) to your [wiki:TracEnvironment project environment] directory and restart the service. 26 To restore a PostgreSQL database backup, use the command: 27 {{{#!sh 28 psql -U <user> -d <database> -f postgresql.dump 29 }}} 30 The `<database>` option is the same as the [TracEnvironment#DatabaseConnectionStrings database connection string] in the `[trac]` `database` option of //trac.ini//. 28 31 29 32 ---- -
wiki/pages/TracBatchModify
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 From [wiki:TracQuery custom query] results Trac provides support for modifying a batch of tickets in one request.4 Trac supports modifying a batch of tickets in one request from [TracQuery custom query] results . 5 5 6 To perform a batch modification select the tickets you wish to modify and set the new field values using the section underneath the query results.6 To perform a batch modification, select the tickets you wish to modify and set the new field values using the section underneath the query results. 7 7 8 8 == List fields 9 9 10 The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed in addition of replacing the entire list value. All list field controls accept multiple items (i.e. multiple keywords or cc addresses). 10 The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed in addition of replacing the entire list value. All list field controls accept multiple items, such as multiple keywords or cc addresses. 11 12 == Excluded fields 13 14 Multi-line text fields are not supported, because no valid use-case has been presented for syncing them across several tickets. That restriction applies to the `Description` field as well as to any [TracTicketsCustomFields#AvailableFieldTypesandOptions custom field] of type 'textarea'. However, future versions of Trac could support in conjunction with more suitable actions like 'prepend', 'append' or 'search & replace' ([http://trac-hacks.org/ticket/2415 th:#2415]). -
wiki/pages/TracBrowser
r26484 r37343 1 = The Trac Repository Browser = 1 = The Trac Repository Browser 2 2 3 [[TracGuideToc]] 3 4 4 The Trac repository browser can be used to browse specific revisions of directories 5 and files stored in the repositories associated with the Trac environment. 5 The Trac repository browser can be used to browse specific revisions of directories and files stored in the repositories associated with the Trac environment. 6 6 7 ''(since 0.12)'': 8 At the top-level of the repository browser is the '''Repository Index''', 9 listing all the configured repositories. 10 Each repository has a name which is used as a path prefix in a 11 "virtual" file hierarchy encompassing all the available repositories. 12 One of the repositories can be configured with an empty name; this is the default repository. When such a default repository is present, its top-level files and directories 13 are also listed, in a '''Default Repository''' section placed before the 14 repository index. If the default repository is the only repository associated 15 with the Trac environment the '''Repository Index''' will be omitted ^[#note-multirepos (1)]^. 7 At the top-level of the repository browser is the '''Repository Index''', listing all the configured repositories. 8 Each repository has a name which is used as a path prefix in a "virtual" file hierarchy encompassing all the available repositories. 9 One of the repositories can be configured with an empty name; this is the default repository. When such a default repository is present, its top-level files and directories are also listed, in a '''Default Repository''' section placed before the repository index. If the default repository is the only repository associated with the Trac environment, then the '''Repository Index''' will be omitted. This means that after upgrading a single-repository Trac of version 0.11 (or earlier) to a multi-repository Trac (0.12), the repository browser will look and feel the same, that single repository becoming automatically the "default" repository. 16 10 17 Directory entries are displayed in a list with sortable columns. The list 18 entries can be sorted by ''Name'', ''Size'', ''Age'' or ''Author'' by clicking on the column 19 headers. The sort order can be reversed by clicking on a given column 20 header again. 11 Directory entries are displayed in a list with sortable columns. The list entries can be sorted by ''Name'', ''Size'', ''Age'' or ''Author'' by clicking on the column headers. The sort order can be reversed by clicking on a given column header again. 21 12 22 The browser can be used to navigate through the directory structure 23 by clicking on the directory names. 13 The browser can be used to navigate through the directory structure by clicking on the directory names. 24 14 Clicking on a file name will show the contents of the file. 25 Clicking on the revision number of a file or directory will take 26 you to the TracRevisionLog for that file. 27 Note that there's also a ''Revision Log'' navigation link that will do the 28 same for the path currently being examined. 29 Clicking on the ''diff'' icon after revision number will display the changes made 30 to the files modified in that revision. 15 Clicking on the revision number of a file or directory will take you to the TracRevisionLog for that file. 16 Note that there's also a ''Revision Log'' navigation link that will do the same for the path currently being examined. 17 Clicking on the ''diff'' icon after revision number will display the changes made to the files modified in that revision. 31 18 Clicking on the ''Age'' of the file - will take you to that changeset in the timeline. 32 19 33 It's also possible to browse directories or files as they were in history, 34 at any given repository revision. The default behavior is to display the 35 latest revision but another revision number can easily be selected using 36 the ''View revision'' input field at the top of the page. 20 It's also possible to browse directories or files as they were in history, at any given repository revision. The default behavior is to display the latest revision but another revision number can easily be selected using the ''View revision'' input field at the top of the page. 37 21 38 The color bar next to the ''Age'' column gives a visual indication of the age 39 of the last change to a file or directory, following the convention that 40 '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]''' 41 is newest, but this can be [TracIni#browser-section configured]. 22 The color bar next to the ''Age'' column gives a visual indication of the age of the last change to a file or directory, following the convention that '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]''' is newest, but this can be [TracIni#browser-section configured]. 42 23 43 At the top of the browser page, there's a ''Visit'' drop-down menu which you can use 44 to select some interesting places in the repository, for example branches or tags. 24 At the top of the browser page, there's a ''Visit'' drop-down menu which you can use to select some interesting places in the repository, for example branches or tags. 45 25 This is sometimes referred to as the ''browser quickjump'' facility. 46 26 The precise meaning and content of this menu depends on your repository backend. 47 For Subversion, this list contains by default the top-level trunk directory 48 and sub-directories of the top-level branches and tags directories 49 (`/trunk`, `/branches/*`, and `/tags/*`). This can be [TracIni#svn-section configured] 50 for more advanced cases. 27 For Subversion, this list contains by default the top-level trunk directory and sub-directories of the top-level branches and tags directories (`/trunk`, `/branches/*`, and `/tags/*`). This can be [TracIni#svn-section configured] for more advanced cases. 51 28 52 If you're using a Javascript enabled browser, you'll be able to expand and 53 collapse directories in-place by clicking on the arrow head at the right side of a 54 directory. Alternatively, the [trac:TracKeys keyboard] can also be used for this: 55 - use `'j'` and `'k'` to select the next or previous entry, starting with the first 56 - `'o'` (open) to toggle between expanded and collapsed state of the selected 29 If you're using a Javascript enabled browser, you'll be able to expand and collapse directories in-place by clicking on the arrow head at the right side of a directory. Alternatively, the [trac:TracKeys keyboard] can also be used for this: 30 - use `j` and `k` to select the next or previous entry, starting with the first 31 - `o` ('''o'''pen) to toggle between expanded and collapsed state of the selected 57 32 directory or for visiting the selected file 58 - `'v'` (view, visit) and `'<Enter>'`, same as above 59 - `'r'` can be used to force the reload of an already expanded directory 60 - `'A'` can be used to directly visit a file in annotate (blame) mode 61 - `'L'` to view the log for the selected entry 62 If no row has been selected using `'j'` or `'k'` these keys will operate on the entry under the mouse. 63 64 {{{#!comment 65 MMM: I guess that some keys are upper case and some lower to avoid conflicts with browser defined keys. 66 I find for example in Firefox and IE on windows that 'a' works as well as 'A' but 'l' does not work for 'L'. 67 cboos: 'l' is reserved for Vim like behavior, see #7867 68 }}} 33 - `v` ('''v'''iew, '''v'''isit) and `<Enter>`, same as above 34 - `r` can be used to force the '''r'''eload of an already expanded directory 35 - `a` can be used to directly visit a file in '''a'''nnotate (blame) mode 36 - `l` to view the '''l'''og for the selected entry 37 If no row has been selected using `j` or `k` these keys will operate on the entry under the mouse. 69 38 70 39 For the Subversion backend, some advanced additional features are available: 71 - The `svn:needs-lock` property will be displayed 72 - Support for the `svn:mergeinfo` property showing the merged and eligible information 73 - Support for browsing the `svn:externals` property 74 (which can be [TracIni#svn:externals-section configured]) 75 - The `svn:mime-type` property is used to select the syntax highlighter for rendering 76 the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is 77 highlighted as HTML, regardless of the file extension. It also allows selecting the character 78 encoding used in the file content. For example, if the file content is encoded in UTF-8, 79 set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the 80 default encoding defined in the `default_charset` option of the `[trac]` section 81 of [TracIni#trac-section trac.ini]. 40 - The `svn:needs-lock` property will be displayed. 41 - Support for the `svn:mergeinfo` property showing the merged and eligible information. 42 - Support for browsing the `svn:externals` property, which can be [TracIni#svn:externals-section configured]. 43 - The `svn:mime-type` property is used to select the syntax highlighter for rendering the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is highlighted as HTML, regardless of the file extension. It also allows selecting the character encoding used in the file content. For example, if the file content is encoded in UTF-8, set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the default encoding defined in the `default_charset` option of the `[trac]` section of [TracIni#trac-section trac.ini]. 82 44 {{{#!comment 83 45 MMM: I found this section a bit hard to understand. I changed the first item as I understood that well. … … 86 48 }}} 87 49 88 89 50 ---- 90 {{{#!div style="font-size:85%"91 [=#note-multirepos (1)] This means that after upgrading a single-repository Trac of version92 0.11 (or below) to a multi-repository Trac (0.12), the repository browser will look and feel93 the same, that single repository becoming automatically the "default" repository.94 }}}95 96 51 See also: TracGuide, TracChangeset, TracFineGrainedPermissions -
wiki/pages/TracCgi
r26484 r37343 1 = Installing Trac as CGI = 1 = Installing Trac as CGI 2 [[TracGuideToc]] 3 [[PageOutline]] 2 4 3 {{{ 4 #!div class=important 5 ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.'' 5 {{{#!div class=important 6 ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.'' 6 7 }}} 7 8 8 CGI script is the entrypoint that web-server calls when a web-request to an application is made. To generate the `trac.cgi` script run: 9 {{{ 10 trac-admin /path/to/env deploy /path/to/www/trac 11 }}} 12 `trac.cgi` will be in the `cgi-bin` folder inside the given path. ''Make sure it is executable by your web server''. This command also copies `static resource` files to a `htdocs` directory of a given destination. 9 CGI script is the entrypoint that web-server calls when a web-request to an application is made. The `trac.cgi` script can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. Make sure the script is executable by your web server. 13 10 14 == Apache web-server configuration ==11 == Apache web-server configuration 15 12 16 13 In [http://httpd.apache.org/ Apache] there are two ways to run Trac as CGI: 17 14 18 15 1. Use a `ScriptAlias` directive that maps an URL to the `trac.cgi` script (recommended) 19 2. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.16 1. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory. 20 17 21 18 To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation: 22 {{{ 19 {{{#!apache 23 20 ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi 24 21 }}} … … 27 24 28 25 If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable: 29 {{{ 26 {{{#!apache 30 27 <Location "/trac"> 31 28 SetEnv TRAC_ENV "/path/to/projectenv" … … 34 31 35 32 Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable: 36 {{{ 33 {{{#!apache 37 34 <Location "/trac"> 38 35 SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir" … … 42 39 ''Note that the `SetEnv` directive requires enabled `mod_env` module. It is also possible to set TRAC_ENV in trac.cgi. Just add the following code between "try:" and "from trac.web ...":'' 43 40 44 {{{ 41 {{{#!python 45 42 import os 46 43 os.environ['TRAC_ENV'] = "/path/to/projectenv" … … 49 46 '' Or for TRAC_ENV_PARENT_DIR: '' 50 47 51 {{{ 48 {{{#!python 52 49 import os 53 50 os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir" 54 51 }}} 55 52 56 If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [ http://trac.edgewall.org/wiki/ApacheSuexec].53 If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [trac:ApacheSuexec]. 57 54 58 55 On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI). 59 56 60 === Using WSGI ===57 === Using WSGI 61 58 62 59 You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [http://pythonweb.org/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI]. You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application. 63 60 64 == Mapping Static Resources ==61 == Mapping Static Resources 65 62 66 63 See TracInstall#MappingStaticResources. 67 64 68 == Adding Authentication ==65 == Adding Authentication 69 66 70 67 See TracInstall#ConfiguringAuthentication. -
wiki/pages/TracChangeset
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 Trac has a built-in functionality for visualizing “diffs” -changes to files.4 Trac has a built-in functionality for visualizing “diffs”, or changes to files. 5 5 6 There are different kinds of ''change sets''. 7 Some can correspond to revisions made in the repositories, 8 others can aggregate changes made in several revisions, 9 but in the end, any kind of differences can be shown. 6 There are different kinds of ''change sets''. Some correspond to revisions made in the repositories, others aggregate changes made in several revisions. Ultimately, any kind of difference can be shown. 10 7 11 The changeset view consists of two parts, the ''header'' 12 and the ''diff views''. 8 The changeset view consists of two parts, the ''header'' and the ''diff views''. 13 9 14 10 == Changeset Header == … … 23 19 * Files — A list of files affected by this changeset 24 20 25 If more than one revision is involved in the set of changes being 26 displayed, the ''Timestamp'', ''Author'' and ''Message'' fields 27 won't be shown. 21 If more than one revision is involved in the set of changes being displayed, the ''Timestamp'', ''Author'' and ''Message'' fields will not be shown. 28 22 29 In front of each listed file, you'll find a colored rectangle. The color 30 indicates how the file is affected by the changeset. 23 A colored rectangle indicates how the file is affected by the changeset: 31 24 32 25 [[span(style=background:#bfb;border:1px solid #999;font-size:80%;margin-right:.5em,'' '')]] Green: Added \\ … … 39 32 == Diff Views == 40 33 41 Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which will contain only the regions of the file that are affected by the changeset. There are two different styles of displaying the diffs: ''inline'' or ''side-by-side'' (you can switch between those styles using the preferences form):34 Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which contains only the regions of the file that are affected by the changeset. There are two different styles to display the diffs: ''inline'' or ''side-by-side''. You can switch between the styles using the preferences form: 42 35 43 * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers on the left sideindicate the exact position of the change in both the old and the new version of the file.44 * The ''side-by-side'' style shows the old version on the left and the new version on the right (this will typically require more screen width than the inline style.) Added and removed regions will be colored in the same way as with the inline style (green and red, respectively), butmodified regions will have a yellow background.36 * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers indicate the exact position of the change in both the old and the new version of the file. 37 * The ''side-by-side'' style shows the old version on the left and the new version on the right and this will typically require more screen width than the inline style. Added and removed regions will be colored in the same way as with the inline style (green and red), and modified regions will have a yellow background. 45 38 46 39 In addition, various advanced options are available in the preferences form for adjusting the display of the diffs: 47 * You can set how many lines are displayed before and after every change 48 (if the value ''all'' is used, then the full file will be shown) 49 * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly 50 40 * You can set how many lines are displayed before and after every change; if the value ''all'' is used, then the full file will be shown. 41 * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly. 51 42 52 43 == The Different Ways to Get a Diff == … … 54 45 === Examining a Changeset === 55 46 56 When viewing a repository check-in, such as when following a 57 changeset [wiki:TracLinks link] or a changeset event in the 58 [wiki:TracTimeline timeline], Trac will display the exact changes 59 made by the check-in. 47 When viewing a repository check-in, such as when following a changeset [wiki:TracLinks link] or a changeset event in the [wiki:TracTimeline timeline], Trac will display the exact changes made by the check-in. 60 48 61 There will be also navigation links to the ''Previous Changeset'' 62 to and ''Next Changeset''. 49 There will be also navigation links to the ''Previous Changeset'' to and ''Next Changeset''. 63 50 64 51 === Examining Differences Between Revisions === 65 52 66 Often you'll want to look at changes made on a file 67 or on a directory spanning multiple revisions. The easiest way 68 to get there is from the TracRevisionLog, where you can select 69 the ''old'' and the ''new'' revisions of the file or directory, and 70 then click the ''View changes'' button. 53 Often you want to look at changes made on a file or on a directory spanning multiple revisions. The easiest way to get there is from the TracRevisionLog, where you can select the ''old'' and the ''new'' revisions of the file or directory, and then click the ''View changes'' button. 71 54 72 55 === Examining Differences Between Branches === 73 56 74 One of the core features of version control systems is the possibility 75 to work simultaneously on different ''Lines of Developments'', commonly 76 called “branches”. Trac enables you to examine the exact differences 77 between such branches. 57 One of the core features of version control systems is the possibility to work simultaneously on different ''Lines of Developments'', commonly called “branches”. Trac enables you to examine the exact differences between such branches. 78 58 79 Using the '''View changes ...''' button in the TracBrowser allows you to enter 80 ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist 81 of the changes that should be applied to the ''From:'' content in order 82 to get to the ''To:'' content. 59 Using the '''View changes ...''' button in the TracBrowser allows you to enter ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist of the changes that should be applied to the ''From:'' content to get to the ''To:'' content. 83 60 84 For convenience, it is possible to invert the roles of the ''old'' and the ''new'' 85 path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page. 61 For convenience, it is possible to invert the roles of the ''old'' and the ''new'' path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page. 86 62 87 63 === Checking the Last Change === 88 64 89 The last possibility for examining changes is to use the ''Last Change'' 90 link provided by the TracBrowser. 65 Another way to examine changes is to use the ''Last Change'' link provided by the TracBrowser. 91 66 92 This link will take you to the last change that was made on that path. 93 From there, you can use the ''Previous Change'' and ''Next Change'' links 94 to traverse the change history of the file or directory. 67 This link will take you to the last change that was made on that path. From there, you can use the ''Previous Change'' and ''Next Change'' links to traverse the change history of the file or directory. 95 68 96 69 ---- -
wiki/pages/TracEnvironment
r26484 r37343 1 = The Trac Environment =1 = The Trac Environment 2 2 3 Trac uses a directory structure and a database for storing project data. The directory is referred to as the “environment”. 3 [[TracGuideToc]] 4 [[PageOutline(2-5)]] 4 5 5 == Creating an Environment == 6 Trac uses a directory structure and a database for storing project data. The directory is referred to as the environment. 6 7 7 A new Trac environment is created using [TracAdmin#initenv trac-admin's initenv]: 8 {{{ 8 == Creating an Environment 9 10 A new Trac environment is created using [TracAdmin#initenv trac-admin's initenv]: 11 {{{#!sh 9 12 $ trac-admin /path/to/myproject initenv 10 13 }}} 11 14 12 `trac-admin` will ask you for the name of the project and the 13 database connection string (explained below). 15 `trac-admin` will ask you for the name of the project and the database connection string, see below. 14 16 15 === SomeUseful Tips16 - The user under which the web server runs will require file system write permission to 17 the environment directory and all the files inside. Please remember to set18 the appropriate permissions. The same applies to the source code repository, 19 although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation.17 === Useful Tips 18 19 - Place your environment's directory on a filesystem which supports sub-second timestamps, as Trac monitors the timestamp of its configuration files and changes happening on a filesystem with too coarse-grained timestamp resolution may go undetected in Trac < 1.0.2. This is also true for the location of authentication files when using TracStandalone. 20 21 - The user under which the web server runs will require file system write permission to the environment directory and all the files inside. Please remember to set the appropriate permissions. The same applies to the source code repository, although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation. 20 22 21 - `initenv`, when using an svn repository, does not imply that trac-admin will perform `svnadmin create` for the specified repository path. You need to perform the `svnadmin create` prior to `trac-admin initenv` if you're creating a new svn repository altogether with a new trac environment,otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment.23 - `initenv`, when using an svn repository, does not imply that trac-admin will perform `svnadmin create` for the specified repository path. You need to perform the `svnadmin create` prior to `trac-admin initenv` if you're creating a new svn repository altogether with a new Trac environment; otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment. 22 24 23 - Non-ascii environment paths are not supported 25 - Non-ascii environment paths are not supported. 24 26 25 - Also, it seems that project names with spaces can be problematic for authentication (see [trac:#7163]).27 - Also, it seems that project names with spaces can be problematic for authentication, see [trac:#7163]. 26 28 27 29 - TracPlugins located in a [TracIni#inherit-section shared plugins folder] that is defined in an [TracIni#GlobalConfiguration inherited configuration] are currently not loaded during creation, and hence, if they need to create extra tables for example, you'll need to [TracUpgrade#UpgradetheTracEnvironment upgrade the environment] before being able to use it. 28 30 29 == Database Connection Strings == 31 {{{#!div style="border: 1pt dotted; margin: 1em" 32 **Caveat:** don't confuse the //Trac environment directory// with the //source code repository directory//. 30 33 31 Since version 0.9, Trac supports both [http://sqlite.org/ SQLite] and 32 [http://www.postgresql.org/ PostgreSQL] database backends. Preliminary 33 support for [http://mysql.com/ MySQL] was added in 0.10. The default is 34 to use SQLite, which is probably sufficient for most projects. The database 35 file is then stored in the environment directory, and can easily be 36 [wiki:TracBackup backed up] together with the rest of the environment. 34 This is a common beginners' mistake. 35 It happens that the structure for a Trac environment is loosely modeled after the Subversion repository directory structure, but those are two disjoint entities and they are not and //must not// be located at the same place. 36 }}} 37 37 38 === SQLite Connection String === 38 == Database Connection Strings 39 40 Trac supports [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL] and [http://mysql.com/ MySQL] database backends. The default is SQLite, which is probably sufficient for most projects. The database file is then stored in the environment directory, and can easily be [wiki:TracBackup backed up] together with the rest of the environment. 41 42 Note that if the username or password of the connection string (if applicable) contains the `:`, `/` or `@` characters, they need to be URL encoded. 43 44 === SQLite Connection String 45 39 46 The connection string for an SQLite database is: 40 47 {{{ … … 43 50 where `db/trac.db` is the path to the database file within the Trac environment. 44 51 45 === PostgreSQL Connection String === 46 If you want to use PostgreSQL or MySQL instead, you'll have to use a 47 different connection string. For example, to connect to a PostgreSQL 48 database on the same machine called `trac`, that allows access to the 49 user `johndoe` with the password `letmein`, use: 52 === PostgreSQL Connection String 53 54 If you want to use PostgreSQL instead, you'll have to use a different connection string. For example, to connect to a PostgreSQL database on the same machine called `trac` for user `johndoe` with the password `letmein` use: 50 55 {{{ 51 56 postgres://johndoe:letmein@localhost/trac 52 57 }}} 53 ''Note that due to the way the above string is parsed, the "/" and "@" characters cannot be part of the password.''54 58 55 If PostgreSQL is running on a non-standard port (for example 9342), use:59 If PostgreSQL is running on a non-standard port, for example 9342, use: 56 60 {{{ 57 61 postgres://johndoe:letmein@localhost:9342/trac 58 62 }}} 59 63 60 On UNIX, you might want to select a UNIX socket for the transport, 61 either the default socket as defined by the PGHOST environment variable: 64 On UNIX, you might want to select a UNIX socket for the transport, either the default socket as defined by the PGHOST environment variable: 62 65 {{{ 63 66 postgres://user:password@/database 64 67 }}} 68 65 69 or a specific one: 66 70 {{{ … … 68 72 }}} 69 73 70 Note that with PostgreSQL you will have to create the database before running 71 `trac-admin initenv`. 74 Note that with PostgreSQL you will have to create the database before running `trac-admin initenv`. 72 75 73 76 See the [http://www.postgresql.org/docs/ PostgreSQL documentation] for detailed instructions on how to administer [http://postgresql.org PostgreSQL]. 74 Generally, the following is sufficient to create a database user named `tracuser`, and a database named `trac`. 75 {{{ 76 createuser -U postgres -E -P tracuser 77 createdb -U postgres -O tracuser -E UTF8 trac 78 }}} 79 When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command. Also note that the database should be created as UTF8. LATIN1 encoding causes errors trac's use of unicode in trac. SQL_ASCII also seems to work. 80 81 Under some default configurations (debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user. For example: 82 {{{ 83 sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser' 84 sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac' 77 Generally, the following is sufficient to create a database user named `tracuser` and a database named `trac`: 78 {{{#!sh 79 $ createuser -U postgres -E -P tracuser 80 $ createdb -U postgres -O tracuser -E UTF8 trac 85 81 }}} 86 82 87 Trac uses the `public` schema by default but you can specify a different schema in the connection string: 83 When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a Trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command. Also note that the database should be created as UTF8. LATIN1 encoding causes errors, because of Trac's use of unicode. SQL_ASCII also seems to work. 84 85 Under some default configurations (Debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user: 86 {{{#!sh 87 $ sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser' 88 $ sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac' 89 }}} 90 91 Trac uses the `public` schema by default, but you can specify a different schema in the connection string: 88 92 {{{ 89 93 postgres://user:pass@server/database?schema=yourschemaname 90 94 }}} 91 95 92 === MySQL Connection String ===96 === MySQL Connection String 93 97 94 If you want to use MySQL instead, you'll have to use a 95 different connection string. For example, to connect to a MySQL 96 database on the same machine called `trac`, that allows access to the 97 user `johndoe` with the password `letmein`, the mysql connection string is: 98 The format of the MySQL connection string is similar to those for PostgreSQL, with the `postgres` scheme being replaced by `mysql`. For example, to connect to a MySQL database on the same machine called `trac` for user `johndoe` with password `letmein`: 98 99 {{{ 99 100 mysql://johndoe:letmein@localhost:3306/trac 100 101 }}} 101 102 102 == Source Code Repository ==103 == Source Code Repository 103 104 104 Since version 0.12, a single Trac environment can be connected to more than one repository. There are many different ways to connect repositories to an environment, see TracRepositoryAdmin. This page also details the various attributes that can be set for a repository (like `type`, `url`, `description`).105 A single environment can be connected to more than one repository. However, by default Trac is not connected to any source code repository, and the ''Browse Source'' toolbar item will not be displayed. 105 106 106 In Trac 0.12 `trac-admin` no longer asks questions related to repositories. Therefore, by default Trac is not connected to any source code repository, and the ''Browse Source'' toolbar item will not be displayed. 107 You can also explicitly disable the `trac.versioncontrol.*` components (which are otherwise still loaded) 108 {{{ 109 [components] 110 trac.versioncontrol.* = disabled 111 }}} 107 There are many different ways to connect repositories to an environment, see TracRepositoryAdmin. A single repository can be specified when the environment is created by passing the optional arguments `repository_type` and `repository_dir` to the `initenv` command. 112 108 113 For some version control systems, it is possible to specify not only the path to the repository, 114 but also a ''scope'' within the repository. Trac will then only show information 115 related to the files and changesets below that scope. The Subversion backend for 116 Trac supports this; for other types, check the corresponding plugin's documentation. 117 118 Example of a configuration for a Subversion repository used as the default repository: 119 {{{ 120 [trac] 121 repository_type = svn 122 repository_dir = /path/to/your/repository 123 }}} 124 125 The configuration for a scoped Subversion repository would be: 126 {{{ 127 [trac] 128 repository_type = svn 129 repository_dir = /path/to/your/repository/scope/within/repos 130 }}} 131 132 == Directory Structure == 109 == Directory Structure 133 110 134 111 An environment directory will usually consist of the following files and directories: 135 112 136 113 * `README` - Brief description of the environment. 137 * `VERSION` - Contains the environment version identifier. 138 * `attachments` - Attachments to wiki pages and tickets are stored here. 114 * `VERSION` - Environment version identifier. 115 * `files` 116 * `attachments` - Attachments to wiki pages and tickets. 139 117 * `conf` 140 118 * `trac.ini` - Main configuration file. See TracIni. 141 119 * `db` 142 * `trac.db` - The SQLite database (if you're using SQLite). 143 * `htdocs` - directory containing web resources, which can be referenced in Genshi templates using `/htdocs/site/...` URLs. ''(since 0.11)'' 144 * `log` - default directory for log files, if logging is turned on and a relative path is given. 145 * `plugins` - Environment-specific [wiki:TracPlugins plugins] (Python eggs or single file plugins, since [trac:milestone:0.10 0.10]) 146 * `templates` - Custom Genshi environment-specific templates. ''(since 0.11)'' 147 * `site.html` - method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance 148 149 === Caveat: don't confuse a ''Trac environment directory'' with the ''source code repository directory'' #Caveat 150 151 This is a common beginners' mistake. 152 It happens that the structure for a Trac environment is loosely modelled after the Subversion repository directory 153 structure, but those are two disjoint entities and they are not and ''must not'' be located at the same place. 120 * `trac.db` - The SQLite database, if you are using SQLite. 121 * `htdocs` - Directory containing web resources, which can be referenced in Genshi templates using `/chrome/site/...` URLs. 122 * `log` - Default directory for log files, if `file` logging is enabled and a relative path is given. 123 * `plugins` - Environment-specific [wiki:TracPlugins plugins]. 124 * `templates` - Custom Genshi environment-specific templates. 125 * `site.html` - Method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance. 154 126 155 127 ---- -
wiki/pages/TracFastCgi
r26484 r37343 1 [[PageOutline]] 2 3 = Trac with FastCGI = 1 = Trac with FastCGI 2 3 [[TracGuideToc]] 4 [[PageOutline(2-5, Contents, floated)]] 4 5 5 6 [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. 6 7 7 Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i .e. run with different permissions than web server running with (`mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect).8 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. 8 9 9 10 '''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]. 10 11 11 [[PageOutline(2-3,Overview,inline)]] 12 13 14 == Simple Apache configuration == 12 == Simple Apache configuration 15 13 16 14 There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and … … 19 17 The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache. 20 18 21 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) 22 23 === Set up with `mod_fastcgi` === 19 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. 20 21 === Set up with `mod_fastcgi` 22 24 23 `mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file: 25 24 {{{ … … 48 47 }}} 49 48 50 === Set up with `mod_fcgid` ===51 Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` 52 instead of `trac.cgi`. Note that slash at the end - it is important. 49 === Set up with `mod_fcgid` 50 51 Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` instead of `trac.cgi`: 53 52 {{{ 54 53 ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/ 55 54 }}} 56 57 To set up Trac environment for `mod_fcgid` it is necessary to use 58 `DefaultInitEnv` directive. It cannot be used in `Directory` or 59 `Location` context, so if you need to support multiple projects, try 60 alternative environment setup below. 55 Note the slash at the end. 56 57 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. 61 58 62 59 {{{ … … 64 61 }}} 65 62 66 === alternative environment setup === 67 A better method to specify path to Trac environment is to embed the path 68 into `trac.fcgi` script itself. That doesn't require configuration of server 69 environment variables, works for both FastCgi modules 70 (and for [http://www.lighttpd.net/ lighttpd] and CGI as well): 63 === alternative environment setup 64 65 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: 71 66 {{{ 72 67 import os 73 68 os.environ['TRAC_ENV'] = "/path/to/projectenv" 74 69 }}} 75 or 70 or: 76 71 {{{ 77 72 import os … … 79 74 }}} 80 75 81 With this method different projects can be supported by using different 82 `.fcgi` scripts with different `ScriptAliases`. 76 With this method different projects can be supported by using different `.fcgi` scripts with different `ScriptAliases`. 83 77 84 78 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: … … 87 81 }}} 88 82 89 == Simple Cherokee Configuration ==83 == Simple Cherokee Configuration 90 84 91 85 The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process. 92 86 You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down. 93 First set up an information source in cherokee-admin with a local interpreter .87 First set up an information source in cherokee-admin with a local interpreter: 94 88 95 89 {{{ … … 113 107 }}} 114 108 115 116 == Simple Lighttpd Configuration == 117 118 The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd]. 119 120 lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance 121 environments. It has a very low memory footprint compared to other web servers and takes care of CPU load. 122 123 For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with lighttpd add the following to your lighttpd.conf: 109 == Simple Lighttpd Configuration 110 111 The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ Lighttpd]. 112 113 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. 114 115 For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with Lighttpd add the following to your lighttpd.conf: 124 116 {{{ 125 117 #var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory … … 138 130 }}} 139 131 140 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, 141 and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf` 142 using `bin-environment` (as in the section above on Apache configuration). 143 144 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. 132 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. 133 134 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. 145 135 146 136 For using two projects with lighttpd add the following to your `lighttpd.conf`: … … 166 156 ) 167 157 }}} 168 Note that field values are different. If you prefer setting the environment 169 variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, e.g., to 170 `first.fcgi` and `second.fcgi`, and reference them in the above settings. 171 Note that the above will result in different processes in any event, even 172 if both are running from the same `trac.fcgi` script. 158 159 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. 160 Note that the above will result in different processes in any event, even if both are running from the same `trac.fcgi` script. 173 161 174 162 {{{ … … 213 201 ) 214 202 215 216 }}} 217 Note that lighttpd (I use version 1.4.3) stopped if password file doesn't exist. 218 219 Note that lighttpd doesn't support 'valid-user' in versions prior to 1.3.16. 220 221 Conditional configuration is also useful for mapping static resources, i.e. serving out images and CSS directly instead of through FastCGI: 203 }}} 204 Note that Lighttpd (v1.4.3) stops if the password file doesn't exist. 205 206 Note that Lighttpd doesn't support 'valid-user' in versions prior to 1.3.16. 207 208 Conditional configuration is also useful for mapping static resources, ie serving out images and CSS directly instead of through FastCGI: 222 209 {{{ 223 210 # Aliasing functionality is needed … … 243 230 } 244 231 }}} 232 245 233 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. 246 234 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: … … 274 262 }}} 275 263 276 Changing date/time format also supported by lighttpd over environment variable LC_TIME 264 Changing date/time format also supported by lighttpd over environment variable LC_TIME: 277 265 {{{ 278 266 fastcgi.server = ("/trac" => … … 293 281 ] 294 282 295 Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac. 296 297 Note about running lighttpd with reduced permissions: 298 299 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. 300 301 302 == Simple !LiteSpeed Configuration == 283 Relaunch Lighttpd and browse to `http://yourhost.example.org/trac` to access Trac. 284 285 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. 286 287 == Simple !LiteSpeed Configuration 303 288 304 289 The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.litespeedtech.com/ LiteSpeed]. … … 306 291 !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. 307 292 308 1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first. 309 310 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: 311 293 1. Please make sure you have a working install of a Trac project. Test install with "tracd" first. 294 295 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: 312 296 {{{ 313 297 http://yourdomain.com/trac/ 314 298 }}} 315 299 316 3. Go “!TracVhost → External Apps” tab and create a new “External Application”. 317 300 3. Go "!TracVhost → External Apps" tab and create a new "External Application". 318 301 {{{ 319 302 Name: MyTracFCGI … … 332 315 }}} 333 316 334 4. Optional . If you need to use htpasswd based authentication. Go to “!TracVhost → Security” tab and create a new security “Realm”.317 4. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm. 335 318 336 319 {{{ … … 342 325 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. 343 326 344 5. Go to “!PythonVhost → Contexts” and create a new “FCGI Context”.327 5. Go to "!PythonVhost → Contexts" and create a new FCGI Context. 345 328 346 329 {{{ … … 365 348 }}} 366 349 367 368 == Simple Nginx Configuration == 350 == Simple Nginx Configuration 369 351 370 352 Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately. 371 353 372 354 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32 373 {{{355 {{{ 374 356 server { 375 357 listen 10.9.8.7:443; … … 386 368 ssl_prefer_server_ciphers on; 387 369 388 # (Or ``^/some/prefix/(.*)``.389 if ($uri ~ ^/(.*)) {390 set $path_info/$1;370 # it makes sense to serve static resources through Nginx (or ``~ [/some/prefix]/chrome/(.*)``) 371 location ~ /chrome/(.*) { 372 alias /home/trac/instance/static/htdocs/$1; 391 373 } 392 374 393 # it makes sense to serve static resources through Nginx 394 location /chrome/ { 395 alias /home/trac/instance/static/htdocs/; 396 } 397 398 # You can copy this whole location to ``location [/some/prefix]/login`` 375 # You can copy this whole location to ``location [/some/prefix](/login)`` 399 376 # and remove the auth entries below if you want Trac to enforce 400 377 # authorization where appropriate instead of needing to authenticate 401 378 # for accessing the whole site. 402 # (Or `` location /some/prefix``.)403 location /{379 # (Or ``~ location /some/prefix(/.*)``.) 380 location ~ (/.*) { 404 381 auth_basic "trac realm"; 405 382 auth_basic_user_file /home/trac/htpasswd; … … 415 392 # (Or ``fastcgi_param SCRIPT_NAME /some/prefix``.) 416 393 fastcgi_param SCRIPT_NAME ""; 417 fastcgi_param PATH_INFO $ path_info;394 fastcgi_param PATH_INFO $1; 418 395 419 396 ## WSGI NEEDED VARIABLES - trac warns about them … … 438 415 } 439 416 }}} 440 441 2. Modified trac.fcgi: 442 443 {{{ 417 1. Modified trac.fcgi: 418 {{{ 444 419 #!/usr/bin/env python 445 420 import os … … 472 447 473 448 }}} 474 475 3. reload nginx and launch trac.fcgi like that: 476 477 {{{ 449 1. reload nginx and launch trac.fcgi like that: 450 {{{#!sh 478 451 trac@trac.example ~ $ ./trac-standalone-fcgi.py 479 452 }}} 480 453 481 454 The above assumes that: 482 * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory .455 * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory 483 456 * `/home/trac/instance` contains a trac environment 484 457 * `/home/trac/htpasswd` contains authentication information … … 488 461 489 462 Unfortunately nginx does not support variable expansion in fastcgi_pass directive. 490 Thus it is not possible to serve multiple trac instances from one server block.491 492 If you worry enough about security, run trac instances under separate users.493 494 Another way to run trac as a FCGI external application is offered in ticket #T6224463 Thus it is not possible to serve multiple Trac instances from one server block. 464 465 If you worry enough about security, run Trac instances under separate users. 466 467 Another way to run Trac as a FCGI external application is offered in ticket #T6224 495 468 496 469 ---- -
wiki/pages/TracFineGrainedPermissions
r26484 r37343 1 = Fine grained permissions = 1 2 [[PageOutline(2-5, Contents, floated)]] 2 = Fine grained permissions = 3 4 Before Trac 0.11, it was only possible to define fine-grained permissions checks on the repository browser sub-system. 5 6 Since 0.11, there's a general mechanism in place that allows custom **permission policy plugins** to grant or deny any action on any kind of Trac resources, even at the level of specific versions of such resources. 7 8 Note that for Trac 0.12, `authz_policy` has been integrated as an optional module (in `tracopt.perm.authz_policy.*`), so it's installed by default and can simply be activated via the //Plugins// panel in the Trac administration module. 9 3 [[TracGuideToc]] 4 5 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. 6 7 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. 10 8 11 9 == Permission Policies == 12 10 13 A great diversity of permission policies can be implemented ,and Trac comes with a few examples.11 A great diversity of permission policies can be implemented and Trac comes with a few examples. 14 12 15 13 Which policies are currently active is determined by a configuration setting in TracIni: 16 e.g. 17 {{{ 18 [trac] 19 permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy20 }}} 21 This lists the [# AuthzSourcePolicy] described below as the first policy, followed by the !DefaultPermissionPolicy which checks for the traditional coarse grained style permissions described in TracPermissions, and the !LegacyAttachmentPolicy which knows how to use the coarse grained permissions for checking the permissions available on attachments.22 23 Among the possibleoptional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See24 [trac:source:branches/ 0.12-stable/tracopt/perm/authz_policy.py authz_policy.py] for details.14 15 {{{#!ini 16 [trac] 17 permission_policies = ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy 18 }}} 19 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. 20 21 Among the optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See 22 [trac:source:branches/1.0-stable/tracopt/perm/authz_policy.py authz_policy.py] for details. 25 23 26 24 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. 27 25 28 See also [trac:source:branches/0.12-stable/sample-plugins/permissions sample-plugins/permissions] for more examples. 29 26 See also [trac:source:branches/1.0-stable/sample-plugins/permissions sample-plugins/permissions] for more examples. 30 27 31 28 === !AuthzPolicy === 32 29 ==== Configuration ==== 33 * Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12).34 * Copy authz_policy.py into your plugins directory (only for Trac 0.11).35 30 * 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. 36 31 * Update your `trac.ini`: 37 1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section 38 {{{ 32 1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section: 33 {{{#!ini 39 34 [trac] 40 35 ... 41 permission_policies = AuthzPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy42 }}} 43 1. add a new `[authz_policy]` section 44 {{{ 36 permission_policies = AuthzPolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy 37 }}} 38 1. add a new `[authz_policy]` section: 39 {{{#!ini 45 40 [authz_policy] 46 41 authz_file = /some/trac/env/conf/authzpolicy.conf 47 42 }}} 48 1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section 49 {{{ 43 1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section: 44 {{{#!ini 50 45 [components] 51 ...52 # Trac 0.1253 46 tracopt.perm.authz_policy.* = enabled 54 # for Trac 0.11 use this 55 #authz_policy.* = enabled 56 }}} 57 47 }}} 58 48 59 49 ==== Usage Notes ==== 60 Note that the order in which permission policies are specified is quite critical, 61 as policies will be examined in the sequence provided.50 51 Note the order in which permission policies are specified: policies are implemented in the sequence provided and therefore may override earlier policy specifications. 62 52 63 53 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. 64 54 65 NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted. 66 If none of the policies explicitly grants the permission, the final result will be `False` 67 (i.e. permission denied). 55 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. 68 56 69 57 The `authzpolicy.conf` file is a `.ini` style configuration file: 70 {{{ 58 {{{#!ini 71 59 [wiki:PrivatePage@*] 72 60 john = WIKI_VIEW, !WIKI_MODIFY … … 74 62 * = 75 63 }}} 76 * Each section of the config is a glob pattern used to match against a Trac resource 77 descriptor. These descriptors are in the form: 64 * Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form: 78 65 {{{ 79 66 <realm>:<id>@<version>[/<realm>:<id>@<version> ...] 80 67 }}} 81 Resources are ordered left to right, from parent to child. If any 82 component is inapplicable, `*` is substituted. If the version pattern is 83 not specified explicitely, all versions (`@*`) is added implicitly 84 85 Example: Match the WikiStart page 86 {{{ 68 69 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: 70 {{{#!ini 87 71 [wiki:*] 88 72 [wiki:WikiStart*] … … 91 75 }}} 92 76 93 Example: Match the attachment `wiki:WikiStart@117/attachment/FOO.JPG@*` 94 on WikiStart 95 {{{ 77 Example: Match the attachment `wiki:WikiStart@117/attachment:FOO.JPG@*` on WikiStart: 78 {{{#!ini 96 79 [wiki:*] 97 80 [wiki:WikiStart*] 98 81 [wiki:WikiStart@*] 99 [wiki:WikiStart@*/attachment/*] 100 [wiki:WikiStart@117/attachment/FOO.JPG] 101 }}} 102 103 * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of 104 appearance in the configuration file. '''ORDER IS CRITICAL'''. 105 106 * Once a section matches, the current username is matched against the keys 107 (usernames) of the section, '''IN ORDER'''. 82 [wiki:WikiStart@*/attachment:*] 83 [wiki:WikiStart@117/attachment:FOO.JPG] 84 }}} 85 86 * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''. 87 88 * Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''. 108 89 * If a key (username) is prefixed with a `@`, it is treated as a group. 109 * If a value (permission) is prefixed with a `!`, the permission is 110 denied rather than granted. 111 112 The username will match any of 'anonymous', 'authenticated', <username> 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 || 90 * If a value (permission) is prefixed with a `!`, the permission is denied rather than granted. 91 92 The username will match any of 'anonymous', 'authenticated', <username> 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. || 113 93 114 94 For example, if the `authz_file` contains: 115 {{{ 95 {{{#!ini 116 96 [wiki:WikiStart@*] 117 97 * = WIKI_VIEW … … 129 109 130 110 Then: 131 * All versions of WikiStart will be viewable by everybody (including anonymous)111 * All versions of WikiStart will be viewable by everybody, including anonymous 132 112 * !PrivatePage will be viewable only by john 133 113 * other pages will be viewable only by john and jack 134 114 135 115 Groups: 136 {{{ 116 {{{#!ini 137 117 [groups] 138 118 admins = john, jack … … 155 135 156 136 Some repository examples (Browse Source specific): 157 {{{ 137 {{{#!ini 158 138 # A single repository: 159 139 [repository:test_repo@*] 160 140 john = BROWSER_VIEW, FILE_VIEW 161 141 # John has BROWSER_VIEW and FILE_VIEW for the entire test_repo 142 143 # The default repository (requires Trac 1.0.2 or later): 144 [repository:@*] 145 john = BROWSER_VIEW, FILE_VIEW 146 # John has BROWSER_VIEW and FILE_VIEW for the entire default repository 162 147 163 148 # All repositories: 164 149 [repository:*@*] 165 150 jack = BROWSER_VIEW, FILE_VIEW 166 # J ohnhas BROWSER_VIEW and FILE_VIEW for all repositories167 }}} 168 169 Very fine grainrepository access:170 {{{ 151 # Jack has BROWSER_VIEW and FILE_VIEW for all repositories 152 }}} 153 154 Very granular repository access: 155 {{{#!ini 171 156 # John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only 172 157 [repository:test_repo@*/source:trunk/src/some/location/*@*] 173 158 john = BROWSER_VIEW, FILE_VIEW 174 159 175 176 160 # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only 177 161 [repository:test_repo@*/source:trunk/src/some/location/*@1] 178 162 john = BROWSER_VIEW, FILE_VIEW 179 163 180 181 164 # John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only 182 165 [repository:test_repo@*/source:trunk/src/some/location/somefile@*] 183 166 john = BROWSER_VIEW, FILE_VIEW 184 167 185 186 168 # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only 187 169 [repository:test_repo@*/source:trunk/src/some/location/somefile@1] … … 191 173 Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list. 192 174 193 194 175 ==== Missing Features ==== 195 Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see forgotten authz_policy.2.patch part of [trac:ticket:6680 #6680]).176 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]. 196 177 197 178 You cannot do the following: 198 {{{ 179 {{{#!ini 199 180 [groups] 200 181 team1 = a, b, c … … 204 185 }}} 205 186 206 Permission groups are not supported either . You cannot do the following:207 {{{ 187 Permission groups are not supported either, so you cannot do the following: 188 {{{#!ini 208 189 [groups] 209 190 permission_level_1 = WIKI_VIEW, TICKET_VIEW … … 217 198 === !AuthzSourcePolicy (mod_authz_svn-like permission policy) === #AuthzSourcePolicy 218 199 219 At the time of this writing, the old fine grained permissions system from Trac 0.11 and before used for restricting access to the repository has been converted to a permission policy component, but from the user point of view, this makes little if nodifference.220 221 That kind of fine-grainedpermission control needs a definition file, which is the one used by Subversion's mod_authz_svn.222 More information about this file format and about its usage in Subversion is available in the 200 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. 201 202 That kind of granular permission control needs a definition file, which is the one used by Subversion's mod_authz_svn. 203 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. 223 204 224 205 Example: 225 {{{ 206 {{{#!ini 226 207 [/] 227 208 * = r … … 241 222 ==== Trac Configuration ==== 242 223 243 To activate fine grained permissions you __must__ specify the {{{authz_file}}} option in the {{{[trac]}}} section of trac.ini. If this option is set to null or not specifiedthe permissions will not be used.244 245 {{{ 246 [ trac]224 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. 225 226 {{{#!ini 227 [svn] 247 228 authz_file = /path/to/svnaccessfile 248 229 }}} 249 230 250 If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add 251 252 {{{ 231 If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add: 232 233 {{{#!ini 253 234 authz_module_name = modulename 254 235 }}} 255 236 256 where ''modulename'' refers to the same repository indicated by the ` repository_dir` entry in the `[trac]` section. As an example, if the `repository_dir` entry in the `[trac]` section is {{{/srv/active/svn/blahblah}}}, that would yield the following:257 258 {{{ 259 [ trac]237 where ''modulename'' refers to the same repository indicated by the `<name>.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: 238 239 {{{ #!ini 240 [svn] 260 241 authz_file = /path/to/svnaccessfile 261 authz_module_name = blahblah242 authz_module_name = somemodule 262 243 ... 263 repository_dir = /srv/active/svn/blahblah 264 }}} 265 266 where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[blahblah:/some/path]}}}. 244 [repositories] 245 somemodule.dir = /srv/active/svn/somemodule 246 }}} 247 248 where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[somemodule:/some/path]}}}. 267 249 268 250 '''Note:''' Usernames inside the Authz file __must__ be the same as those used inside trac. … … 270 252 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. 271 253 272 {{{ 273 [trac] 274 permission_policies = AuthzSourcePolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy254 {{{#!ini 255 [trac] 256 permission_policies = AuthzSourcePolicy, ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy 275 257 }}} 276 258 … … 278 260 279 261 The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this: 280 {{{ 262 {{{#!apache 281 263 <Location /repos> 282 264 DAV svn … … 288 270 }}} 289 271 290 For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess] 272 For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess]. 273 274 === ReadonlyWikiPolicy 275 276 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: 277 {{{ 278 [trac] 279 permission_policies = ReadonlyWikiPolicy, 280 DefaultPermissionPolicy, 281 LegacyAttachmentPolicy 282 }}} 283 284 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. 285 286 **!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. 287 288 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. 289 290 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. 291 {{{ 292 [trac] 293 permission_policies = AuthzPolicy, 294 ReadonlyWikiPolicy, 295 DefaultPermissionPolicy, 296 LegacyAttachmentPolicy 297 }}} 298 299 The placement of [#AuthzSourcePolicy] relative to `ReadonlyWikiPolicy` does not matter since they don't perform checks on the same realms. 300 301 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. 291 302 292 303 == Debugging permissions 293 304 In trac.ini set: 294 {{{ 305 {{{#!ini 295 306 [logging] 296 307 log_file = trac.log … … 299 310 }}} 300 311 301 And watch:302 {{{ 312 Display the trac.log to understand what checks are being performed: 313 {{{#!sh 303 314 tail -n 0 -f log/trac.log | egrep '\[perm\]|\[authz_policy\]' 304 315 }}} 305 316 306 to understand what checks are being performed. See the sourced documentation of the plugin for more info. 307 317 See the sourced documentation of the plugin for more info. 308 318 309 319 ---- -
wiki/pages/TracGuide
r26484 r37343 61 61 * TracSupport — How to get more information 62 62 63 If you are looking for a good place to ask a question about Trac, look no further than the [ http://trac.edgewall.org/wiki/MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.63 If you are looking for a good place to ask a question about Trac, look no further than the [trac:MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers. -
wiki/pages/TracImport
r26484 r37343 2 2 [[PageOutline]] 3 3 4 By means of migrating from other issue-tracking systems, perform some external actions over tickets or simply synchronize different data bases, there are some available tools, plug-ins or scripts which lets you import or up-date tickets into Trac. 5 6 Below, follows a collection of some of those. 4 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. 7 5 8 6 == !TicketImportPlugin == 9 7 10 [http://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin] :: mainly, but not only, this plug-in lets you import or up-date into Trac a series of tickets from a '''CSV file''' or (if the [http://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel file'''.8 [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'''. 11 9 12 10 == !ExportImportXlsPlugin == 13 11 14 [http://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin] :: this plug-in add an admin panel for export and import tickets via '''XLS file'''. 15 * It depends on the python packages xlwt/rxld. 12 [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. 16 13 17 14 == Bugzilla == 18 15 19 [http://trac-hacks.org/wiki/BugzillaIssueTrackingPlugin BugzillaIssueTrackingPlugin] :: integrates Bugzilla into Trac keeping TracLinks 20 21 Ticket data can be imported from Bugzilla using the [http://trac.edgewall.org/browser/trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution. 16 [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. 22 17 23 18 {{{ … … 40 35 41 36 Currently, the following data is imported from Bugzilla: 42 43 37 * bugs 44 38 * bug activity (field changes) … … 47 41 48 42 The script provides a number of features to ease the conversion, such as: 49 50 * PRODUCT_KEYWORDS: Trac doesn't have the concept of products, so the script provides the ability to attach a ticket keyword instead. 51 52 * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp. 53 54 * 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. 43 * PRODUCT_KEYWORDS: Trac has no concept of products, so the script provides the ability to attach a ticket keyword instead. 44 * IGNORE_COMMENTS: Don't import Bugzilla comments that match a certain regexp. 45 * 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. 55 46 56 47 For more details on the available options, see the configuration section at the top of the script. 57 48 49 === Known Issues === 50 {{{ 51 #!comment 52 Don't merge this section in the default page 53 }}} 54 [[TicketQuery(keywords=~bugzilla,status=!closed)]] 55 56 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. 57 58 58 == Jira == 59 59 60 [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:61 - Parses the Jira backup XML file62 - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]63 - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords60 [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: 61 - Parses the Jira backup XML file. 62 - Sends the imported Jira data and attachments to Trac using the [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin]. 63 - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords. 64 64 65 65 == Mantis == 66 66 67 [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript] :: script to import from Mantis into Trac the following data:67 [http://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: script to import the following data from Mantis into Trac: 68 68 * bugs 69 69 * bug comments … … 73 73 == !PlanetForge == 74 74 75 [http://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin] :: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the COCLICO project. It extends the webadmin panel and the 'trac admin ...' command. Still has no 'import' feature.75 [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. 76 76 77 77 == Scarab == 78 78 79 [http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript] :: script that migrates Scarab issues to Trac tickets 80 * Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] 79 [http://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript]: script that migrates Scarab issues to Trac tickets. Requires [http://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin] 81 80 82 81 == Sourceforge == 83 82 84 [http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript] :: importer of !SourceForge's new backup file (originated from #Trac3521) 85 86 Also, ticket data can be imported from Sourceforge using the [http://trac.edgewall.org/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution. 83 [http://trac-hacks.org/wiki/SfnToTracScript SfnToTracScript]: importer of !SourceForge's new backup file (originated from #Trac3521). 84 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. 87 85 88 86 == Other == 89 87 90 Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import intothem from your application.88 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. 91 89 92 90 === Comma delimited file - CSV === 93 See [ http://trac.edgewall.org/attachment/wiki/TracSynchronize/csv2trac.2.py csv2trac.2.py] for details. This approach is particularly useful if one needs to enter a large number of tickets by hand. (note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases)94 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.91 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. 92 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. 95 93 96 94 ---- -
wiki/pages/TracIni
r26484 r37343 1 = The Trac Configuration File = 2 3 ''[Note To Editors] Please discuss documentation changes in the [#Discussion] section. Even better, send us [TracDev/SubmittingPatches documentation patches] against the ''code'' (i.e. where the configuration entries are documented), either on Trac-dev or on new tickets. '' 1 = The Trac Configuration File 4 2 5 3 [[TracGuideToc]] 6 4 [[PageOutline]] 7 5 8 Trac configuration is done by editing the '''`trac.ini`''' config file, located in `<projectenv>/conf/trac.ini`. Changes to the configuration are usually reflected immediately, though changes to the `[components]` or `[logging]` sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.6 Trac is configured by editing the **`trac.ini`** file, located in the `<projectenv>/conf` directory. The `trac.ini` configuration file and its parent directory should be writable by the web server. 9 7 10 T he `trac.ini` configuration file and its parent directory should be writable by the web server, as Trac currently relies on the possibility to trigger a complete environment reload to flush its caches.8 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. 11 9 12 == Global Configuration ==10 == Global Configuration 13 11 14 In versions prior to 0.11, the global configuration was by default located in `$prefix/share/trac/conf/trac.ini` or /etc/trac/trac.ini, depending on the distribution. If you're upgrading, you may want to specify that file to inherit from. Literally, when you're upgrading to 0.11, you have to add an `[inherit]` section to your project's `trac.ini` file. Additionally, you have to move your customized templates and common images from `$prefix/share/trac/...` to the new location. 15 16 Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows: 17 {{{ 12 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: 13 {{{#!ini 18 14 [inherit] 19 15 file = /path/to/global/trac.ini … … 25 21 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. 26 22 27 Note that the templates found in the `templates/` directory of the TracEnvironment have precedence over those found in `[inherit] templates_dir`. In turn, the latter have precedence over the installed templates, so be careful about what you put there , notably if you override a default template be sure to refresh your modifications when you upgrade to a new version of Trac (the preferred way to perform TracInterfaceCustomization being still to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation).23 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. 28 24 29 25 == Reference for settings … … 31 27 This is a brief reference of available configuration options, and their default settings. 32 28 29 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. 30 {{{ #!comment 31 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. 32 }}} 33 33 [[TracIni]] 34 34 -
wiki/pages/TracInstall
r26484 r37343 1 = Trac Installation Guide for 1. 0 =1 = Trac Installation Guide for 1.1 2 2 [[TracGuideToc]] 3 3 4 4 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. 5 5 6 Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default english version, as usual.7 8 If you're interested in contributing new translations for other languages or enhanc e the existing translations, then please have a look at [[trac:TracL10N]].9 10 What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to'''first read through these general instructions''' to get a good understanding of the tasks involved.6 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. 7 8 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]. 9 10 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. 11 11 12 12 [[PageOutline(2-3,Installation Steps,inline)]] 13 13 14 == Dependencies ==14 == Dependencies 15 15 === Mandatory Dependencies 16 16 To install Trac, the following software packages must be installed: 17 17 18 * [http://www.python.org/ Python], version >= 2.5 and < 3.0 19 (note that we dropped the support for Python 2.4 in this release) 20 * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6, or better yet, [http://pypi.python.org/pypi/distribute distribute] 21 * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 (unreleased version 0.7dev should work as well) 22 23 You also need a database system and the corresponding python bindings. 24 The database can be either SQLite, PostgreSQL or MySQL. 18 * [http://www.python.org/ Python], version >= 2.6 and < 3.0 19 (note that we dropped the support for Python 2.5 in this release) 20 * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6 21 * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 22 23 You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL. 25 24 26 25 ==== For the SQLite database #ForSQLite 27 26 28 As you must be using Python 2.5, 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module). 29 30 However, if you'd like, you can download the latest and greatest version of [[trac:Pysqlite]] from 31 [http://code.google.com/p/pysqlite/downloads/list google code], where you'll find the Windows 32 installers or the `tar.gz` archive for building from source: 33 {{{ 34 $ tar xvfz <version>.tar.gz 35 $ cd <version> 36 $ python setup.py build_static install 37 }}} 38 39 This will download the latest SQLite code and build the bindings. 40 41 SQLite 2.x is no longer supported. 42 43 A known bug PySqlite versions 2.5.2-4 prohibits upgrade of trac databases 44 from 0.11.x to 0.12. Please use versions 2.5.5 and newer or 2.5.1 and 45 older. See #9434 for more detail. 46 47 See additional information in [trac:PySqlite PySqlite]. 27 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). 28 29 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. 48 30 49 31 ==== For the PostgreSQL database #ForPostgreSQL … … 51 33 You need to install the database and its Python bindings: 52 34 * [http://www.postgresql.org/ PostgreSQL], version 8.0 or later 53 * [http://pypi.python.org/pypi/psycopg2 psycopg2] 35 * [http://pypi.python.org/pypi/psycopg2 psycopg2], version 2.0 or later 54 36 55 37 See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details. 56 38 57 58 39 ==== For the MySQL database #ForMySQL 59 40 60 Trac can now work quite well with MySQL, provided you follow the guidelines.41 Trac works well with MySQL, provided you follow the guidelines: 61 42 62 43 * [http://mysql.com/ MySQL], version 5.0 or later 63 44 * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later 64 45 65 It is '''very''' important to read carefully the[trac:MySqlDb] page before creating the database.46 Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database. 66 47 67 48 === Optional Dependencies 68 49 69 ==== Version Control System ==== 70 71 ===== Subversion ===== 72 * [http://subversion.apache.org/ Subversion], 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. 73 74 There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. TracSubversion points you to [http://alagazam.net Algazam], which works for me under Python 2.6.) 75 76 Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings. 77 78 79 '''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. 80 81 82 ===== Others ===== 83 84 Support for other version control systems is provided via third-parties. See [trac:PluginList] and [trac:VersionControlSystem]. 85 86 ==== Web Server ==== 87 A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server ] section below. 88 89 Alternatively you configure Trac to run in any of the following environments. 50 ==== Subversion 51 52 [http://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings. 53 54 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.) 55 56 For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page. 57 58 {{{#!div style="border: 1pt dotted; margin: 1em" 59 **Note:** 60 * Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer `ctype`-style bindings. 61 * If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. 62 }}} 63 64 ==== Git 65 66 [http://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page. 67 68 ==== Other Version Control Systems 69 70 Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem]. 71 72 ==== Web Server 73 A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below. 74 75 Alternatively you can configure Trac to run in any of the following environments: 90 76 * [http://httpd.apache.org/ Apache] with 91 - [http ://code.google.com/p/modwsgi/mod_wsgi], see [wiki:TracModWSGI] and92 http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac93 - [http://modpython.org/ mod_python 3. 3.1], deprecated: see TracModPython)77 - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and 78 [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac]. 79 - [http://modpython.org/ mod_python 3.5.0], see TracModPython 94 80 * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi) 95 81 * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web 96 82 server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp]) 83 * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI]) 97 84 * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script 98 85 is highly discouraged''', better use one of the previous options. 99 86 100 87 101 ==== Other Python Packages ====102 103 * [http://babel.edgewall.org Babel], version >= 0.9.5,104 needed for localization support (unreleased version 1.0dev should work as well)88 ==== Other Python Packages 89 90 * [http://babel.edgewall.org Babel], version 0.9.6 or >= 1.3, 91 needed for localization support 105 92 * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9 106 93 for WikiRestructuredText. 107 * [http://pygments.pocoo.org Pygments] for 108 [wiki:TracSyntaxColoring syntax highlighting]. 109 [http://silvercity.sourceforge.net/ SilverCity] and/or 110 [http://gnu.org/software/enscript/enscript.html Enscript] may still be used 111 but are deprecated and you really should be using Pygments. 94 * [http://pygments.org Pygments] for 95 [TracSyntaxColoring syntax highlighting]. 112 96 * [http://pytz.sf.net pytz] to get a complete list of time zones, 113 97 otherwise Trac will fall back on a shorter list from 114 98 an internal time zone implementation. 115 99 116 '''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel]. 117 118 Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing'' (there are even some pages that are still talking about Trac 0.8!). 119 120 121 == Installing Trac == 100 {{{#!div style="border: 1pt dotted; margin: 1em" 101 **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]. 102 }}} 103 104 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''. 105 106 == Installing Trac 107 108 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. 109 122 110 === Using `easy_install` 123 One way to install Trac is using [http://pypi.python.org/pypi/setuptools setuptools]. 124 With setuptools you can install Trac from the subversion repository; 111 Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools]. 125 112 126 113 A few examples: 127 114 128 - install Trac 1.0:129 {{{ 115 - Install Trac 1.0: 116 {{{#!sh 130 117 easy_install Trac==1.0 131 118 }}} 132 (NOT YET ENABLED) 133 - install latest development version 1.0dev: 134 {{{ 119 - Install latest development version: 120 {{{#!sh 135 121 easy_install Trac==dev 136 122 }}} … … 138 124 either use a released version or install from source 139 125 126 More information can be found on the [trac:setuptools] page. 127 128 {{{#!div style="border: 1pt dotted; margin: 1em" 129 **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]. 130 }}} 131 140 132 === Using `pip` 141 133 'pip' is an easy_install replacement that is very useful to quickly install python packages. 142 To get a trac installation up and running in less than 5 minutes:134 To get a Trac installation up and running in less than 5 minutes: 143 135 144 136 Assuming you want to have your entire pip installation in `/opt/user/trac` 145 137 146 138 - 147 {{{ 148 pip -E /opt/user/tracinstall trac psycopg2139 {{{#!sh 140 pip install trac psycopg2 149 141 }}} 150 142 or 151 143 - 152 {{{ 153 pip -E /opt/user/tracinstall trac mysql-python154 }}} 155 156 Make sure your OS specific headers are available for pip to automatically build PostgreSQL ( libpq-dev) or MySQL (libmysqlclient-dev) bindings.157 158 pip will automatically resolve all dependencies (like Genshi, pygments, etc.) and download the latest packages onpypi.python.org and create a self contained installation in `/opt/user/trac`.144 {{{#!sh 145 pip install trac mysql-python 146 }}} 147 148 Make sure your OS specific headers are available for pip to automatically build PostgreSQL (`libpq-dev`) or MySQL (`libmysqlclient-dev`) bindings. 149 150 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`. 159 151 160 152 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) 161 153 162 Additionally, you can install several trac plugins (listed [http://pypi.python.org/pypi?:action=search&term=trac&submit=search here]) through pip. 163 164 154 Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip. 165 155 166 156 === From source 167 Of course, using the python-typical setup at the top of the source directory also works. 168 169 You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. Trac-1.0.tar.gz), or you can get the source directly from the repository (see Trac:SubversionRepository for details). 170 171 {{{ 157 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. 158 159 {{{#!sh 172 160 $ python ./setup.py install 173 161 }}} 174 162 175 ''You'll need root permissions or equivalent for this step.'' 176 177 This will byte-compile the python source code and install it as an .egg file or folder in the `site-packages` directory 178 of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates. 179 180 The script will also install the [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments], as well as the [wiki:TracStandalone tracd] standalone server. 181 182 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): 183 {{{ 163 ''You will need root permissions or equivalent for this step.'' 164 165 This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory 166 of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as `htdocs` and `templates`. 167 168 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): 169 {{{#!sh 184 170 $ python ./setup.py install 185 171 }}} 186 Alternatively, you can do a `bdist_egg` and copy the .egg from dist/ to the place of your choice, or you can create a Windows installer (`bdist_wininst`). 187 188 === Advanced Options === 172 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`). 173 174 === Using installer 175 176 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. 177 178 === Using package manager 179 180 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. 181 182 === Advanced `easy_install` Options 189 183 190 184 To install Trac to a custom location, or find out about other advanced installation options, run: 191 {{{ 185 {{{#!sh 192 186 easy_install --help 193 187 }}} 194 188 195 Also see [http://docs.python.org/ inst/inst.html Installing Python Modules] for detailed information.189 Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information. 196 190 197 191 Specifically, you might be interested in: 198 {{{ 192 {{{#!sh 199 193 easy_install --prefix=/path/to/installdir 200 194 }}} 201 or, if installing Trac to a Mac OS X system: 202 {{{ 203 easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages 204 }}} 205 Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.6/site-packages }}} by default 206 207 The above will place your `tracd` and `trac-admin` commands into `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.5/site-packages`, which is Apple's preferred location for third-party Python application installations. 208 209 210 == Creating a Project Environment == 211 212 A [TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable [TracIni configuration file], and various other files and directories. 213 214 A new environment is created using [wiki:TracAdmin trac-admin]: 215 {{{ 195 or, if installing Trac on a Mac OS X system: 196 {{{#!sh 197 easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages 198 }}} 199 200 {{{#!div style="border: 1pt dotted; margin: 1em" 201 **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. 202 203 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. 204 }}} 205 206 == Creating a Project Environment 207 208 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. 209 210 A new environment is created using [TracAdmin trac-admin]: 211 {{{#!sh 216 212 $ trac-admin /path/to/myproject initenv 217 213 }}} 218 214 219 [TracAdmin trac-admin] will prompt you for the information it needs to create the environment, such as the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for one of these options, just press `<Enter>` to use the default value. 220 221 Using the default database connection string in particular will always work as long as you have SQLite installed. 222 For the other [DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point. 223 224 Since 0.12, Trac doesn't ask for a [TracEnvironment#SourceCodeRepository source code repository] anymore when creating an environment. Repositories can be [TracRepositoryAdmin added] afterward, or the version control support can be disabled completely if you don't need it. 225 226 Also note that the values you specify here can be changed later by directly editing the [TracIni conf/trac.ini] configuration file. 215 [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 `<Enter>` to use the default value. 216 217 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. 218 219 Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file. 220 221 {{{#!div style="border: 1pt dotted; margin: 1em" 222 **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. 223 }}} 227 224 228 225 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: 229 {{{ 230 # chown -R apache.apache /path/to/myproject 231 }}} 226 {{{#!sh 227 $ chown -R apache:apache /path/to/myproject 228 }}} 229 230 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). 232 231 233 232 {{{#!div class=important … … 235 234 }}} 236 235 237 238 236 == Deploying Trac 239 237 240 === Running the Standalone Server ===241 242 After having created a Trac environment, you can easily try the web interface by running the standalone server [ wiki:TracStandalone tracd]:243 {{{ 238 === Running the Standalone Server 239 240 After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]: 241 {{{#!sh 244 242 $ tracd --port 8000 /path/to/myproject 245 243 }}} 246 244 247 245 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: 248 {{{ 246 {{{#!sh 249 247 $ tracd -s --port 8000 /path/to/myproject 250 248 }}} 251 249 252 === Running Trac on a Web Server === 250 {{{#!div style="border: 1pt dotted; margin: 1em" 251 **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. 252 253 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`. 254 {{{#!sh 255 export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 256 }}} 257 258 Alternatively, the variable can be set in the shell before executing `tracd`: 259 {{{#!sh 260 $ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject 261 }}} 262 }}} 263 264 === Running Trac on a Web Server 253 265 254 266 Trac provides various options for connecting to a "real" web server: 255 - [ wiki:TracFastCgi FastCGI]267 - [TracFastCgi FastCGI] 256 268 - [wiki:TracModWSGI mod_wsgi] 257 - //[wiki:TracModPython mod_python] (no longer recommended, as mod_python is not actively maintained anymore)//258 - //[ wiki:TracCgi CGI] (should not be used, as the performance is far from optimal)//269 - [TracModPython mod_python] 270 - //[TracCgi CGI] (should not be used, as the performance is far from optimal)// 259 271 260 272 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. 261 273 262 ==== Generating the Trac cgi-bin directory ====#cgi-bin263 264 In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [ wiki:TracAdmin trac-admin].265 266 There is, however, a bit of a chicken-and-egg problem. The [ wiki:TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this:267 {{{ 274 ==== Generating the Trac cgi-bin directory #cgi-bin 275 276 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]. 277 278 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: 279 {{{#!sh 268 280 mkdir -p /usr/share/trac/projects/my-project 269 281 trac-admin /usr/share/trac/projects/my-project initenv … … 271 283 mv /tmp/deploy/* /usr/share/trac 272 284 }}} 273 274 275 ==== Mapping Static Resources ====285 Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory. 286 287 ==== Mapping Static Resources 276 288 277 289 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). … … 281 293 There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible by `/chrome/<plugin>` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything. 282 294 283 Note that in order to get those static resources on the filesystem, you need first to extract the relevant resources from Trac using the [TracAdmin trac-admin]` <environment>deploy` command:295 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: 284 296 [[TracAdminHelp(deploy)]] 285 297 … … 289 301 - `<plugins>/` - one directory for each resource directory managed by the plugins enabled for this environment 290 302 291 ===== Example: Apache and `ScriptAlias` =====#ScriptAlias-example303 ===== Example: Apache and `ScriptAlias` #ScriptAlias-example 292 304 293 305 Assuming the deployment has been done this way: 294 {{{ 295 $ trac-admin /var/trac/env deploy /path/to/ trac/htdocs/common306 {{{#!sh 307 $ trac-admin /var/trac/env deploy /path/to/shared/trac 296 308 }}} 297 309 298 310 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: 299 {{{ 311 {{{#!apache 300 312 Alias /trac/chrome/common /path/to/trac/htdocs/common 301 313 Alias /trac/chrome/site /path/to/trac/htdocs/site … … 308 320 309 321 If using mod_python, you might want to add this too (otherwise, the alias will be ignored): 310 {{{ 322 {{{#!apache 311 323 <Location "/trac/chrome/common/"> 312 324 SetHandler None … … 314 326 }}} 315 327 316 Note that we mapped `/trac` part of the URL to the `trac.*cgi` script, and the path `/trac/chrome/common` is the path you have to append to that location to intercept requests to the static resources.328 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. 317 329 318 330 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): 319 {{{ 331 {{{#!apache 320 332 Alias /trac/chrome/site /path/to/projectenv/htdocs 321 333 … … 326 338 }}} 327 339 328 Alternatively to aliasing `/trac/chrome/common`, you can tell Trac to generate direct links for those static resources (and only those), using the [[ wiki:TracIni#trac-section| [trac] htdocs_location]] configuration setting:329 {{{ 340 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: 341 {{{#!ini 330 342 [trac] 331 343 htdocs_location = http://static.example.org/trac-common/ … … 334 346 335 347 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: 336 {{{ 348 {{{#!sh 337 349 $ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common 338 350 }}} 339 351 340 341 ==== Setting up the Plugin Cache ==== 342 343 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. 344 345 == Configuring Authentication == 346 347 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. 352 ==== Setting up the Plugin Cache 353 354 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. 355 356 == Configuring Authentication 357 358 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. 348 359 349 360 The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. … … 351 362 Please refer to one of the following sections: 352 363 * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`. 353 * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi` of course, but the same instructions applies also for`mod_python`, `mod_fcgi` or `mod_fastcgi`.364 * [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`. 354 365 * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx) 366 367 [trac:TracAuthenticationIntroduction] also contains some useful information for beginners. 355 368 356 369 == Granting admin rights to the admin user 357 370 Grant admin rights to user admin: 358 {{{ 371 {{{#!sh 359 372 $ trac-admin /path/to/myproject permission add admin TRAC_ADMIN 360 373 }}} 361 This user will have an "Admin" entry menu that will allow you to admin your trac project. 362 363 == Finishing the install 364 365 === Automatic reference to the SVN changesets in Trac tickets === 366 367 You can configure SVN to automatically add a reference to the changeset into the ticket comments, whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas: 368 * '''`Refs #123`''' - to reference this changeset in `#123` ticket 369 * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed'' 370 371 This functionality requires a post-commit hook to be installed as described in [wiki:TracRepositoryAdmin#ExplicitSync TracRepositoryAdmin], and enabling the optional commit updater components by adding the following line to the `[components]` section of your [wiki:TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel. 372 {{{ 373 tracopt.ticket.commit_updater.* = enabled 374 }}} 375 For more information, see the documentation of the `CommitTicketUpdater` component in the "Plugins" admin panel. 376 377 === Using Trac === 374 375 This user will have an //Admin// navigation item that directs to pages for administering your Trac project. 376 377 == Configuring Trac 378 379 TracRepositoryAdmin provides information on configuring version control repositories for your project. 380 381 == Using Trac 378 382 379 383 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. 380 384 381 Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [ wiki:TracPermissions permissions] to authenticated users to see the full set of features.385 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. 382 386 383 387 '' Enjoy! '' -
wiki/pages/TracInterfaceCustomization
r26484 r37343 1 = Customizing the Trac Interface =1 = Customizing the Trac Interface 2 2 [[TracGuideToc]] 3 3 [[PageOutline]] 4 4 5 == Introduction ==6 This page is meant to give users suggestions on how they can customize the look of Trac. Topics on this page cover editing the HTML templates and CSS files, but not the program code itself. The topics are intended to show users how they can modify the look of Trac to meet their specific needs.Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.5 == Introduction 6 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. 7 7 8 == Project Logo and Icon ==9 The easiest parts of the Trac interface to customize are the logo and the site icon. 8 == Project Logo and Icon 9 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]. 10 10 11 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'')11 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''. 12 12 13 '' 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.''13 '''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. 14 14 15 15 Now configure the appropriate section of your [wiki:TracIni trac.ini]: 16 16 17 === Logo ===18 Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.17 === Logo 18 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'. 19 19 20 {{{ 20 {{{#!ini 21 21 [header_logo] 22 22 src = site/my_logo.gif … … 26 26 }}} 27 27 28 === Icon ===29 Icons should be a 32x32 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file. Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.28 === Icon 29 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: 30 30 31 {{{ 31 {{{#!ini 32 32 [project] 33 33 icon = site/my_icon.ico 34 34 }}} 35 35 36 Note though that this icon is ignored by Internet Explorer, which only accepts a file named ``favicon.ico`` at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from ``trac.ini`` as follows: 36 == Custom Navigation Entries 37 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. 37 38 38 {{{ 39 [project] 40 icon = /favicon.ico 41 }}} 42 43 Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension. 44 45 {{{ 46 [project] 47 icon = /favicon.ico? 48 }}} 49 50 == Custom Navigation Entries == 51 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). 52 53 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 . 54 {{{ 39 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: 40 {{{#!ini 55 41 [mainnav] 56 42 wiki.label = Home … … 65 51 == Site Appearance == #SiteAppearance 66 52 67 Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.53 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`: 68 54 69 Say you want to add a link to a custom stylesheet, and then your own 70 header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), e.g. {{{/path/to/env/templates/site.html}}}: 71 72 {{{ 73 #!xml 55 {{{#!xml 74 56 <html xmlns="http://www.w3.org/1999/xhtml" 75 57 xmlns:py="http://genshi.edgewall.org/" … … 79 61 <head py:match="head" py:attrs="select('@*')"> 80 62 ${select('*|comment()|text()')} 81 <link rel="stylesheet" type="text/css" 82 href="${href.chrome('site/style.css')}" /> 63 <link rel="stylesheet" href="${href.chrome('site/style.css')}" /> 83 64 </head> 84 65 … … 99 80 }}} 100 81 101 Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example `${href.chrome('site/style.css')}` attribute references a CSS file placed into environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting.82 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. 102 83 103 `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 104 and modify them. 84 `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. 105 85 See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`. 106 86 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. 107 108 87 109 88 Example snippet of adding introduction text to the new ticket form (but not shown during preview): … … 124 103 Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss]. 125 104 126 If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others: 127 {{{ 128 #!xml 129 <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')" 130 xmlns:xi="http://www.w3.org/2001/XInclude"> 131 <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> 132 <xi:include href="site_newticket.cs"><xi:fallback /></xi:include> 133 </py:if> 134 ${select('*')} 135 </form> 136 }}} 137 138 Also note that the `site.html` (despite its name) can be put in a common 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. 105 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. 139 106 140 107 == Project List == #ProjectList … … 142 109 You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. 143 110 144 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.111 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: 145 112 146 {{{ 147 #!text/html 113 {{{#!text/html 148 114 <!DOCTYPE html 149 115 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" … … 173 139 174 140 For [wiki:TracModWSGI mod_wsgi]: 175 {{{ 141 {{{#!python 176 142 os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html' 177 143 }}} 178 144 179 145 For [wiki:TracFastCgi FastCGI]: 180 {{{ 146 {{{#!apache 181 147 FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ 182 148 -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template … … 184 150 185 151 For [wiki:TracModPython mod_python]: 186 {{{ 152 {{{#!apache 187 153 PythonOption TracEnvParentDir /parent/dir/of/projects 188 154 PythonOption TracEnvIndexTemplate /path/to/template … … 190 156 191 157 For [wiki:TracCgi CGI]: 192 {{{ 158 {{{#!apache 193 159 SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template 194 160 }}} … … 196 162 For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd: 197 163 - Unix 198 {{{ 199 #!sh 164 {{{#!sh 200 165 $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template 201 166 }}} 202 167 - Windows 203 {{{ 204 #!sh 168 {{{#!sh 205 169 $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template 206 170 }}} 207 171 208 == Project Templates ==172 == Project Templates 209 173 210 The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by 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.174 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. 211 175 212 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.176 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. 213 177 214 However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of twoalternatives:178 However, do not edit templates or site resources inside the Trac egg. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives: 215 179 * For a modification to one project only, copy the template to project `templates` directory. 216 * 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.180 * 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. 217 181 218 182 Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg. 219 183 220 Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server.184 Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server. 221 185 222 186 ---- -
wiki/pages/TracLinks
r26484 r37343 28 28 Milestones :: `milestone:1.0` 29 29 Attachment :: `attachment:example.tgz` (for current page attachment), `attachment:attachment.1073.diff:ticket:944` (absolute path) 30 Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk` 30 Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`, `[1/repository]` 31 31 Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]` 32 32 Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`, … … 43 43 Milestones :: milestone:1.0 44 44 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path) 45 Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk 45 Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository] 46 46 Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk] 47 47 Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953, … … 134 134 135 135 In order to link explicitly to a [=#toplevel toplevel] Wiki page, 136 use the `wiki:/` prefix. 137 Be careful **not** to use the `/` prefix alone, as this corresponds to the 138 [#Server-relativelinks] syntax and with such a link you will lack the `/wiki/` 139 part in the resulting URL. 140 141 ''(Changed in 0.11)'' Note that in Trac 0.10, using e.g. `[../newticket]` may have worked for linking to the `/newticket` top-level URL, but since 0.11, such a link will stay in the wiki namespace and therefore link to a sibling page. 142 See [#Server-relativelinks] for the new syntax. 136 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. 143 137 144 138 === Link anchors === … … 312 306 - `ticket:1,150` 313 307 314 ''(since Trac 0.11)''315 316 308 === timeline: links === 317 309 318 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 alternatively you can specify your local time, followed by your timezone if you don't want to compute the UTC time.310 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. 319 311 320 312 Examples: … … 323 315 - `timeline:2008-01-29T15:48Z` 324 316 - `timeline:2008-01-29T16:48+01` 325 326 ''(since Trac 0.11)'' 317 - `timeline:2008-01-29T16:48+0100` 318 - `timeline:2008-01-29T16:48+01:00` 327 319 328 320 === wiki: links === … … 339 331 ''aliases:'' `browser:`, `repos:` 340 332 341 The default behavior for a source:/some/path linkis to open the browser in that directory directory333 The default behavior for a `source:/some/path link` is to open the browser in that directory directory 342 334 if the path points to a directory or to show the latest content of the file. 343 335 … … 351 343 352 344 Finally, one can also highlight an arbitrary set of lines: 353 - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103 .354 ''(since 0.11)''345 - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103, and target line 99 346 - 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 355 347 356 348 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)'' -
wiki/pages/TracLogging
r26484 r37343 1 = Trac Logging =1 = Trac Logging 2 2 [[TracGuideToc]] 3 3 … … 6 6 Logging is configured in the `[logging]` section in [wiki:TracIni#logging-section trac.ini]. 7 7 8 == Supported Logging Methods ==8 == Supported Logging Methods 9 9 10 10 The log method is set using the `log_type` option in [wiki:TracIni#logging-section trac.ini], which takes any of the following values: … … 16 16 '''eventlog''':: (Windows) Use the system's NT Event Log for Trac logging. 17 17 18 == Log Levels ==18 == Log Levels 19 19 20 20 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: … … 26 26 '''DEBUG''':: Trace messages, profiling, etc. 27 27 28 Note that starting with Trac 0.11.5 you can in addition 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).28 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. 29 29 30 == Log Format ==30 == Log Format 31 31 32 Starting with Trac 0.10.4 (see [trac:#2844 #2844]), it is possible to set the output format for log entries. This can be donethrough 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:32 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: 33 33 '''$(basename)s''':: The last path component of the current environment. 34 34 '''$(path)s''':: The absolute path for the current environment. … … 38 38 39 39 The default format is: 40 {{{ 40 {{{#!ini 41 41 log_format = Trac[$(module)s] $(levelname)s: $(message)s 42 42 }}} 43 43 44 44 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: 45 {{{ 45 {{{#!ini 46 46 log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s 47 47 }}} -
wiki/pages/TracModPython
r26484 r37343 1 = Trac and mod_python =2 1 [[TracGuideToc]] 3 2 3 = Trac and mod_python 4 5 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. 4 6 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. 5 7 6 {{{#!div class="important" 7 ** A Word of Warning ** 8 9 As of 16^th^ June 2010, the mod_python project is officially dead. If you are considering using mod_python for a new installation, '''please don't'''! There are known issues which will not be fixed and there are now better alternatives. Check out the main TracInstall pages for your target version for more information. 10 }}} 11 12 13 These instructions are for Apache 2; if you are still using Apache 1.3, you may have some luck with [trac:wiki:TracModPython2.7 TracModPython2.7], but you'll be totally on your own. 8 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. 14 9 15 10 [[PageOutline(2-3,Overview,inline)]] … … 18 13 19 14 If you just installed mod_python, you may have to add a line to load the module in the Apache configuration: 20 {{{ 15 {{{#!apache 21 16 LoadModule python_module modules/mod_python.so 22 17 }}} 23 18 24 '' Note: The exact path to the module depends on how the HTTPD installation is laid out.''25 26 On Debian using apt-get 27 {{{ 19 '''Note''': The exact path to the module depends on how the HTTPD installation is laid out. 20 21 On Debian using apt-get: 22 {{{#!sh 28 23 apt-get install libapache2-mod-python libapache2-mod-python-doc 29 24 }}} 30 (Still on Debian) after you have installed mod_python, you must enable the modules in apache2 (equivalent of the above Load Module directive): 31 {{{ 25 26 Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive: 27 {{{#!sh 32 28 a2enmod python 33 29 }}} 30 34 31 On Fedora use, using yum: 35 {{{ 32 {{{#!sh 36 33 yum install mod_python 37 34 }}} 38 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+. 39 {{{ 40 #!xml 35 36 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+. 37 {{{#!apache 41 38 <Location /mpinfo> 42 39 SetHandler mod_python … … 49 46 50 47 A simple setup of Trac on mod_python looks like this: 51 {{{ 52 #!xml 48 {{{#!apache 53 49 <Location /projects/myproject> 54 50 SetHandler mod_python … … 62 58 }}} 63 59 64 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. 65 66 The options available are 67 {{{ 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 }}} 86 87 === Python Egg Cache ===88 89 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 writablean alternate egg cache directory can be specified like this:90 {{{ 60 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. 61 62 The options available are: 63 {{{#!apache 64 # For a single project 65 PythonOption TracEnv /var/trac/myproject 66 67 # For multiple projects 68 PythonOption TracEnvParentDir /var/trac/myprojects 69 70 # For the index of multiple projects 71 PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html 72 73 # A space delimitted list, with a "," between key and value pairs. 74 PythonOption TracTemplateVars key1,val1 key2,val2 75 76 # Useful to get the date in the wanted order 77 PythonOption TracLocale en_GB.UTF8 78 79 # See description above 80 PythonOption TracUriRoot /projects/myproject 81 }}} 82 83 === Python Egg Cache 84 85 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: 86 {{{#!apache 91 87 PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache 92 88 }}} 93 89 94 or you can uncompress the Genshi egg to resolve problems extracting from it.95 96 === Configuring Authentication ===90 Or you can uncompress the Genshi egg to resolve problems extracting from it. 91 92 === Configuring Authentication 97 93 98 94 See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page. 99 95 100 101 96 == Advanced Configuration 102 97 103 === Setting the Python Egg Cache === 104 105 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. 106 107 {{{ 108 #!xml 98 === Setting the Python Egg Cache 99 100 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. 101 102 {{{#!apache 109 103 <Location /projects/myproject> 110 104 ... … … 114 108 }}} 115 109 116 117 === Setting the !PythonPath === 118 119 If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler using the `PythonPath` directive: 120 {{{ 121 #!xml 110 === Setting the !PythonPath 111 112 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: 113 {{{#!apache 122 114 <Location /projects/myproject> 123 115 ... … … 129 121 Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work. 130 122 131 === Setting up multiple projects ===123 === Setting up multiple projects 132 124 133 125 The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`: 134 {{{ 135 #!xml 126 {{{#!apache 136 127 <Location /projects> 137 128 SetHandler mod_python … … 146 137 147 138 If you don't want to have the subdirectory listing as your projects home page you can use a 148 {{{ 149 #!xml 139 {{{#!apache 150 140 <LocationMatch "/.+/"> 151 141 }}} … … 154 144 155 145 You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive: 156 {{{ 157 #!xml 146 {{{#!apache 158 147 <LocationMatch "/projects/[^/]+/login"> 159 148 AuthType Basic … … 164 153 }}} 165 154 166 === Virtual Host Configuration === 167 168 Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like 169 !http://trac.mycompany.com): 170 171 {{{ 172 #!xml 173 <VirtualHost * > 155 === Virtual Host Configuration 156 157 Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like 158 `http://trac.mycompany.com`: 159 160 {{{#!apache 161 <VirtualHost *> 174 162 DocumentRoot /var/www/myproject 175 163 ServerName trac.mycompany.com … … 191 179 192 180 This does not seem to work in all cases. What you can do if it does not: 193 * Try using `<LocationMatch>` instead of `<Location>` 194 * <Location /> may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to python and authentication does not work (i.e. you get the infamous Authentication information missing error). If this applies to you, try using a sub-directory for trac instead of the root (i.e. /web/ and /web/login instead of / and /login).181 * Try using `<LocationMatch>` instead of `<Location>`. 182 * `<Location />` 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. 195 183 * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`. 196 184 197 For a virtual host that supports multiple projects replace "`TracEnv`" /var/trac/myproject with "`TracEnvParentDir`" /var/trac/ 198 199 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". 200 201 == Troubleshooting == 202 203 In general, if you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option: 204 {{{ 205 #!xml 185 For a virtual host that supports multiple projects replace `TracEnv /var/trac/myproject` with `TracEnvParentDir /var/trac`. 186 187 '''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". 188 189 == Troubleshooting 190 191 If you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option: 192 {{{#!apache 206 193 <Location /projects/myproject> 207 194 ... … … 212 199 For multiple projects, try restarting the server as well. 213 200 214 === Login Not Working === 201 === Login Not Working 202 215 203 If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`. 216 204 The workaround is to use negation expression as follows (for multi project setups): 217 {{{ 218 #!xml 205 {{{#!apache 219 206 #this one for other pages 220 207 <Location ~ "/*(?!login)"> … … 223 210 PythonOption TracEnvParentDir /projects 224 211 PythonOption TracUriRoot / 225 226 </Location> 212 </Location> 213 227 214 #this one for login page 228 215 <Location ~ "/[^/]+/login"> … … 247 234 248 235 This problem will most certainly hit you on Unix when using Python 2.4. 249 In Python 2.4, some version of Expat (an XML parser library written in C) is used, 250 and if Apache is using another version, this results in segmentation faults. 251 As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem 252 can now hit you even if everything was working fine before with Trac 0.10. 253 254 See Graham Dumpleton's detailed [http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash explanation and workarounds] for the issue. 255 256 === Form submission problems === 236 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. 237 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. 238 239 === Form submission problems 257 240 258 241 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. 259 242 260 === Problem with virtual host configuration ===261 262 If the <Location /> 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 `<Directory>` block).263 264 Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able download any CSS or images/icons. I used <Location /trac> `SetHandler None` </Location> to circumvent the problem, though I do not know if this isthe most elegant solution.265 266 === Problem with zipped egg ===267 268 It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify , try installing Trac using the `--always-unzip` option, like this:269 270 {{{ 243 === Problem with virtual host configuration 244 245 If the <Location /> 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 `<Directory>` block. 246 247 Using <Location /> 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 <Location /trac> `SetHandler None` </Location> to circumvent the problem, though this may not be the most elegant solution. 248 249 === Problem with zipped egg 250 251 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: 252 253 {{{#!sh 271 254 easy_install --always-unzip Trac-0.12b1.zip 272 255 }}} 273 256 274 === Using .htaccess ===257 === Using .htaccess 275 258 276 259 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. 277 260 278 It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)279 280 A success story: For me it workedout-of-box, with following trivial config:281 {{{#! xml261 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. 262 263 This also works out-of-box, with following trivial config: 264 {{{#!apache 282 265 SetHandler mod_python 283 266 PythonInterpreter main_interpreter … … 292 275 }}} 293 276 294 The `TracUriRoot` is obviously the path you need to enter to the browser to get to the trac (e.g. domain.tld/projects/trac)295 296 === Additional .htaccess help ===297 298 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:299 300 {{{ 277 The `TracUriRoot` is obviously the path you need to enter to the browser to get to Trac, eg `domain.tld/projects/trac`. 278 279 === Additional .htaccess help 280 281 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: 282 283 {{{#!apache 301 284 <IfModule mod_rewrite.c> 302 285 RewriteEngine Off … … 305 288 306 289 === Platform specific issues 307 ==== Win32 Issues ==== 308 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. 309 310 311 ==== OS X issues ==== 312 313 When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here]. 314 315 ==== SELinux issues ==== 316 317 If Trac reports something like: ''Cannot get shared lock on db.lock'' 318 The security context on the repository may need to be set: 319 320 {{{ 290 ==== Win32 Issues 291 292 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. 293 294 ==== OS X issues 295 296 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. 297 298 ==== SELinux issues 299 300 If Trac reports something like: `Cannot get shared lock on db.lock`, then the security context on the repository may need to be set: 301 302 {{{#!sh 321 303 chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY 322 304 }}} 323 305 324 See also [http://subversion.tigris.org/faq.html#reposperms] 325 326 ==== FreeBSD issues ==== 327 Pay attention to the version of the installed mod_python and sqlite packages. Ports have both the new and old ones, but earlier versions of pysqlite and mod_python won't integrate as the former requires threaded support in python, and the latter requires a threadless install. 328 329 If you compiled and installed apache2, apache wouldn´t support threads (cause it doesn´t work very well on FreeBSD). You could force thread support when running ./configure for apache, using --enable-threads, but this isn´t recommendable. 330 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 331 332 {{{ 306 See also [http://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?] 307 308 ==== FreeBSD issues 309 310 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: 311 * pysqlite requires threaded support in Python 312 * mod_python requires a threadless install. 313 314 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. 315 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: 316 317 {{{#!sh 333 318 export LD_PRELOAD=/usr/lib/libc_r.so 334 319 }}} 335 320 336 337 ==== Fedora 7 Issues ==== 338 Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython but not for tracd 339 340 341 === Subversion issues === 342 343 If you get the following Trac Error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. (The better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.) 344 345 If this is not the case, it's possible that you're using Subversion libraries that are binary incompatible with the apache ones (an incompatibility of the `apr` libraries is usually the cause). In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`). 346 347 You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter: 348 {{{ 321 ==== Fedora 7 Issues 322 323 Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd. 324 325 === Subversion issues 326 327 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. 328 329 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`). 330 331 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: 332 {{{#!apache 349 333 PythonInterpreter main_interpreter 350 334 }}} 351 This is anyway the recommended workaround for other well-known issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue. 352 353 === Page layout issues === 354 355 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: 356 {{{ 357 #!xml 335 336 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. 337 338 === Page layout issues 339 340 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: 341 {{{#!apache 358 342 Alias /myproject/css "/usr/share/trac/htdocs/css" 359 343 <Location /myproject/css> … … 362 346 }}} 363 347 364 Note: For the above configuration to have any effect it must be put after the configuration of your project root location, i.e. {{{<Location /myproject />}}}. 365 366 Also, setting `PythonOptimize On` seems to mess up the page headers and footers, in addition to hiding the documentation for macros and plugins (see #Trac8956). Considering how little effect the option has, it is probably a good idea to leave it `Off`. 367 368 === HTTPS issues === 369 370 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: 371 {{{ 372 #!xml 373 <VirtualHost * > 348 '''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{<Location /myproject />}}}. 349 350 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`. 351 352 === HTTPS issues 353 354 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: 355 {{{#!apache 356 <VirtualHost *> 374 357 DocumentRoot /var/www/myproject 375 358 ServerName trac.mycompany.com … … 379 362 }}} 380 363 381 382 === Segmentation fault with php5-mhash or other php5 modules === 383 You may encounter segfaults (reported on debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See debian bug report [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487]384 385 Some people also have troubles when using php5 compiled with its own 3rd party libraries instead of system libraries. Check here [http://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault]364 === Segmentation fault with php5-mhash or other php5 modules 365 366 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]. 367 368 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]. 386 369 387 370 ---- 388 See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipeTracNginxRecipe]371 See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe] -
wiki/pages/TracModWSGI
r26484 r37343 1 = Trac and mod_wsgi = 2 3 4 [http://code.google.com/p/modwsgi/ 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 performances. 1 = Trac and mod_wsgi 2 3 [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. 5 4 6 5 [[PageOutline(2-3,Overview,inline)]] … … 8 7 == The `trac.wsgi` script 9 8 10 Trac can be run on top of mod_wsgi with the help of the following application script, which is just a Python file, though usually saved with a `.wsgi` extension). 9 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. 10 11 A robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` 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]. 12 13 If you are using Trac with multiple projects, you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` in trac.wsgi: 14 {{{#!python 15 def application(environ, start_request): 16 # Add this to config when you have multiple projects 17 environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects') 18 .. 19 }}} 11 20 12 21 === A very basic script … … 23 32 }}} 24 33 25 The `TRAC_ENV` variable should naturally be the directory for your Trac environment (if you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead), while the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs. 34 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`. 35 36 On Windows: 37 - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example: 38 {{{#!python 39 os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs' 40 }}} 41 - If run under a Window service, you should create a directory for Python Egg cache: 42 {{{#!python 43 os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs' 44 }}} 26 45 27 46 === A more elaborate script 28 47 29 If you 're 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.48 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. 30 49 31 50 To solve this problem, use the following `.wsgi` file instead: … … 43 62 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. 44 63 45 If you have installed Trac and eggs in a path different from the standard oneyou should add that path by adding the following code at the top of the wsgi script:64 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: 46 65 47 66 {{{#!python … … 52 71 Change it according to the path you installed the Trac libs at. 53 72 54 === Recommended `trac.wsgi` script55 56 A somewhat robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths (see TracInstall#cgi-bin).57 58 59 73 == Mapping requests to the script 60 74 61 After you've done preparing your .wsgi script, add the following to your Apache configuration file (`httpd.conf` for example).62 63 {{{ 75 After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`: 76 77 {{{#!apache 64 78 WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi 65 79 … … 73 87 Here, the script is in a subdirectory of the Trac environment. 74 88 75 If you followed the directions [ http://trac.edgewall.org/wiki/TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:76 77 {{{ 89 If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following: 90 91 {{{#!apache 78 92 WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi 79 93 … … 85 99 }}} 86 100 87 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 as a result. After adding this configuration, restart Apache, and then it should work.101 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. 88 102 89 103 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): … … 97 111 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. 98 112 99 100 113 == Configuring Authentication 101 114 102 We describe in the the following sections different methods for setting up authentication. 103 104 See also [http://httpd.apache.org/docs/2.2/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide. 105 106 === Using Basic Authentication === 107 108 The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file: 109 {{{ 115 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. 116 117 === Using Basic Authentication 118 119 The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows: 120 {{{#!sh 110 121 $ htpasswd -c /somewhere/trac.htpasswd admin 111 122 New password: <type password> … … 114 125 }}} 115 126 116 After the first user, you don t need the "-c" option anymore:117 {{{ 127 After the first user, you don't need the "-c" option anymore: 128 {{{#!sh 118 129 $ htpasswd /somewhere/trac.htpasswd john 119 130 New password: <type password> … … 126 137 After you've created the users, you can set their permissions using TracPermissions. 127 138 128 Now, you 'llneed to enable authentication against the password file in the Apache configuration:129 {{{ 139 Now, you need to enable authentication against the password file in the Apache configuration: 140 {{{#!apache 130 141 <Location "/trac/login"> 131 142 AuthType Basic … … 136 147 }}} 137 148 138 If you 're hosting multiple projectsyou can use the same password file for all of them:139 {{{ 149 If you are hosting multiple projects, you can use the same password file for all of them: 150 {{{#!apache 140 151 <LocationMatch "/trac/[^/]+/login"> 141 152 AuthType Basic … … 148 159 See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html mod_auth_basic] documentation. 149 160 150 === Using Digest Authentication ===161 === Using Digest Authentication 151 162 152 163 For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. 153 164 154 You 'llhave to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:155 {{{ 156 #htdigest -c /somewhere/trac.htpasswd trac admin165 You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows: 166 {{{#!sh 167 $ htdigest -c /somewhere/trac.htpasswd trac admin 157 168 }}} 158 169 159 170 The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive: 160 171 161 {{{ 172 {{{#!apache 162 173 <Location "/trac/login"> 163 164 AuthType Digest 165 AuthName "trac" 166 AuthDigestDomain /trac 167 AuthUserFile /somewhere/trac.htpasswd 168 Require valid-user 174 AuthType Digest 175 AuthName "trac" 176 AuthDigestDomain /trac 177 AuthUserFile /somewhere/trac.htpasswd 178 Require valid-user 169 179 </Location> 170 180 }}} … … 172 182 For multiple environments, you can use the same `LocationMatch` as described with the previous method. 173 183 184 '''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. ''' 185 174 186 Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system: 175 {{{ 176 LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so 177 }}} 178 187 {{{#!apache 188 LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so 189 }}} 179 190 180 191 See also the [http://httpd.apache.org/docs/2.2/mod/mod_auth_digest.html mod_auth_digest] documentation. … … 182 193 === Using LDAP Authentication 183 194 184 Configuration for [http://httpd.apache.org/docs/2.2/mod/mod_ldap.html mod_ldap] authentication in Apache is a bit tricky (httpd 2.2.x and OpenLDAP: slapd 2.3.19) 185 186 1. You need to load the following modules in Apache httpd.conf 187 {{{ 188 LoadModule ldap_module modules/mod_ldap.so 189 LoadModule authnz_ldap_module modules/mod_authnz_ldap.so 190 }}} 191 192 2. Your httpd.conf also needs to look something like: 193 194 {{{ 195 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). 196 197 1. You need to load the following modules in Apache httpd.conf: 198 {{{#!apache 199 LoadModule ldap_module modules/mod_ldap.so 200 LoadModule authnz_ldap_module modules/mod_authnz_ldap.so 201 }}} 202 1. Your httpd.conf also needs to look something like: 203 {{{#!apache 195 204 <Location /trac/> 196 205 # (if you're using it, mod_python specific settings go here) … … 206 215 </Location> 207 216 }}} 208 209 210 3. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory: 211 212 213 Use the following as your LDAP URL: 214 {{{ 215 AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)" 216 }}} 217 218 You will also need to provide an account for Apache to use when checking 219 credentials. As this password will be listed in plaintext in the 220 config, you should be sure to use an account specifically for this task: 221 {{{ 222 AuthLDAPBindDN ldap-auth-user@example.com 223 AuthLDAPBindPassword "password" 224 }}} 225 226 The whole section looks like: 227 {{{ 217 1. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL: 218 {{{#!apache 219 AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)" 220 }}} 221 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: 222 {{{#!apache 223 AuthLDAPBindDN ldap-auth-user@example.com 224 AuthLDAPBindPassword "password" 225 }}} 226 The whole section looks like: 227 {{{#!apache 228 228 <Location /trac/> 229 229 # (if you're using it, mod_python specific settings go here) … … 239 239 authzldapauthoritative Off 240 240 # require valid-user 241 require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com 242 </Location> 243 }}} 244 245 Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to Global Catalog Server portion of AD (Notice 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. 246 247 Note 2: You can also require the user be a member of a certain LDAP group, instead of 248 just having a valid login: 249 {{{ 250 Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com 241 Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com 242 </Location> 243 }}} 244 245 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. 246 247 Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login: 248 {{{#!apache 249 Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com 251 250 }}} 252 251 253 252 See also: 254 - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap 255 253 - [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap. 256 254 - [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. 257 255 - [http://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP. … … 259 257 === Using SSPI Authentication 260 258 261 If you are using Apache on Windows, you can use mod_auth_sspi to provide 262 single-sign-on. Download the module from the !SourceForge [http://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the 263 following to your !VirtualHost: 264 {{{ 265 <Location /trac/login> 266 AuthType SSPI 267 AuthName "Trac Login" 268 SSPIAuth On 269 SSPIAuthoritative On 270 SSPIDomain MyLocalDomain 271 SSPIOfferBasic On 272 SSPIOmitDomain Off 273 SSPIBasicPreferred On 274 Require valid-user 275 </Location> 276 }}} 277 278 Using the above, usernames in Trac will be of the form `DOMAIN\username`, so 279 you may have to re-add permissions and such. If you do not want the domain to 280 be part of the username, set `SSPIOmitDomain On` instead. 259 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: 260 {{{#!apache 261 <Location /trac/login> 262 AuthType SSPI 263 AuthName "Trac Login" 264 SSPIAuth On 265 SSPIAuthoritative On 266 SSPIDomain MyLocalDomain 267 SSPIOfferBasic On 268 SSPIOmitDomain Off 269 SSPIBasicPreferred On 270 Require valid-user 271 </Location> 272 }}} 273 274 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. 281 275 282 276 Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338]. … … 291 285 292 286 Here is an example (from the !HttpAuthStore link) using acct_mgr-0.4 for hosting a single project: 293 {{{ 287 {{{#!ini 294 288 [components] 295 289 ; be sure to enable the component … … 302 296 }}} 303 297 This will generally be matched with an Apache config like: 304 {{{ 298 {{{#!apache 305 299 <Location /authFile> 306 300 …HTTP authentication configuration… … … 308 302 </Location> 309 303 }}} 310 Note that '''authFile''' need not exist . See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server.304 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. 311 305 312 306 === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host 313 307 314 Per the mod_wsgi documentation linked to above, here is an example Apache configuration that a) serves the Trac instance from a virtualhost subdomain and b) uses Apache basic authentication for Trac authentication. 315 308 Per the mod_wsgi documentation linked to above, here is an example Apache configuration that: 309 - serves the Trac instance from a virtualhost subdomain 310 - uses Apache basic authentication for Trac authentication. 316 311 317 312 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: 318 313 319 314 Create the htpasswd file: 320 {{{ 315 {{{#!sh 321 316 cd /home/trac-for-my-proj/the-env 322 317 htpasswd -c htpasswd firstuser … … 324 319 htpasswd htpasswd seconduser 325 320 }}} 326 (keep the file above your document root for security reasons) 327 328 Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content s:329 330 {{{ 321 Keep the file above your document root for security reasons. 322 323 Create this file e.g. (ubuntu) `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` with the following content: 324 325 {{{#!apache 331 326 <Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi> 332 327 WSGIApplicationGroup %{GLOBAL} … … 351 346 Note: for subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS. 352 347 353 354 348 == Troubleshooting 355 349 356 350 === Use a recent version 357 351 358 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].352 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]. 359 353 360 354 ''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'' 361 355 362 If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you'll even need version 0.3.4 or greater (see [trac:#10675] for details). 363 364 === Getting Trac to work nicely with SSPI and 'Require Group' === 365 If like me you've 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 its not working your usernames in trac are probably looking like 'DOMAIN\user' rather than 'user'. 366 367 This WSGI script 'fixes' things, hope it helps: 356 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. 357 358 === Getting Trac to work nicely with SSPI and 'Require Group' 359 360 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'. 361 362 This WSGI script 'fixes' that: 368 363 {{{#!python 369 364 import os … … 379 374 }}} 380 375 381 382 === Trac with PostgreSQL === 383 384 When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as a database back-end, the server ''may'' create a lot of open database connections and thus PostgreSQL processes. 385 386 A somewhat brutal workaround is to disabled connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class. 387 388 But it's not necessary to edit the source of Trac, the following lines in `trac.wsgi` will also work: 389 390 {{{ 376 === Trac with PostgreSQL 377 378 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. 379 380 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. 381 382 But it is not necessary to edit the source of Trac. The following lines in `trac.wsgi` will also work: 383 384 {{{#!python 391 385 import trac.db.postgres_backend 392 386 trac.db.postgres_backend.PostgreSQLConnection.poolable = False … … 395 389 or 396 390 397 {{{ 391 {{{#!python 398 392 import trac.db.mysql_backend 399 393 trac.db.mysql_backend.MySQLConnection.poolable = False 400 394 }}} 401 395 402 Now Trac drops the connection after serving a page and the connection count on the database will be kept minimal.396 Now Trac drops the connection after serving a page and the connection count on the database will be kept low. 403 397 404 398 //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.// … … 408 402 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. 409 403 410 411 404 ---- 412 See also: 405 See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe] -
wiki/pages/TracNavigation
r26484 r37343 1 = Trac Navigation =1 = Trac Navigation 2 2 3 Starting with Trac 0.11, it is now possible to customize the main and meta navigation entries in some basic ways. 4 5 The new `[mainnav]` and `[metanav]` configuration sections can now be used to customize the text and link used for the navigation items, or even to disable them. The `mainnav` and `metanav` options in the `[trac]` configuration section can also be used to change the order. 3 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. 6 4 7 5 === `[mainnav]` #mainnav-bar … … 11 9 ** [=#Example Example] ** 12 10 13 In the following example, we rename the link to the Wiki start "Home", and make the "View Tickets" entry link to a specific report. The second example (below) also hides the "!Help/Guide" link. 14 15 Relevant excerpt from the TracIni: 16 {{{ 11 In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report. 12 {{{#!ini 17 13 [mainnav] 18 14 wiki.label = Home … … 21 17 22 18 === `[metanav]` #metanav-bar 23 `[metanav]` corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Log 19 `[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. 24 20 25 There is one special entry in the `[metanav]` section: `logout.redirect` is the page the user sees after hitting the logout button. 21 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. 26 22 [[comment(see also #Trac3808)]] 27 23 28 24 ** Example ** 29 25 30 {{{ 26 {{{#!ini 31 27 [metanav] 32 28 help = disabled … … 35 31 36 32 37 === Notes38 Possible URL formats (for `.href` or `.redirect`):33 === URL Formats 34 Possible URL formats for `.href` or `.redirect`: 39 35 || '''config''' || '''redirect to''' || 40 36 || `wiki/Logout` || `/projects/env/wiki/Logout` || … … 43 39 44 40 45 === `[trac]`#nav-order46 The ` mainnav` and `metanav` options in the `[trac]` configuration section control the order in which the navigation items are displayed (left to right). This can be useful withplugins that add navigation items.41 === Ordering #nav-order 42 The `order` attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items. 47 43 48 ** Example ** 44 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. 49 45 50 In the following example, we change the order to prioritise the ticket related items further left. 46 The default values are: 47 {{{#!ini 48 [mainnav] 49 browser.order = 4 50 newticket.order = 6 51 roadmap.order = 3 52 search.order = 7 53 tickets.order = 5 54 timeline.order = 2 55 wiki.order = 1 51 56 52 Relevant excerpt from the TracIni: 53 {{{ 54 [trac] 55 mainnav = wiki,tickets,newticket,timeline,roadmap,browser,search,admin 57 [metanav] 58 about.order = 5 59 help.order = 4 60 login.order = 1 61 logout.order = 2 62 prefs.order = 3 56 63 }}} 57 58 The default order and item names can be viewed in the [TracIni#trac-section trac section of TracIni].59 64 60 65 === Context Navigation #ctxtnav-bar 61 66 62 Note that it is still not possible to customize the '''contextual navigation bar''', i.e. the one usually placed below the main navigation bar. 63 67 Note that it is still not possible to customize the '''contextual navigation bar''', ie the one usually placed below the main navigation bar. 64 68 65 69 ---- -
wiki/pages/TracNotification
r26484 r37343 1 = Email Notification of Ticket Changes =1 = Email Notification of Ticket Changes 2 2 [[TracGuideToc]] 3 3 … … 8 8 Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini]. 9 9 10 == Receiving Notification Mails == 11 When reporting a new ticket or adding a comment, enter a valid email address or your 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). 12 13 This is useful to keep up-to-date on an issue or enhancement request that interests you. 14 15 === How to use your username to receive notification mails === 16 17 To receive notification mails, you can either enter a full email address or your username. To get notified with a simple username or login, you need to specify a valid email address in the ''Preferences'' page. 18 19 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. 10 == Receiving Notification Mails 11 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. 12 13 === How to use your username to receive notification mails 14 15 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. 16 17 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. 20 18 21 19 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`'''). 22 20 23 == Configuring SMTP Notification == 21 === Ticket attachment notifications 22 23 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: 24 {{{#!ini 25 [components] 26 trac.ticket.notification.TicketAttachmentNotifier = disabled 27 }}} 28 29 == Configuring SMTP Notification 24 30 25 31 '''Important:''' For TracNotification to work correctly, the `[trac] base_url` option must be set in [wiki:TracIni trac.ini]. 26 32 27 === Configuration Options === 28 These are the available options for the `[notification]` section in trac.ini. 29 30 * '''`smtp_enabled`''': Enable email notification. 31 * '''`smtp_from`''': Email address to use for ''Sender''-headers in notification emails. 32 * '''`smtp_from_name`''': Sender name to use for ''Sender''-headers in notification emails. 33 * '''`smtp_from_author`''': (''since 1.0'') Use the author of a change (the reporter of a new ticket, or the author of a comment) as the `From:` header value in notification e-mails (default: false). If the author hasn't set an e-mail address, `smtp_from` and `smtp_from_name` are used instead. 34 * '''`smtp_replyto`''': Email address to use for ''Reply-To''-headers in notification emails. 35 * '''`smtp_default_domain`''': (''since 0.10'') Append the specified domain to addresses that do not contain one. Fully qualified addresses are not modified. The default domain is appended to all username/login for which an email address cannot be found from the user settings. 36 * '''`smtp_always_cc`''': List of email addresses to always send notifications to. ''Typically used to post ticket changes to a dedicated mailing list.'' 37 * '''`smtp_always_bcc`''': (''since 0.10'') List of email addresses to always send notifications to, but keeps addresses not visible from other recipients of the notification email 38 * '''`smtp_subject_prefix`''': (''since 0.10.1'') Text that is inserted before the subject of the email. Set to "!__default!__" by default. 39 * '''`always_notify_reporter`''': Always send notifications to any address in the reporter field (default: false). 40 * '''`always_notify_owner`''': (''since 0.9'') Always send notifications to the address in the owner field (default: false). 41 * '''`always_notify_updater`''': (''since 0.10'') Always send a notification to the updater of a ticket (default: true). 42 * '''`use_public_cc`''': (''since 0.10'') Addresses in To: (owner, reporter) and Cc: lists are visible by all recipients (default is ''Bcc:'' - hidden copy). 43 * '''`use_short_addr`''': (''since 0.10'') Enable delivery of notifications to addresses that do not contain a domain (i.e. do not end with ''@<domain.com>'').This option is useful for intranets, where the SMTP server can handle local addresses and map the username/login to a local mailbox. See also `smtp_default_domain`. Do not use this option with a public SMTP server. 44 * '''`ignore_domains`''': Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains). 45 * '''`mime_encoding`''': (''since 0.10'') This option allows selecting the MIME encoding scheme. Supported values: 46 * `none`: default value, uses 7bit encoding if the text is plain ASCII, or 8bit otherwise. 47 * `base64`: works with any kind of content. May cause some issues with touchy anti-spam/anti-virus engines. 48 * `qp` or `quoted-printable`: best for european languages (more compact than base64) if 8bit encoding cannot be used. 49 * '''`ticket_subject_template`''': (''since 0.11'') A [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet used to get the notification subject. 50 * '''`email_sender`''': (''since 0.12'') Name of the component implementing `IEmailSender`. This component is used by the notification system to send emails. Trac currently provides the following components: 51 * `SmtpEmailSender`: connects to an SMTP server (default). 52 * `SendmailEmailSender`: runs a `sendmail`-compatible executable. 53 54 Either '''`smtp_from`''' or '''`smtp_replyto`''' (or both) ''must'' be set, otherwise Trac refuses to send notification mails. 55 56 The following options are specific to email delivery through SMTP. 57 * '''`smtp_server`''': SMTP server used for notification messages. 58 * '''`smtp_port`''': (''since 0.9'') Port used to contact the SMTP server. 59 * '''`smtp_user`''': (''since 0.9'') User name for authentication SMTP account. 60 * '''`smtp_password`''': (''since 0.9'') Password for authentication SMTP account. 61 * '''`use_tls`''': (''since 0.10'') Toggle to send notifications via a SMTP server using [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS], such as GMail. 62 63 The following option is specific to email delivery through a `sendmail`-compatible executable. 64 * '''`sendmail_path`''': (''since 0.12'') Path to the sendmail executable. The sendmail program must accept the `-i` and `-f` options. 65 66 === Example Configuration (SMTP) === 67 {{{ 33 === Configuration Options 34 These are the available options for the `[notification]` section in trac.ini: 35 36 [[TracIni(notification)]] 37 38 === Example Configuration (SMTP) 39 {{{#!ini 68 40 [notification] 69 41 smtp_enabled = true … … 74 46 }}} 75 47 76 === Example Configuration (`sendmail`) ===77 {{{ 48 === Example Configuration (`sendmail`) 49 {{{#!ini 78 50 [notification] 79 51 smtp_enabled = true … … 85 57 }}} 86 58 87 === Customizing the e-mail subject === 59 === Subscriber Configuration 60 The default subscriptions are configured in the `[notification-subscriber]` section in trac.ini: 61 62 [[TracIni(notification-subscriber)]] 63 64 Each user can override these defaults in his ''Notifications'' preferences. 65 66 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. 67 68 === Customizing the e-mail subject 88 69 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: 89 {{{ 70 {{{#!genshi 90 71 $prefix #$ticket.id: $summary 91 72 }}} … … 95 76 * `prefix`: The prefix defined in `smtp_subject_prefix`. 96 77 * `summary`: The ticket summary, with the old value if the summary was edited. 97 * `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, e .g.`$ticket.milestone`.98 99 === Customizing the e-mail content ===100 101 The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/t emplates`.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:102 103 {{{ 78 * `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`. 79 80 === Customizing the e-mail content 81 82 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: 83 84 {{{#!genshi 104 85 $ticket_body_hdr 105 86 $ticket_props … … 135 116 $project.descr 136 117 }}} 137 == Sample Email == 118 119 == Sample Email 138 120 {{{ 139 121 #42: testing … … 146 128 ---------------------------+------------------------------------------------ 147 129 Changes: 148 * component: chang set view => search system130 * component: changeset view => search system 149 131 * priority: low => highest 150 132 * owner: jonas => anonymous … … 161 143 }}} 162 144 163 164 == Customizing e-mail content for MS Outlook == 165 166 Out-of-the-box, MS Outlook normally presents plain text e-mails with a variable-width font; 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]. 145 == Customizing e-mail content for MS Outlook 146 147 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]. 167 148 168 149 Replace the following second row in the template: … … 171 152 }}} 172 153 173 with this instead (''requires Python 2.6 or later''):154 with this (requires Python 2.6 or later): 174 155 {{{ 175 156 -------------------------------------------------------------------------- … … 185 166 }}} 186 167 187 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.168 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. 188 169 {{{#!div style="margin: 1em 1.75em; border:1px dotted" 189 170 {{{#!html … … 205 186 Changes:<br /> 206 187 <br /> 207 * component: chang set view => search system<br />188 * component: changeset view => search system<br /> 208 189 * priority: low => highest<br /> 209 190 * owner: jonas => anonymous<br /> … … 221 202 }}} 222 203 223 **Important**: Only those ticket fields that are listed in `sel` are part of the HTML mail. If you have defined custom ticket fields which shall be part of the mail they have to be added to `sel`, example:204 **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: 224 205 {{{ 225 206 sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2'] 226 207 }}} 227 208 228 However, it's not as perfect as an automatically HTML-formatted e-mail would be, but presented ticket properties are at least readable by default in MS Outlook... 229 230 231 == Using GMail as the SMTP relay host == 232 233 Use the following configuration snippet 234 {{{ 209 However, the solution is still a workaround to an automatically HTML-formatted e-mail. 210 211 == Using GMail as the SMTP relay host 212 213 Use the following configuration snippet: 214 {{{#!ini 235 215 [notification] 236 216 smtp_enabled = true … … 243 223 }}} 244 224 245 where ''user'' and ''password'' match an existing GMail account, ''i.e.'' the ones you use to log in on [http://gmail.com]225 where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [http://gmail.com]. 246 226 247 227 Alternatively, you can use `smtp_port = 25`.[[br]] 248 You should not use `smtp_port = 465`. It will not work and your ticket submission may deadlock. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [comment:ticket:7107:2 #7107] for details. 249 250 == Filtering notifications for one's own changes == 251 In Gmail, use the filter: 252 253 {{{ 254 from:(<smtp_from>) (("Reporter: <username>" -Changes) OR "Changes (by <username>)") 255 }}} 256 257 For Trac .10, use the filter: 258 {{{ 259 from:(<smtp_from>) (("Reporter: <username>" -Changes -Comment) OR "Changes (by <username>)" OR "Comment (by <username>)") 260 }}} 261 262 to delete these notifications. 263 264 In Thunderbird, there is no such solution if you use IMAP 265 (see http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body). 266 267 The best you can do is to set "always_notify_updater" in conf/trac.ini to false. 268 You will however still get an email if you comment a ticket that you own or have reported. 269 270 You can also add this plugin: 271 http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin 272 273 == Troubleshooting == 228 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. 229 230 == Troubleshooting 274 231 275 232 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. 276 233 277 Notification errors are not reported through the web interface, so the user who submit 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.278 279 === ''Permission denied'' error ===234 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. 235 236 === ''Permission denied'' error 280 237 281 238 Typical error message: 282 {{{ 239 {{{#!sh 283 240 ... 284 241 File ".../smtplib.py", line 303, in connect … … 287 244 }}} 288 245 289 This error usually comes from a security settings on the server: many Linux distributions do not let the web server (Apache, ...) to post email messageto the local SMTP server.246 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. 290 247 291 248 Many users get confused when their manual attempts to contact the SMTP server succeed: 292 {{{ 249 {{{#!sh 293 250 telnet localhost 25 294 251 }}} 295 Th e trouble is thata regular user may connect to the SMTP server, but the web server cannot:296 {{{ 252 This is because a regular user may connect to the SMTP server, but the web server cannot: 253 {{{#!sh 297 254 sudo -u www-data telnet localhost 25 298 255 }}} 299 256 300 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 browsingthe Trac [trac:MailingList MailingList] archive.257 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. 301 258 302 259 Relevant ML threads: … … 304 261 305 262 For SELinux in Fedora 10: 306 {{{ 263 {{{#!sh 307 264 $ setsebool -P httpd_can_sendmail 1 308 265 }}} 309 === ''Suspected spam'' error === 266 267 === ''Suspected spam'' error 310 268 311 269 Some SMTP servers may reject the notification email sent by Trac. 312 270 313 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, it is recommended to change the default encoding to "quoted-printable" using the `mime_encoding` option. 314 315 Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, it is recommended to stick with the Base64 encoding. 316 317 === ''501, 5.5.4 Invalid Address'' error === 318 319 On IIS 6.0 you could get a 320 {{{ 321 Failure sending notification on change to ticket #1: SMTPHeloError: (501, '5.5.4 Invalid Address') 322 }}} 323 in the trac log. Have a look [http://support.microsoft.com/kb/291828 here] for instructions on resolving it. 324 271 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. 272 273 Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding. 325 274 326 275 ---- 327 See also: TracTickets, TracIni, TracGuide 276 See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi] -
wiki/pages/TracPermissions
r26484 r37343 1 = Trac Permissions =1 = Trac Permissions 2 2 [[TracGuideToc]] 3 3 4 4 Trac uses a simple, case sensitive, permission system to control what users can and can't access. 5 5 6 Permission privileges are managed using the [TracAdmin trac-admin] tool or (new in version 0.11)the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.6 Permission privileges are managed using the [TracAdmin trac-admin] tool or the ''General / Permissions'' panel in the ''Admin'' tab of the web interface. 7 7 8 8 In addition to the default permission policy described in this page, it is possible to activate additional permission policies by enabling plugins and listing them in the `[trac] permission_policies` configuration entry in the TracIni. See TracFineGrainedPermissions for more details. … … 11 11 In addition to these privileges, users can be granted additional individual rights in effect when authenticated and logged into the system. All logged in users belong to the virtual group "authenticated", which inherits permissions from "anonymous". 12 12 13 == Graphical Admin Tab == 14 ''This feature is new in version 0.11.'' 15 16 To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_ADD`, `PERMISSION_REMOVE`. The permissions can granted using the `trac-admin` command (more on `trac-admin` below): 13 == Graphical Admin Tab 14 15 To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_GRANT`, `PERMISSION_REVOKE`. The permissions can be granted using the `trac-admin` command (more on `trac-admin` below): 17 16 {{{ 18 17 $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN … … 27 26 An easy way to quickly secure a new Trac install is to run the above command on the anonymous user, install the [http://trac-hacks.org/wiki/AccountManagerPlugin AccountManagerPlugin], create a new admin account graphically and then remove the TRAC_ADMIN permission from the anonymous user. 28 27 29 == Available Privileges == 28 From the graphical admin tab, users with `PERMISSION_GRANT` will only be allowed to grant permissions that they possess, and users with `PERMISSION_REVOKE` will only be allowed to revoke permissions that they possess. For example, a user cannot grant `MILESTONE_ADMIN` unless they have `PERMISSION_GRANT` and `MILESTONE_ADMIN`, and they cannot revoke `MILESTONE_ADMIN` unless they have `PERMISSION_REVOKE` and `MILESTONE_ADMIN`. `PERMISSION_ADMIN` just grants the user both `PERMISSION_GRANT` and `PERMISSION_REVOKE`, and users with `TRAC_ADMIN` can grant or revoke any permission. 29 30 == Available Privileges 30 31 31 32 To enable all privileges for a user, use the `TRAC_ADMIN` permission. Having `TRAC_ADMIN` is like being `root` on a *NIX system: it will allow you to perform any operation. … … 33 34 Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac ('''note that the privilege names are case-sensitive'''): 34 35 35 === Repository Browser ===36 === Repository Browser 36 37 37 38 || `BROWSER_VIEW` || View directory listings in the [wiki:TracBrowser repository browser] || … … 40 41 || `CHANGESET_VIEW` || View [wiki:TracChangeset repository check-ins] || 41 42 42 === Ticket System ===43 === Ticket System 43 44 44 45 || `TICKET_VIEW` || View existing [wiki:TracTickets tickets] and perform [wiki:TracQuery ticket queries] || … … 49 50 || `TICKET_EDIT_CC` || Full modify cc field || 50 51 || `TICKET_EDIT_DESCRIPTION` || Modify description field || 51 || `TICKET_EDIT_COMMENT` || Modify comments||52 || `TICKET_EDIT_COMMENT` || Modify another user's comments. Any user can modify their own comments by default. || 52 53 || `TICKET_BATCH_MODIFY` || [wiki:TracBatchModify Batch modify] tickets || 53 || `TICKET_ADMIN` || All `TICKET_*` permissions, plus the deletion of ticket attachments and modification of the reporter and description fields. It also allows managing ticket properties in the WebAdmin panel. ||54 || `TICKET_ADMIN` || All `TICKET_*` permissions, deletion of ticket attachments and modification of the reporter field, which grants ability to create a ticket on behalf of another user (it will appear that another user created the ticket). It also allows managing ticket properties through the web administration module. || 54 55 55 56 Attention: the "view tickets" button appears with the `REPORT_VIEW` permission. 56 57 57 === Roadmap ===58 === Roadmap 58 59 59 60 || `MILESTONE_VIEW` || View milestones and assign tickets to milestones. || … … 65 66 || `ROADMAP_ADMIN` || to be removed with [trac:#3022 #3022], replaced by MILESTONE_ADMIN || 66 67 67 === Reports ===68 === Reports 68 69 69 70 || `REPORT_VIEW` || View [wiki:TracReports reports], i.e. the "view tickets" link. || … … 74 75 || `REPORT_ADMIN` || All `REPORT_*` permissions || 75 76 76 === Wiki System ===77 === Wiki System 77 78 78 79 || `WIKI_VIEW` || View existing [wiki:TracWiki wiki] pages || … … 83 84 || `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. || 84 85 85 === Permissions ===86 === Permissions 86 87 87 88 || `PERMISSION_GRANT` || add/grant a permission || … … 89 90 || `PERMISSION_ADMIN` || All `PERMISSION_*` permissions || 90 91 91 === Others ===92 === Others 92 93 93 94 || `TIMELINE_VIEW` || View the [wiki:TracTimeline timeline] page || … … 96 97 || `EMAIL_VIEW` || Shows email addresses even if [wiki:TracIni#trac-section trac show_email_addresses] configuration option is false || 97 98 98 == Creating New Privileges ==99 100 To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [wiki:TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation of the component in the admin panel.101 102 == Granting Privileges ==99 == Creating New Privileges 100 101 To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [wiki:TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation on the [wiki:TracIni#extra-permissions-section TracIni] page after enabling the component. 102 103 == Granting Privileges 103 104 104 105 You grant privileges to users using [wiki:TracAdmin trac-admin]. The current set of privileges can be listed with the following command: … … 122 123 }}} 123 124 124 == Permission Groups ==125 == Permission Groups 125 126 126 127 There are two built-in groups, "authenticated" and "anonymous". … … 144 145 Group membership can be checked by doing a {{{permission list}}} with no further arguments; the resulting output will include group memberships. '''Use at least one lowercase character in group names, as all-uppercase names are reserved for permissions'''. 145 146 146 == Adding a New Group and Permissions ==147 == Adding a New Group and Permissions 147 148 Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group. 148 149 … … 154 155 }}} 155 156 156 == Removing Permissions ==157 == Removing Permissions 157 158 158 159 Permissions can be removed using the 'remove' command. For example: … … 175 176 }}} 176 177 177 == Default Permissions ==178 == Default Permissions 178 179 179 180 By default on a new Trac installation, the `anonymous` user will have ''view'' access to everything in Trac, but will not be able to create or modify anything. -
wiki/pages/TracPlugins
r26484 r37343 1 = Trac plugins = 2 [[TracGuideToc]] 3 4 From version 0.9 onwards, Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], with peculiarities described in the [TracDev/PluginDevelopment plugin development] page. 5 6 == Plugin discovery == 7 8 From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in the global shared plugins directory (see [TracIni#GlobalConfiguration Global Configuration]) and in the `plugins` directory of the local TracEnvironment. Components defined in globally-installed plugins should be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the trac.ini file. 9 10 == Requirements for Trac eggs == 11 12 To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version 0.6) installed. 1 [[PageOutline(2-5,Contents,pullout)]] 2 3 = Trac plugins 4 5 Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], with special cases described in the [trac:TracDev/PluginDevelopment plugin development] page. 6 7 == Plugin discovery 8 9 From the user's point of view, a plugin is either a standalone .py file or an .egg package. Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Components defined in globally-installed plugins must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file. Components defined in the `plugins` directory of the project environment are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file. 10 11 == Requirements for Trac eggs 12 13 To use egg-based plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version >= 0.6) installed. 13 14 14 15 To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows: 15 16 16 {{{ 17 {{{#!sh 17 18 $ python ez_setup.py 18 19 }}} 19 20 20 If the `ez_setup.py` script fails to install the setuptools release, you can download it from [ http://www.python.org/pypi/setuptools PyPI] and install it manually.21 If the `ez_setup.py` script fails to install the setuptools release, you can download it from [pypi:setuptools PyPI] and install it manually. 21 22 22 23 Plugins can also consist of a single `.py` file dropped directly into either the project's or the shared `plugins` directory. 23 24 24 == Installing a Trac plugin ==25 26 === For a single project ===25 == Installing a Trac plugin 26 27 === For a single project 27 28 28 29 Plugins are typically packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs]. That means they are .zip archives with the file extension `.egg`. … … 32 33 * Unpack the source. It should provide `setup.py`. 33 34 * Run: 34 35 {{{ 35 {{{#!sh 36 36 $ python setup.py bdist_egg 37 37 }}} 38 38 39 You should have a *.egg file. Examine the output of running python to find where this was created.40 41 Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd (kill and run again).39 You should now have an *.egg file. Examine the output of running Python to find where this was created. 40 41 Once you have the plugin archive, copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then restart the web server. If you are running as a [wiki:TracStandalone "tracd" standalone server], restart tracd, ie kill the process and run again. 42 42 43 43 To uninstall a plugin installed this way, remove the egg from the `plugins` directory and restart the web server. 44 44 45 Note: the Python version that the egg is built with ''must'' match the Python version with which Trac is run. For example, if you're running Trac under Python 2.5, but have upgraded your standalone Python to 2.6, the eggs won't be recognized. 46 47 Note also: in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need; since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below), and then enable them selectively on a project-by-project basis. 48 49 === For all projects === 50 51 ==== With an .egg file ==== 52 53 Some plugins (such as [trac:SpamFilter SpamFilter]) are downloadable as an `.egg` file that can be installed with the `easy_install` program: 54 {{{ 55 easy_install TracSpamFilter 56 }}} 57 58 If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python24\Scripts`) to their `PATH` environment variable (see [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information). 59 60 If Trac reports permission errors after installing a zipped egg, and you would rather not bother providing a egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass `--always-unzip` to `easy_install`: 61 {{{ 62 easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg 63 }}} 64 You should end up with a directory having the same name as the zipped egg (complete with `.egg` extension) and containing its uncompressed contents. 65 66 Trac also searches for plugins installed in the shared plugins directory ''(since 0.10)''; see TracIni#GlobalConfiguration. This is a convenient way to share the installation of plugins across several, but not all, environments. 67 68 ==== From source ==== 45 '''Note''': the Python version that the egg is built with ''must'' match the Python version with which Trac is run. For example, if you are running Trac under Python 2.6, but have upgraded your standalone Python to 2.7, the eggs won't be recognized. 46 47 '''Note''': in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need; since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below), and then enable them selectively on a project-by-project basis. 48 49 === For all projects 50 51 ==== With an .egg file 52 53 Some plugins, such as [trac:SpamFilter SpamFilter], are downloadable as an `.egg` file that can be installed with `easy_install` or `pip`: 54 {{{#!sh 55 $ easy_install TracSpamFilter 56 $ pip install TracSpamFilter 57 }}} 58 59 If `easy_install` is not on your system, see the Requirements section above to install it. Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python27\Scripts`) to their `PATH` environment variable, or use the full path to `easy_install` (for example, `C:\Python27\Scripts\easy_install.py`). See [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install Windows notes] for more information. 60 61 `pip` is included in Python 2.7.9. In earlier versions of Python it can be installed through the package manager of your OS (e.g. `apt-get install python-pip`) or using the [https://pip.pypa.io/en/latest/installing.html#install-pip get_pip.py]. 62 63 If Trac reports permission errors after installing a zipped egg, and you would rather not bother providing an egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass `--always-unzip` to `easy_install`: 64 {{{#!sh 65 $ easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg 66 }}} 67 You should end up with a directory having the same name as the zipped egg, complete with `.egg` extension, and containing its uncompressed contents. 68 69 Trac also searches for plugins installed in the shared plugins directory, see TracIni#GlobalConfiguration. This is a convenient way to share the installation of plugins across several, but not all, environments. 70 71 ==== From source 69 72 70 73 `easy_install` makes installing from source a snap. Just give it the URL to either a Subversion repository or a tarball/zip of the source: 71 {{{ 72 easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha73 }}} 74 75 ==== Enabling the plugin ====76 77 Unlike plugins installed per -environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, i.e.the path specified in the `[inherit] plugins_dir` configuration option.78 79 This is done in the `[components]` section of the configuration file . For example:80 {{{ 74 {{{#!sh 75 $ easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha 76 }}} 77 78 ==== Enabling the plugin 79 80 Unlike plugins installed per environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This also applies to plugins installed in the shared plugins directory, ie the path specified in the `[inherit] plugins_dir` configuration option. 81 82 This is done in the `[components]` section of the configuration file `trac.ini`. For example: 83 {{{#!ini 81 84 [components] 82 85 tracspamfilter.* = enabled 83 86 }}} 84 87 85 The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source (look for a top-level directory that contains a file named `__init__.py`).86 87 Note:After installing the plugin, you must restart your web server.88 89 ==== Uninstalling ====90 91 `easy_install` or `python setup.py` does not have an uninstall feature. Hower, it is usually quite trivial to remove a globally-installed egg and reference:88 The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source: look for a top-level directory that contains a file named `__init__.py`. 89 90 After installing the plugin, you must restart your web server. 91 92 ==== Uninstalling 93 94 Neither `easy_install` nor `python setup.py` have an uninstall feature. However, it is usually trivial to remove a globally installed egg and reference: 92 95 93 96 1. Do `easy_install -m [plugin name]` to remove references from `$PYTHONLIB/site-packages/easy-install.pth` when the plugin installed by setuptools. 94 97 1. Delete executables from `/usr/bin`, `/usr/local/bin`, or `C:\\Python*\Scripts`. To find what executables are involved, refer to the `[console-script]` section of `setup.py`. 95 1. Delete the .egg file or folder from where it's installed (usually inside `$PYTHONLIB/site-packages/`).98 1. Delete the .egg file or folder from where it's installed, usually inside `$PYTHONLIB/site-packages/`. 96 99 1. Restart the web server. 97 100 98 If you are uncertain about the location of the egg , here's a small tip to help locate an egg (or any package). Just replace`myplugin` with whatever namespace the plugin uses (as used when enabling the plugin):99 {{{ 101 If you are uncertain about the location of the egg file, you can try to locate it by replacing `myplugin` with whatever namespace the plugin uses (as used when enabling the plugin): 102 {{{#!pycon 100 103 >>> import myplugin 101 104 >>> print myplugin.__file__ … … 103 106 }}} 104 107 105 == Setting up the plugin cache ==106 107 Some plugins will need to be extracted by the Python egg s runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.108 == Setting up the plugin cache 109 110 Some plugins will need to be extracted by the Python egg's runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable. 108 111 109 112 To do this from the Apache configuration, use the `SetEnv` directive: 110 {{{ 113 {{{#!apache 111 114 SetEnv PYTHON_EGG_CACHE /path/to/dir 112 115 }}} 113 116 114 This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], i .e.in the same `<Location>` block.115 116 For example (for CGI):117 {{{ 117 This works whether you're using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], ie in the same `<Location>` block. 118 119 For example for CGI: 120 {{{#!apache 118 121 <Location /trac> 119 122 SetEnv TRAC_ENV /path/to/projenv … … 122 125 }}} 123 126 124 Or (for mod_python):125 {{{ 127 Or for mod_python: 128 {{{#!apache 126 129 <Location /trac> 127 130 SetHandler mod_python … … 131 134 }}} 132 135 133 ''Note: !SetEnv requires the `mod_env` module which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.'' 136 '''Note''': !SetEnv requires the `mod_env` module, which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block. 134 137 135 138 For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables. 136 139 137 ''Note: that if you already use -initial-env to set the project directory for either a single project or parent you will need to add an additional -initial-env directive to the !FastCgiConfig directive. I.e. 138 139 {{{ 140 '''Note''': if you already use -initial-env to set the project directory for either a single project or parent, you will need to add an additional -initial-env directive to the !FastCgiConfig directive: 141 142 {{{#!apache 140 143 FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache 141 144 }}} 142 145 143 === About hook scripts === 144 145 If you've set up some subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well. 146 147 == Troubleshooting == 148 149 === Is setuptools properly installed? === 150 151 Try this from the command line: 152 {{{ 153 $ python -c "import pkg_resources" 154 }}} 155 156 If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac. 157 158 === Did you get the correct version of the Python egg? === 159 160 Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6). 161 162 Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead. 163 164 === Is the plugin enabled? === 165 166 If you install a plugin globally (i.e., ''not'' inside the `plugins` directory of the Trac project environment), you must explicitly enable it in [TracIni trac.ini]. Make sure that: 167 168 * ...you actually added the necessary line(s) to the `[components]` section. 169 * ...the package/module names are correct. 170 * ...the value is "enabled", not "enable" or "Enable". 171 172 === Check the permissions on the .egg file === 173 174 Trac must be able to read the .egg file. 175 176 === Check the log files === 177 178 Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins. 179 180 === Verify you have proper permissions === 181 182 Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have TRAC_ADMIN permissions for it to show up on the navigation bar. 183 184 === Is the wrong version of the plugin loading? === 185 186 If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules: 187 188 * Only one version of the plugin can be loaded for each running Trac server (i.e., each Python process). The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference. 189 * A globally-installed plugin (typically `setup.py install`) will override any version in the global or project plugins directories. A plugin from the global plugins directory will be located ''before'' any project plugins directory. 190 * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give uncertain results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request. 191 * Having more than one version listed inside Python site-packages is fine (i.e., installed with `setup.py install`) -- setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory -- neither version number nor installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins. 192 193 === If all of the above failed === 194 195 Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away! 196 197 == Web-based plugin administration == 198 199 The WebAdmin plugin (part of the core since 0.11) offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission: 146 === About hook scripts 147 148 If you have set up some Subversion hook scripts that call the Trac engine, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well. 149 150 == Web-based plugin administration 151 152 The [trac:WebAdmin] interface offers limited support for plugin configuration through the web to users with `TRAC_ADMIN` permission: 200 153 201 154 * en/disabling installed plugins 202 155 * installing plugins by uploading them as eggs 203 156 204 You probably want to disable the second function for security reasons: in `trac.ini`, in the `[components]` section, add the line 205 {{{ 157 If you wish to disable the second function for security reasons, add the following to your `trac.ini` file: 158 {{{#!ini 159 [components] 206 160 trac.admin.web_ui.PluginAdminPanel = disabled 207 161 }}} 208 162 This disables the whole panel, so the first function will no longer be available either. 163 164 == Troubleshooting 165 166 === Is setuptools properly installed? 167 168 Try this from the command line: 169 {{{#!sh 170 $ python -c "import pkg_resources" 171 }}} 172 173 If you get '''no output''', setuptools '''is''' installed. Otherwise, you'll need to install it before plugins will work in Trac. 174 175 === Did you get the correct version of the Python egg? 176 177 Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6). 178 179 Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead. 180 181 === Is the plugin enabled? 182 183 If you install a plugin globally, ie ''not'' inside the `plugins` directory of the Trac project environment, you must explicitly enable it in [TracIni trac.ini]. Make sure that: 184 185 * you actually added the necessary line(s) to the `[components]` section. 186 * the package/module names are correct and do not contain typos. 187 * the value is "enabled", not "enable" or "Enable". 188 * the section name is "components", not "component". 189 190 === Check the permissions on the .egg file 191 192 Trac must be able to read the .egg file. 193 194 === Check the log files 195 196 Enable [wiki:TracLogging logging] and set the log level to `DEBUG`, then watch the log file for messages about loading plugins. 197 198 === Verify you have the proper permissions 199 200 Some plugins require you have special permissions in order to use them. [trac:WebAdmin WebAdmin], for example, requires the user to have `TRAC_ADMIN` permissions for it to show up on the navigation bar. 201 202 === Is the wrong version of the plugin loading? 203 204 If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules: 205 206 * Only one version of the plugin can be loaded for each running Trac server, ie each Python process. The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference. 207 * A globally installed plugin (typically `setup.py install`) will override any version in the global or project plugins directories. A plugin from the global plugins directory will be located ''before'' any project plugins directory. 208 * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give unpredicatable results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request. 209 * Having more than one version listed inside Python site-packages is fine, ie installed with `setup.py install`, because setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory: neither the version number nor the installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins. 210 211 === If all of the above failed 212 213 Okay, so the logs don't mention plugins, the egg is readable, the Python version is correct, ''and'' the egg has been installed globally (and is enabled in trac.ini)... and it ''still'' doesn't work or give any error messages or any other indication as to why. Hop on the [trac:IrcChannel IrcChannel] and ask away! 209 214 210 215 ---- -
wiki/pages/TracQuery
r26484 r37343 1 = Trac Ticket Queries =1 = Trac Ticket Queries 2 2 [[TracGuideToc]] 3 3 4 In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', used to display lists of tickets meeting a specified set ofcriteria.4 In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', which can be used to display tickets that meet specified criteria. 5 5 6 6 To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link. 7 7 8 == Filters ==8 == Filters 9 9 10 When you first go to the query page the default filter will display tickets relevant to you:11 * If logged in then all open tickets it will display open tickets assigned to you.12 * 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.13 * If not logged and no name/email defined in the preferencesthen all open issues are displayed.10 When you first go to the query page, the default filter will display tickets relevant to you: 11 * If logged in then all open tickets, it will display open tickets assigned to you. 12 * 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. 13 * If not logged in and no name/email is defined in the preferences, then all open issues are displayed. 14 14 15 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'' ofthe criteria.15 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. 16 16 17 17 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. 18 18 19 Once you've edited your filtersclick the ''Update'' button to refresh your results.19 After you have edited your filters, click the ''Update'' button to refresh your results. 20 20 21 == Navigating Tickets == 22 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. 21 == Navigating Tickets 23 22 24 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(<span style="color: grey">it no longer matches the query criteria </span>)]] the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold. 23 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. 24 25 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(<span style="color: grey">it no longer matches the query criteria </span>)]], the text will also be greyed. Lastly, if '''a new ticket matching the query criteria has been created''', it will be shown in bold. 25 26 26 27 The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again. 27 28 28 == Saving Queries ==29 == Saving Queries 29 30 30 31 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. 31 32 You can also save references to queries in Wiki content, as described below. 32 33 33 '' 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.34 '''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. 34 35 35 '' 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.36 '''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. 36 37 38 === Using TracLinks 37 39 38 === Using TracLinks === 39 40 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. 40 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. 41 41 {{{ 42 42 [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0] … … 46 46 [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0] 47 47 48 This uses a very simple query language to specify the criteria (see [wiki:TracQuery#QueryLanguage Query Language]).48 This uses a very simple query language to specify the criteria, see [wiki:TracQuery#QueryLanguage Query Language]. 49 49 50 50 Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading `?` character: … … 56 56 [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner] 57 57 58 === Using the `[[TicketQuery]]` Macro ===58 === Customizing the ''table'' format 59 59 60 The [trac:TicketQuery TicketQuery] macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting. 61 62 Example: 63 {{{ 64 [[TicketQuery(version=0.6|0.7&resolution=duplicate)]] 65 }}} 66 67 This is displayed as: 68 [[TicketQuery(version=0.6|0.7&resolution=duplicate)]] 69 70 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 allows displaying the link and description of a single ticket: 71 {{{ 72 [[TicketQuery(id=123)]] 73 }}} 74 75 This is displayed as: 76 [[TicketQuery(id=123)]] 77 78 A more compact representation without the ticket summaries is also available: 79 {{{ 80 [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]] 81 }}} 82 83 This is displayed as: 84 [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]] 85 86 Finally, if you wish to receive only the number of defects that match the query, use the ``count`` parameter. 87 88 {{{ 89 [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]] 90 }}} 91 92 This is displayed as: 93 [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]] 94 95 === Customizing the ''table'' format === 96 You can also customize the columns displayed in the table format (''format=table'') by using ''col=<field>'' - you can specify multiple fields and what order they are displayed by placing pipes (`|`) between the columns like below: 97 60 You can also customize the columns displayed in the table format (''format=table'') by using ''col=<field>''. You can specify multiple fields and what order they are displayed in by placing pipes (`|`) between the columns: 98 61 {{{ 99 62 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]] … … 103 66 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]] 104 67 105 ==== Full rows ==== 106 In ''table'' format you can also have full rows by using ''rows=<field>'' like below: 68 ==== Full rows 107 69 70 In ''table'' format you can also have full rows by using ''rows=<field>'': 108 71 {{{ 109 72 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]] … … 113 76 [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]] 114 77 78 == Query Language 115 79 116 === Query Language === 117 118 `query:` TracLinks and the `[[TicketQuery]]` macro both use a mini “query language” for specifying query filters. Basically, the filters are separated by ampersands (`&`). Each filter then 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 (`\`). 80 `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 (`\`). 119 81 120 82 The available operators are: … … 130 92 || '''`!$=`''' || the field content does not end with any of the values || 131 93 132 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 left outto avoid having to quote the query string.94 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. 133 95 || '''`created=2007-01-01..2008-01-01`''' || query tickets created in 2007 || 134 96 || '''`created=lastmonth..thismonth`''' || query tickets created during the previous month || … … 137 99 138 100 ---- 139 See also: TracTickets, TracReports, TracGuide 101 See also: TracTickets, TracReports, TracGuide, TicketQuery -
wiki/pages/TracReports
r26484 r37343 30 30 31 31 == Changing Report Numbering == 32 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 ''(since 0.10)'':32 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: 33 33 * id integer PRIMARY KEY 34 34 * author text … … 47 47 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. 48 48 49 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). ''(since 0.11)''49 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). 50 50 51 51 == Alternative Download Formats == … … 109 109 }}} 110 110 111 Dynamic variables can also be used in the report title and description (since 1.1.1). 111 112 112 113 == Advanced Reports: Dynamic Variables == … … 136 137 }}} 137 138 138 Dynamic variables can also be used in the report title and description (since 1.1.1).139 139 140 140 === !Special/Constant Variables === … … 164 164 * '''id''' — same as '''ticket''' above when '''realm''' is not set 165 165 * '''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) 166 - 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 166 167 * '''created, modified, date, time''' — Format cell as a date and/or time. 167 168 * '''description''' — Ticket description field, parsed through the wiki engine. … … 245 246 === Reporting on custom fields === 246 247 247 If you have added custom fields to your tickets ( a feature since v0.8,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.248 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. 248 249 249 250 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. -
wiki/pages/TracRepositoryAdmin
r26484 r37343 1 = Repository Administration =1 = Repository Administration 2 2 [[PageOutline(2-3)]] 3 3 4 == Quick start == #QuickStart 5 6 * Manage repositories in the "Repository" admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. 4 == Quick start #QuickStart 5 6 * Enable the repository connector(s) for the version control system(s) that you will use. 7 * Add repositories through the //Repositories// admin panel, with `trac-admin` or in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. 7 8 * 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. 8 * Set the `[trac] repository_sync_per_request` option to an empty value to disable per-request syncing. 9 * Make sure the user under which your Subversion hooks are run has write access to the Trac environment, or use a tool like `sudo` to temporarily elevate privileges. 10 11 == Specifying repositories == #Repositories 12 Starting with 0.12, Trac can handle more than one repository per environment. The pre-0.12 way of specifying the repository with the `repository_dir` and `repository_type` options in the `[trac]` section of [wiki:TracIni trac.ini] is still supported, but two new mechanisms allow including additional repositories into an environment. 13 14 It is also possible to define aliases of repositories, that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking all the links to the old name. 15 16 A number of attributes can be associated with each repository, which define the repository's location, type, name and how it is displayed in the source browser. The following attributes are supported: 9 * 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. 10 11 == Enabling the components 12 13 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. 14 15 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. 16 17 {{{#!ini 18 tracopt.versioncontrol.svn.* = enabled 19 }}} 20 21 {{{#!ini 22 tracopt.versioncontrol.git.* = enabled 23 }}} 24 25 == Specifying repositories #Repositories 26 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. 27 28 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. 29 30 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: 17 31 18 32 ||='''Attribute''' =||='''Description''' =|| … … 24 38 ||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. || 25 39 ||`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. || 40 ||`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`.|| 26 41 ||`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. || 27 42 ||`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. || … … 29 44 A repository `name` and one of `alias` or `dir` attributes are mandatory. All others are optional. 30 45 46 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. 47 31 48 After adding a repository, the cache for that repository must be re-synchronized once with the `trac-admin $ENV repository resync` command. 32 49 … … 35 52 36 53 37 === In `trac.ini` ===#ReposTracIni54 === In `trac.ini` #ReposTracIni 38 55 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. 39 56 … … 41 58 42 59 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. 43 {{{ 44 #!ini 60 {{{#!ini 45 61 [repositories] 46 62 project.dir = /var/repos/project … … 59 75 Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around. 60 76 61 === In the database ===#ReposDatabase77 === In the database #ReposDatabase 62 78 Repositories can also be specified in the database, using either the "Repositories" admin panel under "Version Control", or the `trac-admin $ENV repository` commands. 63 79 … … 80 96 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. 81 97 82 83 == Repository synchronization == #Synchronization 98 == Repository caching 99 100 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. 101 102 Subversion repositories are cached unless the type is `direct-svnfs`. Git repositories are cached when `[git]` [wiki:TracIni#git-section cached_repository] is `true`. 103 104 == Repository synchronization #Synchronization 84 105 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. 85 106 86 107 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. 87 108 88 === Mercurial Repositories ===109 === Mercurial Repositories 89 110 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. 90 111 91 === Explicit synchronization ===#ExplicitSync92 This is the preferred method of repository synchronization. It requires setting the ` [trac] repository_sync_per_request` option in [wiki:TracIni#trac-section trac.ini] to an empty value, 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-changehook as well.112 === Explicit synchronization #ExplicitSync 113 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. 93 114 94 115 `changeset added <repos> <rev> [...]`:: … … 100 121 The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository. 101 122 102 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. 123 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. 124 125 ==== Subversion 103 126 104 127 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`): … … 108 131 /usr/bin/trac-admin /path/to/env changeset added "$1" "$2" 109 132 }}} 110 Note: Ubuntu doesn't seem to like /usr/bin/trac-admin, so just use: 111 {{{#!sh 112 #!/bin/sh 113 export PYTHON_EGG_CACHE="/path/to/dir" 114 trac-admin /path/to/env/ changeset added "$1" "$2" 115 }}} 133 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. 116 134 On Windows (`post-commit.cmd`): 117 {{{#! application/x-dos-batch135 {{{#!bat 118 136 @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2" 119 137 }}} … … 126 144 }}} 127 145 On Windows (`post-revprop-change.cmd`): 128 {{{#! application/x-dos-batch146 {{{#!bat 129 147 @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2" 130 148 }}} … … 136 154 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. 137 155 138 Git hooks can be used in the same way for explicit syncing of git repositories. Add the following to `.git/hooks/post-commit`: 139 {{{#!sh 140 REV=$(git rev-parse HEAD) 141 trac-admin /path/to/env changeset added <my-repository> $REV 142 }}} 156 ==== Git 157 158 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): 159 {{{#!sh 160 #!/bin/sh 161 REV=$(git rev-parse HEAD) 162 trac-admin /path/to/env changeset added <repos> $REV 163 }}} 164 165 Alternately, if your repository is one that only gets pushed to, add the following to the `hooks/post-receive` file in the repo: 166 {{{#!sh 167 #!/bin/sh 168 tracenv=/path/to/env # change with your Trac environment's path 169 repos= # change with your repository's name 170 while read oldrev newrev refname; do 171 if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then 172 git rev-list --reverse "$newrev" -- 173 else 174 git rev-list --reverse "$newrev" "^$oldrev" -- 175 fi | xargs trac-admin "$tracenv" changeset added "$repos" 176 done 177 }}} 178 179 The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository. 180 181 ==== Mercurial 143 182 144 183 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): … … 158 197 }}} 159 198 160 === Per-request synchronization ===#PerRequestSync161 If the post-commit hooks are not available, the environment can be set up for per-request synchronization. In that case, the ` [trac] repository_sync_per_request` option in [wiki:TracIni#trac-section trac.ini] must be set to a comma-separated list of repository names to be synchronized.199 === Per-request synchronization #PerRequestSync 200 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`. 162 201 163 202 Note that in this case, the changeset listener extension point is not called, and therefore plugins using it will not work correctly. 164 203 165 166 == Migration from a single-repository setup (Subversion) == #Migration 167 The following procedure illustrates a typical migration from a Subversion single-repository setup to multiple repositories. 168 169 1. Remove the default repository specification from the `[trac] repository_dir` option. 170 1. Add the main repository as a named repository. 171 1. Re-synchronize the main repository. 172 1. Set up post-commit and post-revprop-change hooks on the "main" repository, and set `[trac] repository_sync_per_request` to an empty value. 173 1. Add an alias to the main repository as the default repository (by leaving out the the `name`, e.g. `.alias = main`). This ensures that all links predating the migration still resolve to the main repository. 174 1. Repeat steps 2, 3 and 4 to add other "named" repositories as needed. 175 176 == Migration from a single-repository setup (Mercurial) == #MigrationMercurial 177 The following procedure illustrates a typical migration from a Mercurial single-repository setup to multiple repositories. Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:ticket:9485 #9485] for more information. 178 179 1. Upgrade to the latest version of the TracMercurial plugin. 180 1. Remove the default repository specification from the `[trac] repository_dir` option. 181 1. Add the main repository as a named repository. 182 1. Add an alias to the main repository as the default repository (by leaving out the the `name`, e.g. `.alias = main`). This ensures that all links predating the migration still resolve to the main repository. 183 1. Repeat step 3 to add other "named" repositories as needed. 184 185 == Troubleshooting == 186 187 === My trac-post-commit-hook doesn't work anymore === #trac-post-commit-hook 204 == Automatic changeset references in tickets 205 206 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: 207 * '''`Refs #123`''' - to reference this changeset in `#123` ticket 208 * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed'' 209 210 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. 211 {{{#!ini 212 tracopt.ticket.commit_updater.* = enabled 213 }}} 214 For more information, see the documentation of the `CommitTicketUpdater` component in the //Plugins// admin panel and the [trac:CommitTicketUpdater] page. 215 216 == Troubleshooting 217 218 === My trac-post-commit-hook doesn't work anymore #trac-post-commit-hook 188 219 189 220 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
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 When you browse the repository, it's always possible to query the 5 ''Revision Log'' view corresponding to the path you're currently seeing. 6 This will display a list of the most recent changesets in which the 7 current path or any other path below it has been modified. 4 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. 8 5 9 6 == The Revision Log Form == 10 7 11 It's possible to set the revision at which the revision log should 12 start, using the ''View log starting at'' field. An empty value 13 or a value of ''head'' is taken to be the newest changeset. 8 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. 14 9 15 It's also possible to specify the revision at which the log should 16 stop, using the ''back to'' field. By default, it's left empty, 17 which means the revision log will stop as soon as 100 revisions have 18 been listed. 10 It is also possible to specify the revision at which the log should stop, using the ''Back to'' field. By default it is empty, 11 which means the revision log will show the latest 100 revisions. 19 12 20 13 Also, there are three modes of operation of the revision log. 21 14 22 By default, the revision log ''stops on copy'', which means that 23 whenever an ''Add'', ''Copy'' or ''Rename'' operation is detected, 24 no older revision will be shown. That's very convenient when working 25 with branches, as one only sees the history corresponding to what 26 has been done on the branch. 15 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. 27 16 28 It's also possible to indicate that one wants to see what happened 29 before a ''Copy'' or ''Rename'' change, by selecting the 17 It is also possible to indicate that one wants to see what happened before a ''Copy'' or ''Rename'' change, by selecting the 30 18 ''Follow copies'' mode. This will cross all copies or renames changes. 31 Each time the name of the path changes, there will be an additional 32 indentation level. That way, the changes on the different paths 33 are easily grouped together visually. 19 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. 34 20 35 It's even possible to go past an ''Add'' change, in order to see 36 if there has been a ''Delete'' change on that path, before 37 that ''Add''. This mode corresponds to the mode called 38 ''Show only adds, moves and deletes''. 39 While quite useful at times, be aware that this operation is quite 40 resource intensive. 21 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 22 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. 41 23 42 Finally, there's also a checkbox ''Show full log messages'', 43 which controls whether the full content of the commit log message 24 Finally, there's also a checkbox ''Show full log messages'', which controls whether the full content of the commit log message 44 25 should be displayed for each change, or only a shortened version of it. 45 26 46 27 == The Revision Log Information == 47 28 48 For each revision log entry, the re are 7 columns:29 For each revision log entry, the following columns are displayed: 49 30 1. The first column contains a pair of radio buttons and should be used 50 31 for selecting the ''old'' and the ''new'' revisions that will be … … 68 49 == Inspecting Changes Between Revisions == 69 50 70 The ''View changes...'' buttons (placed above and below the list 71 of changes, on the left side) will show the set of differences 72 corresponding to the aggregated changes starting from the ''old'' 73 revision (first radio-button) to the ''new'' revision (second 51 The ''View changes...'' buttons (placed above and below the list of changes, on the left side) will show the set of differences 52 corresponding to the aggregated changes starting from the ''old'' revision (first radio-button) to the ''new'' revision (second 74 53 radio-button), in the TracChangeset view. 75 54 76 Note that the ''old'' revision doesn't need to be actually 77 ''older'' than the ''new'' revision: it simply gives a base 78 for the diff. It's therefore entirely possible to easily 79 generate a ''reverse diff'', for reverting what has been done 55 Note that the ''old'' revision doesn't need to be actually ''older'' than the ''new'' revision: it simply gives a base 56 for the diff. It's therefore entirely possible to easily generate a ''reverse diff'', for reverting what has been done 80 57 in the given range of revisions. 81 58 82 Finally, if the two revisions are identical, the corresponding 83 changeset will be shown (same effect as clicking on the !ChangeSet number). 59 Finally, if the two revisions are identical, the corresponding changeset will be shown. This has the same effect as clicking on the !ChangeSet number. 84 60 85 61 == Alternative Formats == … … 87 63 === The !ChangeLog Text === 88 64 89 At the bottom of the page, there's a ''!ChangeLog'' link 90 that will show the range of revisions as currently shown, 91 but as a simple text, matching the usual conventions for 92 !ChangeLog files. 65 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. 93 66 94 67 === RSS Support === 95 68 96 The revision log also provides a RSS feed to monitor the changes. 97 To subscribe to a RSS feed for a file or directory, open its 98 revision log in the browser and click the orange 'XML' icon at the bottom 99 of the page. For more information on RSS support in Trac, see TracRss. 69 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 70 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. 100 71 101 72 ---- -
wiki/pages/TracRoadmap
r26484 r37343 1 = The Trac Roadmap =1 = The Trac Roadmap 2 2 [[TracGuideToc]] 3 3 4 4 The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project. 5 5 6 == The Roadmap View ==6 == The Roadmap View 7 7 8 Basically, the roadmap is just a list of future milestones. 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.8 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. 9 9 10 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. 10 == The Milestone View 11 11 12 == The Milestone View == 13 14 You can add a description for each milestone (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. 12 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. 15 13 16 14 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. 17 15 18 == Roadmap Administration ==16 == Roadmap Administration 19 17 20 18 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`. … … 22 20 '''Note:''' Milestone descriptions can not currently be edited using 'trac-admin'. 23 21 24 == iCalendar Support ==22 == iCalendar Support 25 23 26 24 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 … … 28 26 * the cross-platform [http://www.mozilla.org/projects/calendar/ Mozilla Calendar] 29 27 * [http://chandlerproject.org Chandler] 30 * [http://kontact.kde.org/korganizer/ Korganizer] (the calendar application of the [http://www.kde.org/ KDE] project)31 * [http ://www.novell.com/de-de/products/desktop/features/evolution.html Evolution] also support iCalendar32 * [http://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files (it appears as a new static calendar in Outlook)28 * [http://kontact.kde.org/korganizer/ Korganizer], the calendar application of the [http://www.kde.org/ KDE] project 29 * [https://wiki.gnome.org/Apps/Evolution Evolution] 30 * [http://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files and appears as a new static calendar in Outlook 33 31 * [https://www.google.com/calendar/ Google Calendar] 34 32 35 33 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. 36 34 37 '''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.35 '''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. 38 36 39 37 '''Note:''' To include the milestones in Google Calendar you might need to rewrite the URL. -
wiki/pages/TracRss
r26484 r37343 1 = Using RSS with Trac =1 = Using RSS with Trac 2 2 [[TracGuideToc]] 3 3 4 Several of the Trac modules support content syndication using the RSS (Really Simple Syndication) XML format. 5 Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file. 4 Several of the Trac modules support content syndication using the RSS ([http://en.wikipedia.org/wiki/RSS Really Simple Syndication]) XML format. RSS pushes out updates to Trac whenever they occur and to whoever has subscribed to it. Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file. 6 5 7 6 Trac supports RSS feeds in: 8 7 9 * TracTimeline — Use the RSS feed to '''subscribe to project events'''.[[br]]Monitor overall project progress in your favorite RSS reader.10 * TracTickets, TracReports, and TracQuery — Allows syndication of report and ticket query results. [[br]]Be notified about important and relevant issue tickets.11 * TracBrowser and TracRevisionLog — Syndication of file changes. [[br]]Stay up to date with changes to a specific file or directory.8 * TracTimeline — Use the RSS feed to '''subscribe to project events'''. Monitor overall project progress in your favorite RSS reader. 9 * TracTickets, TracReports, and TracQuery — Allows syndication of report and ticket query results. Be notified about important and relevant issue tickets. 10 * TracBrowser and TracRevisionLog — Syndication of file changes. Stay up to date with changes to a specific file or directory. 12 11 13 == How to access RSS data == 14 Anywhere in Trac where RSS is available, you should find a small orange '''XML''' icon, typically placed at the bottom of the page. Clicking the icon will access the RSS feed for that specific resource. 12 == How to access RSS data 13 Anywhere in Trac where RSS is available, you should find a small orange '''RSS''' icon, typically at the bottom of the page: 14 {{{#!html 15 <a rel="nofollow" style="padding-left: 20px; background: url(../../chrome/common/feed.png) left center no-repeat; border: none;"><span style="color: #666;padding: 0 0 2px; font-size: 11px;">RSS feed</span></a> 16 }}} 17 Clicking the icon will access the RSS feed for that specific resource. 15 18 16 '''Note:''' Different modules provide different data in their RSS feeds. Usually ,the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an ''alternate view of the data currently displayed''.19 '''Note:''' Different modules provide different data in their RSS feeds. Usually the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an ''alternate view of the data currently displayed''. 17 20 18 == Links == 21 Since Trac 1.0 an RSS feed can be retrieved from a Trac site that requires authentication. Hover over the RSS icon, right click and //copy link address//. 22 23 == Links 19 24 * ''Specifications:'' 20 * http://blogs.law.harvard.edu/tech/rss — RSS 2.0 Specification 25 * http://blogs.law.harvard.edu/tech/rss — RSS 2.0 Specification. 21 26 22 27 * ''Multi-platform RSS readers:'' … … 24 29 25 30 * ''Linux/BSD/*n*x systems:'' 26 * http://liferea.sourceforge.net/ — Open source GTK2 RSS Reader for Linux 27 * [http://akregator.sourceforge.net/ Akregator] — Open source KDE RSS Reader (part of KDE-PIM)31 * http://liferea.sourceforge.net/ — Open source GTK2 RSS Reader for Linux. 32 * [http://akregator.sourceforge.net/ Akregator] — Open source KDE RSS Reader, part of KDE-PIM. 28 33 29 34 * ''Mac OS X systems:'' 30 * http://ranchero.com/netnewswire/ — An excellent RSS reader for Mac OS X (has both free and pay versions) 31 * http://www.utsire.com/shrook/ — An RSS reader for Max OS X that supports https (even with self signed certificates) and authenticated feeds. 32 * http://vienna-rss.sourceforge.net/ — Open source Feed Reader for Mac OS X with smart folders support 33 * http://www.mesadynamics.com/Tickershock.html — Non-intrusive "news ticker" style RSS reader for Mac OS X 35 * http://ranchero.com/netnewswire/ — An excellent RSS reader for Mac OS X, has both free and paid versions. 36 * http://www.utsire.com/shrook/ — An RSS reader for Max OS X that supports https, even with self signed certificates, and authenticated feeds. 37 * http://vienna-rss.sourceforge.net/ — Open source Feed Reader for Mac OS X with smart folders support. 34 38 35 39 * ''Windows systems:'' 36 * http://www.rssreader.com/ — Free and powerful RSS Reader for Windows37 * http://www.sharpreader.net/ — A free RSS Reader written in .NET for Windows40 * http://www.rssreader.com/ — Free and powerful RSS Reader for MS Windows. 41 * http://www.sharpreader.net/ — A free RSS Reader written in .NET for MS Windows. 38 42 39 43 * ''Firefox:'' 40 * http://www.mozilla.org/products/firefox/ — Mozilla Firefox features plenty [https://addons.mozilla.org/en-US/firefox/search/?q=rss&appver=&platform= add-ons] for supporting RSS 44 * http://www.mozilla.org/products/firefox/ — Mozilla Firefox features plenty [https://addons.mozilla.org/en-US/firefox/search/?q=rss&appver=&platform= add-ons] for supporting RSS. 41 45 42 46 ---- -
wiki/pages/TracSearch
r26484 r37343 1 = Using Search =1 = Using Search 2 2 3 Trac has a built-in search engine to allow finding occurrences of keywords and substrings in wiki pages, tickets and changeset properties (author, revision and log message). 4 5 Using the Trac search facility is straightforward and its interface should be familiar to most users. 3 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. 6 4 7 5 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. 8 6 9 The search results show the most recent modifications ranked first in the resultsrather than the most relevant result.7 The search results show the most recent modifications ranked first rather than the most relevant result. 10 8 11 == "Quickjump" searches == 12 For quick access to various 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. 13 14 For example: 9 == Quick searches 10 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: 15 11 16 12 * ![42] -- Opens change set 42 17 13 * !#42 -- Opens ticket number 42 18 14 * !{1} -- Opens report 1 19 * /trunk -- Opens the browser for the `trunk` directory 15 * /trunk -- Opens the browser for the `trunk` directory in the default repository 16 * /repos1/trunk -- Opens the browser for the `trunk` directory in the `repos1` repository 20 17 21 == Advanced ==18 == Advanced 22 19 23 === Disabling Quickjump s ===24 To disable the quickjump feature for a search keyword - for example when searching for occurences of the literal word !TracGuide - begin the query with an exclamation mark (`!`).20 === Disabling Quickjump 21 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. 25 22 26 === Search Links === 27 From the Wiki, it is possible to link to a specific search, using 28 `search:` links: 23 === Search Links 24 From the Wiki, it is possible to link to a specific search, using `search:` links: 29 25 * `search:?q=crash` will search for the string "crash" 30 * `search:?q=trac+link&wiki=on` will search for "trac" and "link" 31 in wiki pages only 26 * `search:?q=trac+link&wiki=on` will search for "trac" and "link" in wiki pages only 32 27 33 28 ---- -
wiki/pages/TracStandalone
r26484 r37343 1 = Tracd =1 = Tracd 2 2 3 3 Tracd is a lightweight standalone Trac web server. 4 4 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. 5 5 6 == Pros ==6 == Pros 7 7 8 8 * Fewer dependencies: You don't need to install apache or any other web-server. … … 10 10 * 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). 11 11 12 == Cons ==12 == Cons 13 13 14 14 * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd. 15 15 * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead, 16 or [ http://trac.edgewall.org/wiki/STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.17 18 == Usage examples ==16 or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy. 17 18 == Usage examples 19 19 20 20 A single project on port 8080. (http://localhost:8080/) 21 {{{ 21 {{{#!sh 22 22 $ tracd -p 8080 /path/to/project 23 23 }}} 24 Stric ly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname''option.25 {{{ 24 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. 25 {{{#!sh 26 26 $ tracd --hostname=localhost -p 8080 /path/to/project 27 27 }}} 28 28 With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/) 29 {{{ 29 {{{#!sh 30 30 $ tracd -p 8080 /path/to/project1 /path/to/project2 31 31 }}} … … 35 35 36 36 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: 37 {{{ 37 {{{#!sh 38 38 $ tracd -p 8080 -e /path/to 39 39 }}} 40 40 41 To exit the server on Windows, be sure to use {{{CTRL-BREAK}}} -- using {{{CTRL-C}}}will leave a Python process running in the background.42 43 == Installing as a Windows Service ==44 45 === Option 1 ===41 To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background. 42 43 == Installing as a Windows Service 44 45 === Option 1 46 46 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run: 47 {{{ 47 {{{#!cmd 48 48 C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe 49 49 reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>" … … 54 54 55 55 If you want tracd to start automatically when you boot Windows, do: 56 {{{ 56 {{{#!cmd 57 57 sc config tracd start= auto 58 58 }}} … … 74 74 75 75 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: 76 {{{ 76 {{{#!cmd 77 77 "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>" 78 79 78 net start tracd 80 79 }}} 81 80 82 === Option 2 ===81 === Option 2 83 82 84 83 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service. 85 84 86 === Option 3 ===85 === Option 3 87 86 88 87 also cygwin's cygrunsrv.exe can be used: 89 {{{ 88 {{{#!sh 90 89 $ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects' 91 90 $ net start tracd 92 91 }}} 93 92 94 == Using Authentication == 95 96 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) 93 == Using Authentication 94 95 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) 96 97 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). 97 98 98 99 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. 99 100 100 101 The general format for using authentication is: 101 {{{ 102 {{{#!sh 102 103 $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path 103 104 }}} … … 115 116 Examples: 116 117 117 {{{ 118 {{{#!sh 118 119 $ tracd -p 8080 \ 119 120 --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1 … … 121 122 122 123 Of course, the password file can be be shared so that it is used for more than one project: 123 {{{ 124 {{{#!sh 124 125 $ tracd -p 8080 \ 125 126 --auth="project1,/path/to/passwordfile,mycompany.com" \ … … 129 130 130 131 Another way to share the password file is to specify "*" for the project name: 131 {{{ 132 {{{#!sh 132 133 $ tracd -p 8080 \ 133 134 --auth="*,/path/to/users.htdigest,mycompany.com" \ … … 135 136 }}} 136 137 137 === Basic Authorization: Using a htpasswd password file ===138 === Basic Authorization: Using a htpasswd password file 138 139 This section describes how to use `tracd` with Apache .htpasswd files. 139 140 … … 143 144 144 145 To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache): 145 {{{ 146 {{{#!sh 146 147 $ sudo htpasswd -c /path/to/env/.htpasswd username 147 148 }}} 148 149 then for additional users: 149 {{{ 150 {{{#!sh 150 151 $ sudo htpasswd /path/to/env/.htpasswd username2 151 152 }}} 152 153 153 154 Then to start `tracd` run something like this: 154 {{{ 155 $ tracd -p 8080 --basic-auth="project dirname,/fullpath/environmentname/.htpasswd,realmname" /fullpath/environmentname155 {{{#!sh 156 $ tracd -p 8080 --basic-auth="project,/fullpath/environmentname/.htpasswd,realmname" /path/to/project 156 157 }}} 157 158 158 159 For example: 159 {{{ 160 $ tracd -p 8080 --basic-auth=" testenv,/srv/tracenv/testenv/.htpasswd,My Test Env" /srv/tracenv/testenv160 {{{#!sh 161 $ tracd -p 8080 --basic-auth="project,/srv/tracenv/testenv/.htpasswd,My Test Env" /path/to/project 161 162 }}} 162 163 ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD). 163 164 164 === Digest authentication: Using a htdigest password file ===165 === Digest authentication: Using a htdigest password file 165 166 166 167 If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions. You'll be prompted for a password to enter for each user that you create. For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file. … … 168 169 Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error. 169 170 170 === Generating Passwords Without Apache === 171 172 Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`. Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd ; Windows Python can grok MD5 password hashes just fine and you should use MD5. 173 174 You can use this simple Python script to generate a '''digest''' password file: 175 176 {{{ 177 #!python 178 from optparse import OptionParser 179 # The md5 module is deprecated in Python 2.5 180 try: 181 from hashlib import md5 182 except ImportError: 183 from md5 import md5 184 realm = 'trac' 185 186 # build the options 187 usage = "usage: %prog [options]" 188 parser = OptionParser(usage=usage) 189 parser.add_option("-u", "--username",action="store", dest="username", type = "string", 190 help="the username for whom to generate a password") 191 parser.add_option("-p", "--password",action="store", dest="password", type = "string", 192 help="the password to use") 193 parser.add_option("-r", "--realm",action="store", dest="realm", type = "string", 194 help="the realm in which to create the digest") 195 (options, args) = parser.parse_args() 196 197 # check options 198 if (options.username is None) or (options.password is None): 199 parser.error("You must supply both the username and password") 200 if (options.realm is not None): 201 realm = options.realm 202 203 # Generate the string to enter into the htdigest file 204 kd = lambda x: md5(':'.join(x)).hexdigest() 205 print ':'.join((options.username, realm, kd([options.username, realm, options.password]))) 206 }}} 207 208 Note: If you use the above script you must set the realm in the `--auth` argument to '''`trac`'''. Example usage (assuming you saved the script as trac-digest.py): 209 210 {{{ 211 $ python trac-digest.py -u username -p password >> c:\digest.txt 212 $ tracd --port 8000 --auth=proj_name,c:\digest.txt,trac c:\path\to\proj_name 171 === Generating Passwords Without Apache 172 173 Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`. Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd. Windows Python can grok MD5 password hashes just fine and you should use MD5. 174 175 Trac also provides `htpasswd` and `htdigest` scripts in `contrib`: 176 {{{#!sh 177 $ ./contrib/htpasswd.py -cb htpasswd user1 user1 178 $ ./contrib/htpasswd.py -b htpasswd user2 user2 179 }}} 180 181 {{{#!sh 182 $ ./contrib/htdigest.py -cb htdigest trac user1 user1 183 $ ./contrib/htdigest.py -b htdigest trac user2 user2 213 184 }}} 214 185 215 186 ==== Using `md5sum` 216 187 It is possible to use `md5sum` utility to generate digest-password file: 217 {{{ 188 {{{#!sh 218 189 user= 219 190 realm= … … 223 194 }}} 224 195 225 == Reference ==196 == Reference 226 197 227 198 Here's the online help, as a reminder (`tracd --help`): … … 259 230 Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started. 260 231 261 == Tips ==262 263 === Serving static content ===232 == Tips 233 234 === Serving static content 264 235 265 236 If `tracd` is the only web server used for the project, … … 272 243 Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file, 273 244 the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`, 274 which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax). 275 276 ''Support for `htdocs:` TracLinks syntax was added in version 0.10'' 245 which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax). 277 246 278 247 === Using tracd behind a proxy … … 287 256 288 257 === Authentication for tracd behind a proxy 289 It is convenient to provide central external authentication to your tracd instances, instead of using {{{--basic-auth}}}. There is some discussion about this in #9206.258 It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in [trac:#9206]. 290 259 291 260 Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap. … … 293 262 First we bring tracd into Apache's location namespace. 294 263 295 {{{ 264 {{{#!apache 296 265 <Location /project/proxified> 297 266 Require ldap-group cn=somegroup, ou=Groups,dc=domain.com … … 304 273 305 274 Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory: 306 {{{ 307 #!python 275 {{{#!python 308 276 from trac.core import * 309 277 from trac.config import BoolOption … … 326 294 327 295 Add this new parameter to your TracIni: 328 {{{ 329 ... 296 {{{#!ini 330 297 [trac] 331 298 ... … … 335 302 336 303 Run tracd: 337 {{{ 304 {{{#!sh 338 305 tracd -p 8101 -r -s proxified --base-path=/project/proxified 339 306 }}} … … 342 309 343 310 Global config (e.g. `/srv/trac/conf/trac.ini`): 344 {{{ 311 {{{#!ini 345 312 [components] 346 313 remote-user-auth.* = enabled … … 352 319 353 320 Environment config (e.g. `/srv/trac/envs/myenv`): 354 {{{ 321 {{{#!ini 355 322 [inherit] 356 323 file = /srv/trac/conf/trac.ini 357 324 }}} 358 325 359 === Serving a different base path than / ===326 === Serving a different base path than / 360 327 Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is 361 {{{ 328 {{{#!sh 362 329 $ tracd --base-path=/some/path 363 330 }}} -
wiki/pages/TracSupport
r26484 r37343 1 1 = Trac Support = 2 2 3 Like in most [http://www.opensource.org/ open source projects], "free" Trac support is available primarily through the community itself, mainly through the [trac:MailingList mailing list] and the [trac: project wiki]. The latter is the authoritative source for the TracGuide (administrator and user guides for Trac).3 Like in most [http://www.opensource.org/ open source projects], Trac support is available primarily through the [trac:MailingList mailing list] and the [trac: project wiki]. Both are maintained by the trac community. The [trac: project wiki] is the authoritative source for the TracGuide, consisting of the administrator and user guides for Trac. 4 4 5 There is also an [trac:IrcChannel IRC channel] , where people might be able tohelp out. Much of the 'live' development discussions also happen there.5 There is also an [trac:IrcChannel IRC channel] where online users can help out. Much of the 'live' development discussions also happen there. 6 6 7 Before you start a new support query, make sure you 've done the appropriate searching:7 Before you start a new support query, make sure you have done the appropriate searching: 8 8 * in the project's [trac:TracFaq FAQ] 9 9 * in past messages to the [http://groups.google.com/group/trac-users Trac Users Mailing List] 10 10 * in the Trac ticket system, using either a [trac:search:?q=&ticket=on&wiki=on full search] or a [trac:query: ticket query]. 11 11 12 Please '''don't''' create a ticket in trac.egdewall.org for asking a support question about Trac. Only use it when you face a ''real'' and ''new'' bug in Trac, and do so only after having read the [trac:NewTicketGuidelines NewTicketGuidelines]. The more a bug report or enhancement request complies with those guidelines, the higher the chances are that it will be fixed or implemented promptly!12 Please '''don't''' create a ticket in trac.egdewall.org to ask a Trac support question. Only use it when you face a ''real'' and ''new'' bug in Trac, and do so only after having read the [trac:NewTicketGuidelines NewTicketGuidelines]. The more a bug report or enhancement request complies with those guidelines, the higher the chances are that it will be fixed or implemented promptly! 13 13 14 14 ---- -
wiki/pages/TracSyntaxColoring
r26484 r37343 1 = Syntax Coloring of Source Code = 2 Trac supports language-specific syntax highlighting of source code within wiki formatted text in [WikiProcessors#CodeHighlightingSupport wiki processors] blocks and in the [TracBrowser repository browser]. 3 4 To do this, Trac uses external libraries with support for a great number of programming languages. 5 6 Currently Trac supports syntax coloring using one or more of the following packages: 7 8 * [http://pygments.pocoo.org/ Pygments], by far the preferred system, as it covers a wide range of programming languages and other structured texts and is actively supported 9 * [http://www.codento.com/people/mtr/genscript/ GNU Enscript], commonly available on Unix but somewhat unsupported on Windows 10 * [http://silvercity.sourceforge.net/ SilverCity], legacy system, some versions can be [http://trac.edgewall.org/wiki/TracFaq#why-is-my-css-code-not-being-highlighted-even-though-i-have-silvercity-installed problematic] 1 = Syntax Coloring of Source Code 2 Trac supports language-specific syntax highlighting of source code within wiki formatted text in [WikiProcessors#CodeHighlightingSupport wiki processors] blocks and in the [TracBrowser repository browser]. Syntax coloring is provided using [http://pygments.pocoo.org/ Pygments], which covers a wide range of programming languages and other structured texts, and is actively supported. If Pygments is not available, Trac will display the content as plain text. 11 3 12 4 13 To activate syntax coloring, simply install either one (or more) of these packages (see [#ExtraSoftware] section below). 14 If none of these packages is available, Trac will display the data as plain text. 5 === About Pygments 6 7 [http://pygments.org/ Pygments] is a highlighting library implemented in pure python, very fast, easy to extend and [http://pygments.org/docs/ well documented]. 8 9 The Pygments default style can specified in the [TracIni#mimeviewer-section mime-viewer] section of trac.ini. The default style can be overridden by setting a //Style// preference on the [/prefs/pygments preferences page]. 15 10 16 11 17 == = About Pygments ===12 == Syntax Coloring Support 18 13 19 Starting with trac 0.11 [http://pygments.org/ pygments] will be the new default highlighter. It's a highlighting library implemented in pure python, very fast, easy to extend and [http://pygments.org/docs/ well documented]. 14 === Supported languages 20 15 21 The Pygments default style can specified in the [TracIni#mimeviewer-section mime-viewer] section of trac.ini. The default style can be overridden by setting a Style preference on the [/prefs/pygments preferences page].16 The list of currently supported languages can be found on the [http://pygments.org/languages/ supported languages] page. The list represents the languages supported in the most recent version of Pygments, so the languages actually supported in your installation could differ if you have an older version installed. The listing of [http://pygments.org/docs/lexers/ supported lexers] provides additional information about the default mime type to keyword mappings. 22 17 23 It's very likely that the list below is outdated because the list of supported pygments lexers is growing weekly. Just have a look at the page of [http://pygments.org/docs/lexers/ supported lexers] on the pygments webpage.18 Explicit control of the mime type associated with a [WikiProcessors WikiProcessor] and file extension is available through the `mime_map` setting. For example, by default `.m` files are considered Objective-C files. In order to treat `.m` files as MATLAB files, add `text/matlab:m` to the `mime_map` setting in the [wiki:TracIni#mimeviewer-section "[mimeviewer] section of trac.ini"]. 24 19 20 If a mimetype property such as `svn:mime-type` is set to `text/plain`, there is no coloring even if file is known type like `java`. 25 21 26 == Syntax Coloring Support ==22 === Direct Rendering 27 23 28 === Known MIME Types 29 30 [[KnownMimeTypes]] 31 32 Note that the rich content may be directly //rendered// instead of syntax highlighted. This usually depends on which auxiliary packages are installed and on which components are activated in your setup. For example a `text/x-rst` document will be rendered via `docutils` if it is installed and the `trac.mimeview.rst.ReStructuredTextRenderer` is not disabled, and will be syntax highlighted otherwise. 24 Rich content may be directly //rendered// instead of syntax highlighted. This usually depends on which auxiliary packages are installed and on which components are activated in your setup. For example a `text/x-rst` document will be rendered via `docutils` if it is installed and the `trac.mimeview.rst.ReStructuredTextRenderer` is not disabled, and will be syntax highlighted otherwise. 33 25 34 26 In a similar way, a document with the mimetype `text/x-trac-wiki` is rendered using the Trac wiki formatter, unless the `trac.mimeview.api.WikiTextRenderer` component is disabled. … … 36 28 HTML documents are directly rendered only if the `render_unsafe_html` settings are enabled in the TracIni (those settings are present in multiple sections, as there are different security concerns depending where the document comes from). If you want to ensure that an HTML document gets syntax highlighted and not rendered, use the `text/xml` mimetype. 37 29 38 If mimetype such as 'svn:mime-type' is set to 'text/plain', there is no coloring even if file is known type like 'java'. 30 === Known MIME types 39 31 40 === List of Languages Supported, by Highlighter #language-supported 41 42 This list is only indicative. 43 44 || ||= !SilverCity =||= Enscript =||= Pygments =|| 45 || Ada || || ✓ || || 46 || Asm || || ✓ || || 47 || Apache Conf || || || ✓ || 48 || ASP || ✓ || ✓ || || 49 || C || ✓ || ✓ || ✓ || 50 || C# || || ✓ ^[#a1 (1)]^ || ✓ || 51 || C++ || ✓ || ✓ || ✓ || 52 || CMake || ? || ? || ✓ || 53 || Java || ✓ ^[#a2 (2)]^ || ✓ || ✓ || 54 || Awk || || ✓ || || 55 || Boo || || || ✓ || 56 || CSS || ✓ || || ✓ || 57 || Python Doctests || || || ✓ || 58 || Diff || || ✓ || ✓ || 59 || Eiffel || || ✓ || || 60 || Elisp || || ✓ || || 61 || Fortran || || ✓ ^[#a1 (1)]^ || ✓ || 62 || Haskell || || ✓ || ✓ || 63 || Genshi || || || ✓ || 64 || HTML || ✓ || ✓ || ✓ || 65 || IDL || || ✓ || || 66 || INI || || || ✓ || 67 || Javascript || ✓ || ✓ || ✓ || 68 || Lua || || || ✓ || 69 || m4 || || ✓ || || 70 || Makefile || || ✓ || ✓ || 71 || Mako || || || ✓ || 72 || Matlab ^[#a3 (3)]^ || || ✓ || ✓ || 73 || Mygthy || || || ✓ || 74 || Objective-C || || ✓ || ✓ || 75 || OCaml || || || ✓ || 76 || Pascal || || ✓ || ✓ || 77 || Perl || ✓ || ✓ || ✓ || 78 || PHP || ✓ || || ✓ || 79 || PSP || ✓ || || || 80 || Pyrex || || ✓ || || 81 || Python || ✓ || ✓ || ✓ || 82 || Ruby || ✓ || ✓ ^[#a1 (1)]^ || ✓ || 83 || Scheme || || ✓ || ✓ || 84 || Shell || || ✓ || ✓ || 85 || Smarty || || || ✓ || 86 || SQL || ✓ || ✓ || ✓ || 87 || Troff || || ✓ || ✓ || 88 || TCL || || ✓ || || 89 || Tex || || ✓ || ✓ || 90 || Verilog || ✓ ^[#a2 (2)]^ || ✓ || || 91 || VHDL || || ✓ || || 92 || Visual Basic || || ✓ || ✓ || 93 || VRML || || ✓ || || 94 || XML || ✓ || || ✓ || 95 96 97 98 ''[=#a1 (1)] Not included in the Enscript distribution. Additional highlighting rules can be obtained for 99 [http://neugierig.org/software/ruby/ Ruby], 100 [http://wiki.hasno.info/index.php/Csharp.st C#], 101 [http://wiki.hasno.info/index.php/F90.st Fortran 90x/2003] 102 103 ''[=#a2 (2)] since Silvercity 0.9.7 released on 2006-11-23 104 105 ''[=#a3 (3)] By default `.m` files are considered Objective-C files. In order to treat `.m` files as MATLAB files, add "text/matlab:m" to the "mime_map" setting in the [wiki:TracIni#mimeviewer-section "[mimeviewer] section of trac.ini"]. 106 107 == Extra Software == 108 * GNU Enscript — http://directory.fsf.org/GNU/enscript.html 109 * GNU Enscript for Windows — http://gnuwin32.sourceforge.net/packages/enscript.htm 110 * !SilverCity — http://silvercity.sf.net/ 111 * **Pygments — http://pygments.org/** 32 [[KnownMimeTypes]] 112 33 113 34 ---- -
wiki/pages/TracTickets
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 The Trac ticket database provides simple but effective tracking of issues andbugs within a project.4 The Trac ticket database provides simple but effective way to track issues and software bugs within a project. 5 5 6 6 As the central project management element of Trac, tickets can be used for '''project tasks''', '''feature requests''', '''bug reports''', '''software support issues''' among others. 7 7 8 As with the TracWiki, this subsystem has been designed with the goal of making user contribution and participation as simple as possible. It should be as easy as possible to report bugs, ask questions, suggest improvements and discuss resolutions.8 As with the TracWiki, this subsystem has been designed with the goal of making user contribution and participation as simple as possible. 9 9 10 An issue is assigned to a person who must resolve it or reassign the ticket to someone else. 11 All tickets can be edited, annotated, assigned, prioritized and discussed at any time. 10 An issue is assigned to a person who must resolve it or reassign the ticket to someone else. All tickets can be edited, annotated, assigned, prioritized and discussed at any time. 12 11 13 12 [=#edit-permissions] 14 However, some Trac installations may put restrictions in place aboutwho can change what. For example, the default installation doesn't permit to non-authenticated users ("anonymous" users) to change anything, even to comment on an issue, for obvious spam prevention reasons. Check the local contributing policy, which you can usually find on the front page WikiStart, or contact your local Trac administrator.13 However, a Trac installation may place restrictions on who can change what. For example, the default installation doesn't permit to non-authenticated users ("anonymous" users) to change anything, even to comment on an issue, for obvious spam prevention reasons. Check the local contributing policy, which you can usually find on the front page WikiStart, or contact your local Trac administrator. 15 14 16 15 == Ticket Fields == 17 16 18 A ticket contains the following information attributes:17 A ticket contains the following information: 19 18 20 19 * '''Reporter''' — The author of the ticket. 21 * '''Type''' — The nature of the ticket (for example, defect or enhancement request). See TicketTypes for more details.20 * '''Type''' — The category of the ticket. The default types are `defect`, `enhancement` and `task`. 22 21 * '''Component''' — The project module or subsystem this ticket concerns. 23 22 * '''Version''' — Version of the project that this ticket pertains to. 24 23 * '''Keywords''' — Keywords that a ticket is marked with. Useful for searching and report generation. 25 * '''Priority''' — The importance of this issue, ranging from ''trivial'' to ''blocker''. A pull-down if different priorities where defined.26 * '''Milestone''' — When this issue should be resolved at the latest. A pull-down menu containing a list of milestones.24 * '''Priority''' — The importance of this issue, ranging from ''trivial'' to ''blocker''. A pull-down if different priorities are defined. 25 * '''Milestone''' — Due date of when this issue should be resolved. A pull-down menu containing a list of milestones. 27 26 * '''Assigned to/Owner''' — Principal person responsible for handling the issue. 28 * '''Cc''' — A comma-separated list of other users or E-Mail addresses to notify. ''Note that this does not imply responsiblity or any other policy.''27 * '''Cc''' — A comma-separated list of other users or email addresses to notify. ''Note that this does not imply responsibility or any other policy.'' 29 28 * '''Resolution''' — Reason for why a ticket was closed. One of {{{fixed}}}, {{{invalid}}}, {{{wontfix}}}, {{{duplicate}}}, {{{worksforme}}}. 30 * '''Status''' — What is the current status? One of {{{new}}}, {{{assigned}}}, {{{closed}}}, {{{reopened}}}.31 * '''Summary''' — A brief description summarizing the problem orissue. Simple text without WikiFormatting.29 * '''Status''' — What is the current status? The statuses are defined in the [TracWorkflow#BasicTicketWorkflowCustomization ticket workflow]. For the default workflow the statuses are `new`, `assigned`, `accepted`, `closed` and `reopened`. 30 * '''Summary''' — A description summarizing the issue. Simple text without WikiFormatting. 32 31 * '''Description''' — The body of the ticket. A good description should be specific, descriptive and to the point. Accepts WikiFormatting. 33 32 … … 35 34 - Versions of Trac prior to 0.9 did not have the ''type'' field, but instead provided a ''severity'' field and different default values for the ''priority'' field. This change was done to simplify the ticket model by removing the somewhat blurry distinction between ''priority'' and ''severity''. However, the old model is still available if you prefer it: just add/modify the default values of the ''priority'' and ''severity'', and optionally hide the ''type'' field by removing all the possible values through [wiki:TracAdmin trac-admin]. 36 35 37 - the [trac:TicketTypes type], [trac:TicketComponent component], version, priority and severity fields can be managed with [wiki:TracAdmin trac-admin] or with the [trac:WebAdmin WebAdmin] plugin.36 - The [trac:TicketTypes type], [trac:TicketComponent component], version, priority and severity fields can be managed with [wiki:TracAdmin trac-admin] or with the [trac:WebAdmin WebAdmin] plugin. 38 37 39 38 - Description of the builtin ''priority'' values is available at [trac:TicketTypes#Whyistheseverityfieldgone TicketTypes] … … 67 66 * `default_type`: Default ticket type 68 67 * `default_version`: Name of the default version 69 * `default_owner`: Name of the default owner. If set to the text "< default >"(the default value), the component owner is used.68 * `default_owner`: Name of the default owner. If set to the text `< default >` (the default value), the component owner is used. 70 69 71 If any of these options are omitted, the default value will either be the first in the list, or an empty value, depending on whether the field in question is required to be set. Some of these can be chosen through the [trac:WebAdmin WebAdmin] plugin in the "Ticket System" section (others in the [[wiki:TracIni#ticket-section|"[ticket]"]] section in `trac.ini`).70 If any of these options are omitted, the default value will either be the first in the list, or an empty value, depending on whether the field in question is required to be set. Some of these can be chosen through the [trac:WebAdmin WebAdmin] plugin in the "Ticket System" section, others can be set in the [[wiki:TracIni#ticket-section|"[ticket]"]] section in `trac.ini`. 72 71 73 72 … … 81 80 == Assign-to as Drop-Down List == 82 81 83 If the list of possible ticket owners is finite, you can change the ''assign-to'' ticket field from a text input to a drop-down list. This is done by setting the `restrict_owner` option of the `[ticket]` section in [wiki:TracIni trac.ini] to “true”. In that case, Trac will use the list of all users who have accessed the project to populate the drop-down field.82 If the list of possible ticket owners is finite, you can change the ''assign-to'' ticket field from a text input to a drop-down list. This is done by setting the `restrict_owner` option of the `[ticket]` section in [wiki:TracIni trac.ini] to `true`. In that case, Trac will populate the list with all users who have authenticated with the project and possess the `TICKET_MODIFY` [TracPermissions permissions]. 84 83 85 To appear in the dropdown list, a user needs be registered with the project, ''i.e.'' a user session should exist in the database. Such an entry is automatically created in the database the first time the user submits a change in the project, for example when editing the user's details in the ''Settings'' page, or simply by authenticating if the user has a login. Also, the user must have `TICKET_MODIFY` [TracPermissions permissions]. 84 You may find the dropdown list is //overpopulated// with users that are no longer active in the project. Revoking authentication privileges will not remove the session data that is used to populate the dropdown list. The [wiki:TracAdmin trac-admin] command can be used to list and remove sessions: 86 85 87 '''Notes:''' 88 - See [http://pacopablo.com/wiki/pacopablo/blog/set-assign-to-drop-down Populating Assign To Drop Down] on how to add user entries at database level 86 - List all sessions: 87 {{{#!sh 88 trac-admin /path/to/projenv session list 89 }}} 90 - Remove a session: 91 {{{#!sh 92 trac-admin /path/to/projenv session delete SID 93 }}} 89 94 90 - If you need serious flexibility and aren't afraid of a little plugin coding of your own, see [http://trac-hacks.org/wiki/FlexibleAssignToPlugin FlexibleAssignTo] (disclosure: I'm the author) 95 Alternatively, you can just revoke `TICKET_MODIFY` from users that you don't want to be included in the list. However, that will not be possible if you've granted `TICKET_MODIFY` to all //anonymous// or //authenticated// users. 91 96 92 - Activating this option may cause some performance degradation, read more about this in the [trac:TracPerformance#Configuration Trac performance] page. 97 '''Notes:''' 98 - If you need serious flexibility and aren't afraid of a little plugin coding of your own, see [http://trac-hacks.org/wiki/FlexibleAssignToPlugin FlexibleAssignTo]. 99 100 - Activating this option may cause some performance degradation. Read more about this in the [trac:TracPerformance#Configuration Trac performance] page. 93 101 94 102 == Preset Values for New Tickets == 95 103 96 To create a link to the new-ticket form filled with preset values, you need to call the `/newticket?` URL with `variable=value` separated by `&`. 97 98 Possible variables are : 104 To create a link to the new-ticket form filled with preset values, you need to call the `/newticket?` URL with `variable=value` separated by `&`. Possible variables are: 99 105 100 106 * '''type''' — The type droplist … … 111 117 * '''cc''' — The list of emails for notifying about the ticket change 112 118 113 Example: ''`[/newticket?summary=Compile%20Error&version=1.0&component=gui]`'' [[BR]]119 Example: ''`[/newticket?summary=Compile%20Error&version=1.0&component=gui]`'' 114 120 115 121 ---- -
wiki/pages/TracTicketsCustomFields
r26484 r37343 1 = Custom Ticket Fields =2 Trac supports adding custom, user-defined fields to the ticket module. Using custom fields,you can add typed, site-specific properties to tickets.1 = Custom Ticket Fields 2 Trac supports adding custom, user-defined fields to the ticket module. With custom fields you can add typed, site-specific properties to tickets. 3 3 4 == Configuration ==4 == Configuration 5 5 Configuring custom ticket fields is done in the [wiki:TracIni trac.ini] file. All field definitions should be under a section named `[ticket-custom]`. 6 6 … … 13 13 The example below should help to explain the syntax. 14 14 15 === Available Field Types and Options ===15 === Available Field Types and Options 16 16 * '''text''': A simple (one line) text field. 17 17 * label: Descriptive label. 18 18 * value: Default value. 19 * order: Sort order placement . (Determines relative placement in forms with respect to other custom fields.)19 * order: Sort order placement; this determines relative placement in forms with respect to other custom fields. 20 20 * format: One of: 21 21 * `plain` for plain text 22 * `wiki` to interpret the content as WikiFormatting (''since 0.11.3'')22 * `wiki` to interpret the content as WikiFormatting 23 23 * `reference` to treat the content as a queryable value (''since 1.0'') 24 24 * `list` to interpret the content as a list of queryable values, separated by whitespace (''since 1.0'') 25 25 * '''checkbox''': A boolean value check box. 26 26 * label: Descriptive label. 27 * value: Default value (0 or 1).27 * value: Default value, 0 or 1. 28 28 * order: Sort order placement. 29 29 * '''select''': Drop-down select box. Uses a list of values. … … 35 35 * label: Descriptive label. 36 36 * options: List of values, separated by '''|''' (vertical pipe). 37 * value: Default value (one of the values from options).37 * value: Default value, one of the values from options. 38 38 * order: Sort order placement. 39 39 * '''textarea''': Multi-line text area. 40 40 * label: Descriptive label. 41 41 * value: Default text. 42 * cols: Width in columns. 42 * cols: Width in columns. //(Removed in 1.1.2)// 43 43 * rows: Height in lines. 44 44 * order: Sort order placement. 45 * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting. (''since 0.11.3'') 45 * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting. 46 * '''time''': Date and time picker. (''Since 1.1.1.'') 47 * label: Descriptive label. 48 * value: Default date. 49 * order: Sort order placement. 50 * format: One of: 51 * `relative` for relative dates. 52 * `date` for absolute dates. 53 * `datetime` for absolute date and time values. 46 54 47 === Sample Config === 55 If the `label` is not specified, it will be created by capitalizing the custom field name and replacing underscores with whitespaces. 56 57 Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`. 58 59 === Sample Config 48 60 {{{ 49 61 [ticket-custom] … … 76 88 test_six.cols = 60 77 89 test_six.rows = 30 90 91 test_seven = time 92 test_seven.label = A relative date 93 test_seven.format = relative 94 test_seven.value = now 95 96 test_eight = time 97 test_eight.label = An absolute date 98 test_eight.format = date 99 test_eight.value = yesterday 100 101 test_nine = time 102 test_nine.label = A date and time 103 test_nine.format = datetime 104 test_nine.value = in 2 hours 78 105 }}} 79 106 80 '' Note: To make entering an option for a `select` type field optional, specify a leading `|` in the `fieldname.options` option.''107 '''Note''': To make a `select` type field optional, specify a leading `|` in the `fieldname.options` option. 81 108 82 === Reports Involving Custom Fields ===109 === Reports Involving Custom Fields 83 110 84 111 Custom ticket fields are stored in the `ticket_custom` table, not in the `ticket` table. So to display the values from custom fields in a report, you will need a join on the 2 tables. Let's use an example with a custom ticket field called `progress`. … … 93 120 ORDER BY p.value 94 121 }}} 95 '''Note''' that this will only show tickets that have progress set in them, which is '''not the same as showing all tickets'''. If you created this custom ticket field ''after'' you have already created some tickets, they will not have that field defined, and thus they will never show up on this ticket query. If you go back and modify those tickets, the field will be defined, and they will appear in the query. If that's all you want, you're set.122 '''Note''': This will only show tickets that have progress set in them. This is '''not the same as showing all tickets'''. If you created this custom ticket field ''after'' you have already created some tickets, they will not have that field defined, and thus they will never show up on this ticket query. If you go back and modify those tickets, the field will be defined, and they will appear in the query. 96 123 97 However, if you want to show all ticket entries (with progress defined and without), you need to use a `JOIN` for every custom field that is in the query .124 However, if you want to show all ticket entries (with progress defined and without), you need to use a `JOIN` for every custom field that is in the query: 98 125 {{{ 99 126 #!sql … … 114 141 Note in particular the `LEFT OUTER JOIN` statement here. 115 142 116 === Updating the database === 143 Note that if your config file uses an uppercase name, e.g., 144 {{{ 145 [ticket-custom] 146 147 Progress_Type = text 148 }}} 149 you would use lowercase in the SQL: `AND c.name = 'progress_type'` 150 151 === Updating the database 117 152 118 153 As noted above, any tickets created before a custom field has been defined will not have a value for that field. Here's a bit of SQL (tested with SQLite) that you can run directly on the Trac database to set an initial value for custom ticket fields. Inserts the default value of 'None' into a custom field called 'request_source' for all tickets that have no existing value: -
wiki/pages/TracTimeline
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 T he timeline provides a historic view of the project in a single report.4 Trac's timeline feature provides a historic view of the project in a single report. 5 5 6 It lists all Trac events that have occurred in chronological order, a 7 brief description of each event and if applicable, the person responsible for 8 the change. 6 It lists all Trac events that have occurred in chronological order, a brief description of each event and if applicable, the person responsible for the change. 9 7 10 8 The timeline lists these kinds of events: 11 9 * '''Wiki page events''' — Creation and changes 12 * '''Ticket events''' — Creation and resolution/closing (and optionally other changes)10 * '''Ticket events''' — Creation and resolution/closing and optionally other changes 13 11 * '''Source code changes ''' — Repository check-ins 14 12 * '''Milestone ''' — Milestone completed 15 13 16 Each event entry provides a hyperlink to the specific event in question, who authored the change as well as 17 a brief excerpt of the actual comment or text, if available. 14 Each event entry provides a hyperlink to the specific event in question, who authored the change as well as a brief excerpt of the actual comment or text, if available. 18 15 19 16 It is possible to filter the displayed events with the various filters in the option panel: -
wiki/pages/TracUnicode
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 Trac stores all text using UTF-8 encoding, including text in tickets and wiki pages. Internal processing of text uses true Unicode representations.4 Trac encodes all text using [http://en.wikipedia.org/wiki/UTF-8 UTF-8], including text in tickets and wiki pages. Internal processing of text uses true [http://en.wikipedia.org/wiki/Unicode Unicode] representations. As such, it supports most (all?) commonly used character encodings. 5 5 6 As such, it supports most (all?) commonly used character encodings. 7 8 If the default encoding in your source code repository is not UTF-8, you can specify it in the [TracIni#trac-section trac.ini], for example: 6 If the default encoding in your source code repository is not UTF-8, you can specify it in the [TracIni#trac-section trac.ini]: 9 7 {{{ 10 8 default_charset = gbk 11 9 }}} 12 10 13 You also must make sure that your [trac:DatabaseBackend database backend] stores its data in UTF-8; otherwise strange things will happen.11 Also ensure that your [trac:DatabaseBackend database] stores its data in UTF-8, otherwise results may be unpredictable. 14 12 15 To convert your database to UTF-8, the easiest way is to dump the database, convert the dump into UTF-8 and then import the converted dump back into the database.[[BR]] 16 You can use [http://www.gnu.org/software/libiconv/documentation/libiconv/iconv.1.html iconv] to convert the dump. 17 13 To convert your database to UTF-8, the easiest way is to create a dump of the database, convert it into UTF-8, for example using [http://www.gnu.org/software/libiconv/documentation/libiconv/iconv.1.html iconv], and then import it back into the database. 18 14 19 15 == Examples == -
wiki/pages/TracUpgrade
r26484 r37343 1 = Upgrade Instructions =1 = Upgrade Instructions 2 2 [[TracGuideToc]] 3 3 [[PageOutline(2-4,,inline,unnumbered)]] 4 4 5 == Instructions ==5 == Instructions 6 6 7 7 Typically, there are seven steps involved in upgrading to a newer version of Trac: … … 9 9 === 1. Bring your server off-line 10 10 11 It is not a good idea to update a running server: the server processes may have parts of the current packages cached in memory, and updating the code will likely trigger [#ZipImportError internal errors]. 12 13 === 2. Update the Trac Code === #UpdatetheTracCode 11 It is not a good idea to update a running server: the server processes may have parts of the current packages cached in memory, and updating the code will likely trigger [#ZipImportError internal errors]. 12 13 Although a database backup will be implicitly created by default when upgrading the environment, it is always a good idea to perform a full backup of the environment using the [TracBackup hotcopy] command before beginning. 14 15 === 2. Update the Trac Code #UpdatetheTracCode 14 16 15 17 Get the new version as described in TracInstall, or your operating system specific procedure. 16 18 17 If you already have a 0.1 1version of Trac installed via `easy_install`, it might be easiest to also use `easy_install` to upgrade your Trac installation:18 19 {{{ 20 # easy_install --upgrade Trac==0.12 19 If you already have a 0.12 version of Trac installed via `easy_install`, it might be easiest to also use `easy_install` to upgrade your Trac installation: 20 21 {{{#!sh 22 easy_install --upgrade Trac==1.0 21 23 }}} 22 24 … … 29 31 * on MacOSX: `/Library/Python/2.X/site-packages` 30 32 31 You may also want to remove the Trac `cgi-bin`, `htdocs`, `templates` and `wiki-default` directories that are commonly found in a directory called `share/trac`. (The exact location depends on your platform.) 32 33 This cleanup is not mandatory, but makes it easier to troubleshoot issues later on, as you won't waste your time looking at code or templates from a previous release that are not being used anymore... As usual, make a backup before actually deleting things. 34 35 === 3. Upgrade the Trac Environment === #UpgradetheTracEnvironment 33 You may also want to remove the Trac `cgi-bin`, `htdocs`, `templates` and `wiki-default` directories that are commonly found in a directory called `share/trac`. The exact location depends on your platform. This cleanup is not mandatory, but makes it easier to troubleshoot issues later on, as your installation is uncluttered by code or templates from a previous release that is not used anymore. As usual, make a backup before actually removing things. 34 35 === 3. Upgrade the Trac Environment #UpgradetheTracEnvironment 36 36 37 37 Environment upgrades are not necessary for minor version releases unless otherwise noted. 38 38 39 39 After restarting, Trac should show the instances which need a manual upgrade via the automated upgrade scripts to ease the pain. These scripts are run via [TracAdmin trac-admin]: 40 {{{ 40 {{{#!sh 41 41 trac-admin /path/to/projenv upgrade 42 42 }}} … … 45 45 46 46 Note that a backup of your database will be performed automatically prior to the upgrade. 47 This feature is relatively new for the PostgreSQL or MySQL database backends, so if it fails, you will have to backup the database manually. Then, to perform the actual upgrade, run:48 {{{ 47 This feature is relatively new for PostgreSQL or MySQL databases, so if it fails, you will have to backup the database manually. Then, to perform the actual upgrade, run: 48 {{{#!sh 49 49 trac-admin /path/to/projenv upgrade --no-backup 50 50 }}} … … 52 52 === 4. Update the Trac Documentation === #UpdatetheTracDocumentation 53 53 54 Every [TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. As you probably want to keep the included documentation in sync with the installed version of Trac, [TracAdmin trac-admin] provides acommand to upgrade the documentation:55 {{{ 54 By default, every [TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. However, to keep the included documentation in sync with the installed version of Trac, use the following [TracAdmin trac-admin] command to upgrade the documentation: 55 {{{#!sh 56 56 trac-admin /path/to/projenv wiki upgrade 57 57 }}} … … 59 59 Note that this procedure will leave your `WikiStart` page intact. 60 60 61 62 === 5. Refresh static resources === 61 === 5. Refresh static resources 63 62 64 63 If you have set up a web server to give out static resources directly (accessed using the `/chrome/` URL) then you will need to refresh them using the same command: 65 {{{ 64 {{{#!sh 66 65 trac-admin /path/to/env deploy /deploy/path 67 66 }}} … … 73 72 }}} 74 73 75 === 6. Steps specific to a given Trac version === 76 ==== Upgrading from Trac 0.12 to Trac 1.0 ==== #to1.0 77 74 === 6. Steps specific to a given Trac version 75 76 ==== Upgrading from Trac 1.0 to 1.1.x #to1.1.x 77 78 ===== Python 2.5 no longer supported 79 Upgrade Python to at least 2.6, but not 3.0. 80 81 ===== New workflow actions 82 83 The ticket creation step is now controlled with a workflow action. The default workflow has `create` and `create_and_assign` actions. The `create` action will always be added when upgrading the database. The `create_and_assign` action will be added if the workflow has an //assigned// state. You may want to edit your workflow after upgrading the database to customize the actions available on the //New Ticket// page. 84 85 ===== New permissions policy for read-only wiki pages 86 Since 1.1.2 the read-only attribute of wiki pages is enabled and enforced only when `ReadonlyWikiPolicy` is in the list of active permission policies. If `[trac] permission_policy` has the default value `DefaultPermissionPolicy, LegacyAttachmentPolicy`, then `ReadonlyWikiPolicy` should be automatically appended to the list when upgrading the environment: 87 {{{#!ini 88 [trac] 89 permission_policies = ReadonlyWikiPolicy, 90 DefaultPermissionPolicy, 91 LegacyAttachmentPolicy 92 }}} 93 If other permission policies are enabled, //trac.ini// will need to be edited to append `ReadonlyWikiPolicy` to the list of active `permission_policies`. See TracFineGrainedPermissions#ReadonlyWikiPolicy for additional details on the proper ordering. 94 95 ==== Upgrading from Trac 0.12 to Trac 1.0 #to1.0 96 97 ===== Python 2.4 no longer supported 98 Upgrade Python to at least 2.5, but not 3.0. 99 100 ===== Subversion components not enabled by default for new installations 78 101 The Trac components for Subversion support are no longer enabled by default. To enable the svn support, you need to make sure the `tracopt.versioncontrol.svn` components are enabled, for example by setting the following in the TracIni: 79 {{{ 102 {{{#!ini 80 103 [components] 81 104 tracopt.versioncontrol.svn.* = enabled … … 83 106 The upgrade procedure should take care of this and change the TracIni appropriately, unless you already had the svn components explicitly disabled. 84 107 85 Another step in the automatic upgrade will change the way the attachments are stored. If you're a bit paranoid, you might want to take a backup of the `attachments` directory before upgrading (but if you are, you already did a full copy of the environment, no?). In case the `attachments` directory contains some files which are //not// attachments, the last step of the migration to the new layout will fail: the deletion of the now unused `attachments` directory can't be done if there are still files and folders in it. You may ignore this error, but better go have a look to these files, move them elsewhere and remove the `attachments` directory manually to cleanup the environment. The attachments themselves are now all located in your environment below the `files/attachments` directory. 86 87 88 ==== Upgrading from Trac 0.11 to Trac 0.12 ==== 89 90 ===== Python 2.3 no longer supported ===== 91 The minimum supported version of python is now 2.4 92 93 ===== SQLite v3.x required ===== 108 ===== Attachments migrated to new location 109 Another step in the automatic upgrade will change the way the attachments are stored. Create a backup of the `attachments` directory before upgrading. In case the `attachments` directory contains some files which are //not// attachments, the last step of the migration to the new layout will fail: the deletion of the now unused `attachments` directory can't be done if there are still files and folders in it. You may ignore this error, but better to move them elsewhere and remove the `attachments` directory manually. The attachments themselves are now all located in your environment below the `files/attachments` directory. 110 111 ===== Behavior of `[ticket] default_owner` changed 112 Prior to 1.0, the owner field of new tickets always defaulted to `[ticket] default_owner` when the value was not empty. If the value was empty, the owner field defaulted to to the Component's owner. In 1.0 and later, the `default_owner` must be set to `< default >` to make new tickets default to the Component's owner. This change allows the `default_owner` to be set to an empty value if no default owner is desired. 113 114 ==== Upgrading from Trac 0.11 to Trac 0.12 115 116 ===== Python 2.3 no longer supported 117 The minimum supported version of Python is now 2.4. 118 119 ===== SQLite v3.x required 94 120 SQLite v2.x is no longer supported. If you still use a Trac database of this format, you'll need to convert it to SQLite v3.x first. See [trac:PySqlite#UpgradingSQLitefrom2.xto3.x] for details. 95 121 96 ===== PySqlite 2 required =====97 PySqlite 1.1.x is no longer supported. Please install 2.5.5 or later if possible (see [#Tracdatabaseupgrade Trac database upgrade] below).98 99 ===== Multiple Repository Support =====122 ===== [trac:PySqlite] 2 required 123 [trac:PySqlite] 1.1.x is no longer supported. Please install 2.5.5 or later if possible, see [#Tracdatabaseupgrade Trac database upgrade] below. 124 125 ===== Multiple Repository Support 100 126 The latest version includes support for multiple repositories. If you plan to add more repositories to your Trac instance, please refer to TracRepositoryAdmin#Migration. 101 127 102 This may be of interest to users with only one repository, since there 's now a way to avoid the potentially costly resync check at every request.103 104 ===== Resynchronize the Trac Environment Against the Source Code Repository =====105 106 Each [TracEnvironment Trac environment] must be resynchronized against the source code repository in order to avoid errors such as "[ http://trac.edgewall.org/ticket/6120 No changeset ??? in the repository]" while browsing the source through the Trac interface:107 108 {{{ 128 This may be of interest to users with only one repository, since there is now a way to avoid the potentially costly resync check at every request. 129 130 ===== Resynchronize the Trac Environment Against the Source Code Repository 131 132 Each [TracEnvironment Trac environment] must be resynchronized against the source code repository in order to avoid errors such as "[trac:#6120 No changeset ??? in the repository]" while browsing the source through the Trac interface: 133 134 {{{#!sh 109 135 trac-admin /path/to/projenv repository resync '*' 110 136 }}} 111 137 112 ===== Improved repository synchronization =====138 ===== Improved repository synchronization 113 139 In addition to supporting multiple repositories, there is now a more efficient method for synchronizing Trac and your repositories. 114 140 … … 117 143 Note that if you were using the `trac-post-commit-hook`, ''you're strongly advised to upgrade it'' to the new hook documented in the above references and [TracWorkflow#Howtocombinethetracopt.ticket.commit_updaterwiththetestingworkflow here], as the old hook will not work with anything else than the default repository and even for this case, it won't trigger the appropriate notifications. 118 144 119 ===== Authz permission checking =====120 The authz permission checking has been migrated to a fine-grained permission policy. If you use authz permissions (aka `[trac] authz_file` and `authz_module_name`), you must add `AuthzSourcePolicy` in front of your permission policies in `[trac] permission_policies`. You must also remove `BROWSER_VIEW`, `CHANGESET_VIEW`, `FILE_VIEW` and `LOG_VIEW` from your global permissions (with `trac-admin $ENV permission remove` or the "Permissions" admin panel).121 122 ===== Microsecond timestamps =====123 All timestamps in database tables (except the `session` table)have been changed from "seconds since epoch" to "microseconds since epoch" values. This change should be transparent to most users, except for custom reports. If any of your reports use date/time columns in calculations (e.g. to pass them to `datetime()`), you must divide the values retrieved from the database by 1'000'000. Similarly, if a report provides a calculated value to be displayed as a date/time (i.e. with a column named "time", "datetime", "changetime", "date", "created" or "modified"), you must provide a microsecond timestamp, that is, multiply your previous calculation with 1'000'000.124 125 ==== Upgrading from Trac 0.10 to Trac 0.11 ====126 ===== Site Templates and Styles =====145 ===== Authz permission checking 146 The authz permission checking has been migrated to a fine-grained permission policy. If you use authz permissions (aka `[trac] authz_file` and `authz_module_name`), you must add `AuthzSourcePolicy` in front of your permission policies in `[trac] permission_policies`. You must also remove `BROWSER_VIEW`, `CHANGESET_VIEW`, `FILE_VIEW` and `LOG_VIEW` from your global permissions with `trac-admin $ENV permission remove` or the "Permissions" admin panel. 147 148 ===== Microsecond timestamps 149 All timestamps in database tables, except the `session` table, have been changed from "seconds since epoch" to "microseconds since epoch" values. This change should be transparent to most users, except for custom reports. If any of your reports use date/time columns in calculations (e.g. to pass them to `datetime()`), you must divide the values retrieved from the database by 1'000'000. Similarly, if a report provides a calculated value to be displayed as a date/time (i.e. with a column named "time", "datetime", "changetime", "date", "created" or "modified"), you must provide a microsecond timestamp, that is, multiply your previous calculation with 1'000'000. 150 151 ==== Upgrading from Trac 0.10 to Trac 0.11 152 ===== Site Templates and Styles 127 153 The templating engine has changed in 0.11 to Genshi, please look at TracInterfaceCustomization for more information. 128 154 129 If you are using custom CSS stylesor modified templates in the `templates` directory of the TracEnvironment, you will need to convert them to the Genshi way of doing things. To continue to use your style sheet, follow the instructions at TracInterfaceCustomization#SiteAppearance.130 131 ===== Trac Macros, Plugins =====132 The Trac macros will need to be adapted, as the old-style wiki-macros are not supported anymore (due to the drop of [trac:ClearSilver] and the HDF); they need to be converted to the new-style macros, see WikiMacros. When they are converted to the new style, they need to be placed into the plugins directory instead and not wiki-macros, which is no longer scanned for macros or plugins.133 134 ===== For FCGI/WSGI/CGI users =====155 If you are using custom CSS or modified templates in the `templates` directory of the TracEnvironment, you will need to convert them to the Genshi way of doing things. To continue to use your style sheet, follow the instructions at TracInterfaceCustomization#SiteAppearance. 156 157 ===== Trac Macros, Plugins 158 The Trac macros will need to be adapted, as the old-style wiki-macros are not supported anymore due to the drop of [trac:ClearSilver] and the HDF. They need to be converted to the new-style macros, see WikiMacros. When they are converted to the new style, they need to be placed into the plugins directory instead and not wiki-macros, which is no longer scanned for macros or plugins. 159 160 ===== For FCGI/WSGI/CGI users 135 161 For those who run Trac under the CGI environment, run this command in order to obtain the trac.*gi file: 136 {{{ 162 {{{#!sh 137 163 trac-admin /path/to/env deploy /deploy/directory/path 138 164 }}} … … 140 166 This will create a deploy directory with the following two subdirectories: `cgi-bin` and `htdocs`. Then update your Apache configuration file `httpd.conf` with this new `trac.cgi` location and `htdocs` location. 141 167 142 ===== Web Admin plugin integrated ===== 143 If you had the webadmin plugin installed, you can uninstall it as it is part of the Trac code base since 0.11. 144 145 === 7. Restart the Web Server === #RestarttheWebServer 168 ===== Web Admin plugin integrated 169 If you had the [trac:WebAdmin] plugin installed, you can uninstall it as it is part of the Trac code base since 0.11. 170 171 ===== New Default Configurable Workflow 172 173 When you run `trac-admin <env> upgrade`, your `trac.ini` will be modified to include a `[ticket-workflow]` section. The workflow configured in this case is the original workflow, so that ticket actions will behave like they did in 0.10. 174 175 Graphically, that looks like this: 176 177 {{{#!Workflow width=500 height=240 178 leave = * -> * 179 leave.operations = leave_status 180 leave.default = 1 181 accept = new -> assigned 182 accept.permissions = TICKET_MODIFY 183 accept.operations = set_owner_to_self 184 resolve = new,assigned,reopened -> closed 185 resolve.permissions = TICKET_MODIFY 186 resolve.operations = set_resolution 187 reassign = new,assigned,reopened -> new 188 reassign.permissions = TICKET_MODIFY 189 reassign.operations = set_owner 190 reopen = closed -> reopened 191 reopen.permissions = TICKET_CREATE 192 reopen.operations = del_resolution 193 }}} 194 195 There are some significant caveats in this, such as accepting a ticket sets it to 'assigned' state, and assigning a ticket sets it to 'new' state. So you will probably want to migrate to "basic" workflow; [trac:source:trunk/contrib/workflow/migrate_original_to_basic.py contrib/workflow/migrate_original_to_basic.py] may be helpful. See TracWorkflow for a detailed description of the new basic workflow. 196 197 === 7. Restart the Web Server #RestarttheWebServer 146 198 147 199 If you are not running [wiki:TracCgi CGI], reload the new Trac code by restarting your web server. 148 200 149 == Known Issues == 150 151 Things you should pay attention to, while upgrading. 201 == Known Issues 152 202 153 203 === Customized Templates 154 204 155 Trac supports customization of its Genshi templates by placing copies of the templates in the `<env>/templates` folder of your [TracEnvironment environment] or in a common location specified in the [[TracIni#GlobalConfiguration| [inherit] templates_dir]] configuration setting. If you choose to do so, be wary that you will need to repeat your changes manually on a copy of the new templates when you upgrade to a new release of Trac (even a minor one), as the templates will likely evolve. So keep a diff around ;-)156 157 The preferred way to perform TracInterfaceCustomization is to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation, as this is more robust in case of changes: we usually won't modify element `id`s or change CSS `class`es, and if we have to do so, this will be documented in the TracDev/ApiChangespages.158 159 === !ZipImportError ===160 161 Due to internal caching of zipped packages, 205 Trac supports customization of its Genshi templates by placing copies of the templates in the `<env>/templates` folder of your [TracEnvironment environment] or in a common location specified in the [[TracIni#GlobalConfiguration| [inherit] templates_dir]] configuration setting. If you choose to do so, be aware that you will need to repeat your changes manually on a copy of the new templates when you upgrade to a new release of Trac (even a minor one), as the templates will likely evolve. So keep a diff around. 206 207 The preferred way to perform TracInterfaceCustomization is to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation, as this is more robust in case of changes: we usually won't modify element `id`s or change CSS `class`es, and if we have to do so, this will be documented in the [trac:TracDev/ApiChanges] pages. 208 209 === !ZipImportError 210 211 Due to internal caching of zipped packages, whenever the content of the packages change on disk, the in-memory zip index will no longer match and you'll get irrecoverable !ZipImportError errors. Better anticipate and bring your server down for maintenance before upgrading. 162 212 See [trac:#7014] for details. 163 213 164 === Wiki Upgrade ===214 === Wiki Upgrade 165 215 `trac-admin` will not delete or remove default wiki pages that were present in a previous version but are no longer in the new version. 166 216 167 === Trac database upgrade ===168 169 A known issue in some versions of PySqlite(2.5.2-2.5.4) prevents the trac-admin upgrade script from successfully upgrading the database format. It is advised to use either a newer or older version of the sqlite python bindings to avoid this error. For more details see ticket [trac:#9434].170 171 === parent dir ===172 If you use a trac parent env configuration and one of the plugins in one child does not work, none of the childrenwork.217 === Trac database upgrade 218 219 A known issue in some versions of [trac:PySqlite] (2.5.2-2.5.4) prevents the trac-admin upgrade script from successfully upgrading the database format. It is advised to use either a newer or older version of the sqlite python bindings to avoid this error. For more details see ticket [trac:#9434]. 220 221 === Parent dir 222 If you use a Trac parent env configuration and one of the plugins in one child does not work, none of the children will work. 173 223 174 224 == Related topics 175 225 176 === Upgrading Python === 177 178 Upgrading Python to a newer version will require reinstallation of Python packages: Trac of course; also [http://pypi.python.org/pypi/setuptools easy_install], if you've been using that. Assuming you're using Subversion, you'll also need to upgrade the Python bindings for svn. 179 180 ==== Windows and Python 2.6 ==== 181 182 If you've been using !CollabNet's Subversion package, you may need to uninstall that in favor of [http://alagazam.net/ Alagazam], which has the Python bindings readily available (see TracSubversion). The good news is, that works with no tweaking. 183 184 === Changing Database Backend === 185 ==== SQLite to PostgreSQL ==== 186 187 The [http://trac-hacks.org/wiki/SqliteToPgScript sqlite2pg] script on [http://trac-hacks.org trac-hacks.org] has been written to assist in migrating a SQLite database to a PostgreSQL database 188 189 === Upgrading from older versions of Trac === #OlderVersions 226 === Upgrading Python 227 228 Upgrading Python to a newer version will require reinstallation of Python packages: Trac itself of course, but also [http://pypi.python.org/pypi/setuptools easy_install], if you've been using that. If you are using Subversion, you'll also need to upgrade the Python bindings for svn. 229 230 ==== Windows and Python 2.6 231 232 If you've been using !CollabNet's Subversion package, you may need to uninstall that in favor of [http://alagazam.net/ Alagazam], which has the Python bindings readily available, see [trac:TracSubversion]. That package works without tweaking. 233 234 === Changing Database Backend 235 236 The [http://trac-hacks.org/wiki/TracMigratePlugin TracMigratePlugin] on [http://trac-hacks.org trac-hacks.org] has been written to assist in migrating between SQLite, MySQL and PostgreSQL databases. 237 238 === Upgrading from older versions of Trac #OlderVersions 190 239 191 240 For upgrades from versions older than Trac 0.10, refer first to [trac:wiki:0.10/TracUpgrade#SpecificVersions]. -
wiki/pages/TracWiki
r26484 r37343 1 2 1 = The Trac Wiki System = 3 2 [[TracGuideToc]] … … 15 14 For example, the ''[http://www.w3.org/Provider/Style Style Guide for online hypertext]'' explains how to think about the 16 15 [http://www.w3.org/Provider/Style/Structure.html overall structure of a work] 17 and how to organize information [http://www.w3.org/Provider/Style/WithinDocument.html within each document]. One of the most important tip is “make your HTML page such that you can read it even if you don't follow any links.”16 and how to organize information [http://www.w3.org/Provider/Style/WithinDocument.html within each document]. One of the most important tips is “make your HTML page such that you can read it even if you don't follow any links.” 18 17 19 18 Learn more about: -
wiki/pages/TracWorkflow
r26484 r37343 1 = The Trac Ticket Workflow System = 1 = The Trac Ticket Workflow System 2 3 [[PageOutline(2-5,Contents,pullout)]] 2 4 [[TracGuideToc]] 3 4 The Trac issue database provides a configurable workflow. 5 6 == The Default Ticket Workflow == 7 === Environments upgraded from 0.10 === 8 When you run `trac-admin <env> upgrade`, your `trac.ini` will be modified to include a `[ticket-workflow]` section. 9 The workflow configured in this case is the original workflow, so that ticket actions will behave like they did in 0.10. 10 11 Graphically, that looks like this: 12 13 {{{#!Workflow width=500 height=240 14 leave = * -> * 15 leave.operations = leave_status 16 leave.default = 1 17 accept = new -> assigned 18 accept.permissions = TICKET_MODIFY 19 accept.operations = set_owner_to_self 20 resolve = new,assigned,reopened -> closed 21 resolve.permissions = TICKET_MODIFY 22 resolve.operations = set_resolution 23 reassign = new,assigned,reopened -> new 24 reassign.permissions = TICKET_MODIFY 25 reassign.operations = set_owner 26 reopen = closed -> reopened 27 reopen.permissions = TICKET_CREATE 28 reopen.operations = del_resolution 29 }}} 30 31 There are some significant "warts" in this; such as accepting a ticket sets it to 'assigned' state, and assigning a ticket sets it to 'new' state. Perfectly obvious, right? 32 So you will probably want to migrate to "basic" workflow; [trac:source:trunk/contrib/workflow/migrate_original_to_basic.py contrib/workflow/migrate_original_to_basic.py] may be helpful. 33 34 === Environments created with 0.11 === 35 When a new environment is created, a default workflow is configured in your trac.ini. This workflow is the basic workflow (described in `basic-workflow.ini`), which is somewhat different from the workflow of the 0.10 releases. 36 37 Graphically, it looks like this: 5 The Trac ticket system provides a configurable workflow. 6 7 == The Default Ticket Workflow 8 9 When a new environment is created, a default workflow is configured in your trac.ini. This workflow is the basic workflow, such as specified in [trac:source:/trunk/trac/ticket/workflows/basic-workflow.ini basic-workflow.ini]: 38 10 39 11 {{{#!Workflow width=700 height=300 … … 41 13 leave.operations = leave_status 42 14 leave.default = 1 15 16 create = <none> -> new 17 create.default = 1 18 19 create_and_assign = <none> -> assigned 20 create_and_assign.label = assign 21 create_and_assign.permissions = TICKET_MODIFY 22 create_and_assign.operations = may_set_owner 23 43 24 accept = new,assigned,accepted,reopened -> accepted 44 25 accept.permissions = TICKET_MODIFY 45 26 accept.operations = set_owner_to_self 27 46 28 resolve = new,assigned,accepted,reopened -> closed 47 29 resolve.permissions = TICKET_MODIFY 48 30 resolve.operations = set_resolution 31 49 32 reassign = new,assigned,accepted,reopened -> assigned 50 33 reassign.permissions = TICKET_MODIFY 51 34 reassign.operations = set_owner 35 52 36 reopen = closed -> reopened 53 37 reopen.permissions = TICKET_CREATE … … 55 39 }}} 56 40 57 == Additional Ticket Workflows ==58 59 There are several example workflows provided in the Trac source tree; look in [trac:source:trunk/contrib/workflow contrib/workflow] for `.ini` config sections. One of those may be a good match for what you want. They can be pasted into the `[ticket-workflow]` section of your `trac.ini` file. Howeverif you have existing tickets then there may be issues if those tickets have states that are not in the new workflow.60 61 Here are some [ http://trac.edgewall.org/wiki/WorkFlow/Examples diagrams] of the above examples.62 63 == Basic Ticket Workflow Customization ==64 65 Note: Ticket "statuses" or "states" are not separately defined. The states a ticket can be in are automatically generated by the transitions defined in a workflow. Therefore, creating a new ticket state simply requires defining a state transition in the workflow that starts or ends with that state.41 == Additional Ticket Workflows 42 43 There are example workflows provided in the Trac source tree, see [trac:source:trunk/contrib/workflow contrib/workflow] for `.ini` config sections. One of those may be a good match for what you want. They can be pasted into the `[ticket-workflow]` section of your `trac.ini` file. However, if you have existing tickets then there may be issues if those tickets have states that are not in the new workflow. 44 45 Here are some [trac:WorkFlow/Examples diagrams] of the above examples. 46 47 == Basic Ticket Workflow Customization 48 49 '''Note''': Ticket "statuses" or "states" are not separately defined. The states a ticket can be in are automatically generated by the transitions defined in a workflow. Therefore, creating a new ticket state simply requires defining a state transition in the workflow that starts or ends with that state. 66 50 67 51 Create a `[ticket-workflow]` section in `trac.ini`. 68 52 Within this section, each entry is an action that may be taken on a ticket. 69 53 For example, consider the `accept` action from `simple-workflow.ini`: 70 {{{ 54 55 {{{#!ini 71 56 accept = new,accepted -> accepted 72 57 accept.permissions = TICKET_MODIFY 73 58 accept.operations = set_owner_to_self 74 59 }}} 60 75 61 The first line in this example defines the `accept` action, along with the states the action is valid in (`new` and `accepted`), and the new state of the ticket when the action is taken (`accepted`). 76 62 The `accept.permissions` line specifies what permissions the user must have to use this action. … … 78 64 79 65 The available operations are: 80 - del_owner -- Clear the owner field. 81 - set_owner -- Sets the owner to the selected or entered owner. 82 - ''actionname''`.set_owner` may optionally be set to a comma delimited list or a single value. 83 - set_owner_to_self -- Sets the owner to the logged in user. 84 - del_resolution -- Clears the resolution field 85 - set_resolution -- Sets the resolution to the selected value. 86 - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. Example: 87 {{{ 66 - **del_owner** -- Clear the owner field. 67 - **set_owner** -- Sets the owner to the selected or entered owner. Defaults to the current user. When `[ticket] restrict_owner = true`, the select will be populated with users that have `TICKET_MODIFY` permission and an authenticated session. 68 - ''actionname''`.set_owner` may optionally be set to a comma delimited list of users that will be used to populate the select, or a single user. Groups and permissions may also be included in the list //(Since 1.1.3)//. When groups or permissions are specified the select is populated with all members of the group or all users that possess the permission. 69 - **set_owner_to_self** -- Sets the owner to the logged in user. 70 - **may_set_owner** -- Sets the owner to the selected or entered owner. Defaults to the existing owner. //(Since 1.1.2)//. 71 - **del_resolution** -- Clears the resolution field. 72 - **set_resolution** -- Sets the resolution to the selected value. 73 - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. Example: 74 {{{#!ini 88 75 resolve_new = new -> closed 89 resolve_new. name= resolve76 resolve_new.label = resolve 90 77 resolve_new.operations = set_resolution 91 78 resolve_new.permissions = TICKET_MODIFY 92 79 resolve_new.set_resolution = invalid,wontfix 93 }}} 94 - leave_status -- Displays "leave as <current status>" and makes no change to the ticket. 95 '''Note:''' Specifying conflicting operations (such as `set_owner` and `del_owner`) has unspecified results. 96 97 {{{ 80 }}} 81 - **leave_status** -- Displays "leave as <current status>" and makes no change to the ticket. 82 - **reset_workflow** -- Resets the status of tickets that are in states no longer defined. 83 '''Note:''' Specifying conflicting operations, such as `set_owner` and `del_owner`, has unspecified results. 84 85 In this example, we see the `.label` attribute used. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`: 86 87 {{{#!ini 98 88 resolve_accepted = accepted -> closed 99 resolve_accepted. name= resolve89 resolve_accepted.label = resolve 100 90 resolve_accepted.permissions = TICKET_MODIFY 101 91 resolve_accepted.operations = set_resolution 102 92 }}} 103 93 104 In this example, we see the `. name` attribute used. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`.105 106 For actions that should be available in all states, `*` may be used in place of the state. 107 {{{ 94 In this example, we see the `.label` attribute used. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`. The `.label` attribute is new in Trac 1.1.3 and is functionally the same as the `.name` attribute, which is now deprecated. If neither `.label` or `.name` is specified, the action will be presented to the user as //resolve accepted//, the underscores having been replaced by whitespace (//Since 1.1.3//). 95 96 For actions that should be available in all states, `*` may be used in place of the state. The obvious example is the `leave` action: 97 {{{#!ini 108 98 leave = * -> * 109 99 leave.operations = leave_status 110 100 leave.default = 1 111 101 }}} 112 This also shows the use of the `.default` attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest `.default` value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing `.default` values. 113 If not specified for an action, `.default` is 0. The value may be negative. 114 115 There are a couple of hard-coded constraints to the workflow. In particular, tickets are created with status `new`, and tickets are expected to have a `closed` state. Further, the default reports/queries treat any state other than `closed` as an open state. 116 117 While creating or modifying a ticket workflow, `contrib/workflow/workflow_parser.py` may be useful. It can create `.dot` files that [http://www.graphviz.org GraphViz] understands to provide a visual description of the workflow. 118 119 This can be done as follows (your install path may be different). 120 {{{ 102 103 This also shows the use of the `.default` attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest `.default` value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing `.default` values. 104 If not specified for an action, `.default` is 0. The value may be negative. 105 106 The ticket create actions are specified by a transition from the special `<none>` state. At least one create action must be available to the user in order for tickets to be created. The create actions defined in the default workflow are: 107 {{{#!ini 108 create = <none> -> new 109 create.default = 1 110 111 create_and_assign = <none> -> assigned 112 create_and_assign.label = assign 113 create_and_assign.permissions = TICKET_MODIFY 114 create_and_assign.operations = may_set_owner 115 }}} 116 117 118 There is one hard-coded constraints to the workflow: tickets are expected to have a `closed` state. The default reports/queries treat any state other than `closed` as an open state. 119 120 The special `_reset` action is added by default for tickets that are in states that are no longer defined. This allows tickets to be individually "repaired" after the workflow is changed, although it's recommended that the administrator perform the action by batch modifying the affected tickets. By default the `_reset` action is available to users with the `TICKET_ADMIN` permission and reset tickets are put in the //new// state. The default `_reset` action is equivalent to the following `[ticket-workflow]` action definition: 121 122 {{{#!ini 123 _reset = -> new 124 _reset.label = reset 125 _reset.operations = reset_workflow 126 _reset.permissions = TICKET_ADMIN 127 _reset.default = 0 128 }}} 129 130 Since [trac:milestone:1.0.3] the `_reset` action can be customized by redefining the implicit action. For example, to allow anyone with `TICKET_MODIFY` to perform the `_reset` action, the workflow action would need to be defined: 131 132 {{{#!ini 133 _reset = -> new 134 _reset.label = reset 135 _reset.operations = reset_workflow 136 _reset.permissions = TICKET_MODIFY 137 _reset.default = 0 138 }}} 139 140 == Workflow Visualization 141 142 Workflows can be visualized by rendering them on the wiki using the [WikiMacros#Workflow-macro Workflow macro]. 143 144 Workflows can also be visualized using the `contrib/workflow/workflow_parser.py` script. The script outputs `.dot` files that [http://www.graphviz.org GraphViz] understands. The script can be used as follows (your install path may be different): 145 146 {{{#!sh 121 147 cd /var/local/trac_devel/contrib/workflow/ 122 148 sudo ./showworkflow /srv/trac/PlannerSuite/conf/trac.ini 123 149 }}} 124 And then open up the resulting `trac.pdf` file created by the script (it will be in the same directory as the `trac.ini` file). 125 126 An online copy of the workflow parser is available at http://foss.wush.net/cgi-bin/visual-workflow.pl 127 128 After you have changed a workflow, you need to restart apache for the changes to take effect. This is important, because the changes will still show up when you run your script, but all the old workflow steps will still be there until the server is restarted. 129 130 == Example: Adding optional Testing with Workflow == 131 132 By adding the following to your [ticket-workflow] section of trac.ini you get optional testing. When the ticket is in new, accepted or needs_work status you can choose to submit it for testing. When it's in the testing status the user gets the option to reject it and send it back to needs_work, or pass the testing and send it along to closed. If they accept it then it gets automatically marked as closed and the resolution is set to fixed. Since all the old work flow remains, a ticket can skip this entire section. 133 134 {{{ 150 And then open up the resulting `trac.pdf` file created by the script. It will be in the same directory as the `trac.ini` file. 151 152 After you have changed a workflow, you need to restart your webserver for the changes to take effect. 153 154 == Example: Adding optional Testing with Workflow 155 156 By adding the following to your [ticket-workflow] section of trac.ini you get optional testing. When the ticket has status `new`, `accepted` or `needs_work`, you can choose to submit it for testing. When it's in the testing status the user gets the option to reject it and send it back to `needs_work`, or pass the testing and send it along to `closed`. If they accept it, then it is automatically marked as `closed` and the resolution is set to `fixed`. Since all the old work flow remains, a ticket can skip this entire section. 157 158 {{{#!ini 135 159 testing = new,accepted,needs_work,assigned,reopened -> testing 136 testing. name= Submit to reporter for testing160 testing.label = Submit to reporter for testing 137 161 testing.permissions = TICKET_MODIFY 138 162 139 163 reject = testing -> needs_work 140 reject. name= Failed testing, return to developer164 reject.label = Failed testing, return to developer 141 165 142 166 pass = testing -> closed 143 pass. name= Passes Testing167 pass.label = Passes Testing 144 168 pass.operations = set_resolution 145 169 pass.set_resolution = fixed 146 170 }}} 147 171 148 === How to combine the `tracopt.ticket.commit_updater` with the testing workflow ===172 === How to combine the `tracopt.ticket.commit_updater` with the testing workflow 149 173 150 174 The [[trac:source:trunk/tracopt/ticket/commit_updater.py|tracopt.ticket.commit_updater]] is the optional component that [[TracRepositoryAdmin#trac-post-commit-hook|replaces the old trac-post-commit-hook]], in Trac 0.12. … … 156 180 Have a look at the [[trac:wiki:0.11/TracWorkflow#How-ToCombineSVNtrac-post-commit-hookWithTestWorkflow|Trac 0.11 recipe]] for the `trac-post-commit-hook`, this will give you some ideas about how to modify the component. 157 181 158 == Example: Add simple optional generic review state ==182 == Example: Add simple optional generic review state 159 183 160 184 Sometimes Trac is used in situations where "testing" can mean different things to different people so you may want to create an optional workflow state that is between the default workflow's `assigned` and `closed` states, but does not impose implementation-specific details. The only new state you need to add for this is a `reviewing` state. A ticket may then be "submitted for review" from any state that it can be reassigned. If a review passes, you can re-use the `resolve` action to close the ticket, and if it fails you can re-use the `reassign` action to push it back into the normal workflow. … … 162 186 The new `reviewing` state along with its associated `review` action looks like this: 163 187 164 {{{ 188 {{{#!ini 165 189 review = new,assigned,reopened -> reviewing 166 190 review.operations = set_owner … … 168 192 }}} 169 193 170 Then, to integrate this with the default Trac 0.11 workflow, you also need to add the `reviewing` state to the `accept` and `resolve` actions , like so:171 172 {{{ 194 Then, to integrate this with the default Trac 0.11 workflow, you also need to add the `reviewing` state to the `accept` and `resolve` actions: 195 196 {{{#!ini 173 197 accept = new,reviewing -> assigned 174 198 […] … … 176 200 }}} 177 201 178 Optionally, you can also add a new action that allows you to change the ticket's owner without moving the ticket out of the `reviewing` state. This enables you to reassign review work without pushing the ticket back to the `new` status .179 180 {{{ 202 Optionally, you can also add a new action that allows you to change the ticket's owner without moving the ticket out of the `reviewing` state. This enables you to reassign review work without pushing the ticket back to the `new` status: 203 204 {{{#!ini 181 205 reassign_reviewing = reviewing -> * 182 reassign_reviewing. name= reassign review206 reassign_reviewing.label = reassign review 183 207 reassign_reviewing.operations = set_owner 184 208 reassign_reviewing.permissions = TICKET_MODIFY … … 187 211 The full `[ticket-workflow]` configuration will thus look like this: 188 212 189 {{{ 213 {{{#!ini 190 214 [ticket-workflow] 215 create = <none> -> new 216 create.default = 1 217 create_and_assign = <none> -> assigned 218 create_and_assign.label = assign 219 create_and_assign.permissions = TICKET_MODIFY 220 create_and_assign.operations = may_set_owner 191 221 accept = new,reviewing -> assigned 192 222 accept.operations = set_owner_to_self … … 209 239 reassign_reviewing = reviewing -> * 210 240 reassign_reviewing.operations = set_owner 211 reassign_reviewing. name= reassign review241 reassign_reviewing.label = reassign review 212 242 reassign_reviewing.permissions = TICKET_MODIFY 213 243 }}} 214 244 215 == Example: Limit the resolution options for a new ticket ==216 217 The above resolve_new operation allows you to set the possible resolutions for a new ticket. By modifying the existing resolve action and removing the new status from before the `->` we then get two resolve actions.One with limited resolutions for new tickets, and then the regular one once a ticket is accepted.218 219 {{{ 245 == Example: Limit the resolution options for a new ticket 246 247 The above `resolve_new` operation allows you to set the possible resolutions for a new ticket. By modifying the existing resolve action and removing the new status from before the `->` we then get two resolve actions. One with limited resolutions for new tickets, and then the regular one once a ticket is accepted. 248 249 {{{#!ini 220 250 resolve_new = new -> closed 221 resolve_new. name= resolve251 resolve_new.label = resolve 222 252 resolve_new.operations = set_resolution 223 253 resolve_new.permissions = TICKET_MODIFY … … 229 259 }}} 230 260 231 == Advanced Ticket Workflow Customization ==232 233 If the customization above is not extensive enough for your needs, you can extend the workflow using plugins. These plugins can provide additional operations for the workflow (like code_review), or implement side-effects for an action (such as triggering a build) that may not be merely simple state changes. Look at [trac:source:trunk/sample-plugins/workflow sample-plugins/workflow] for a few simpleexamples to get started.261 == Advanced Ticket Workflow Customization 262 263 If the customizations above do not meet your needs, you can extend the workflow with plugins. Plugins can provide additional operations for the workflow, like code_review, or implement side-effects for an action, such as triggering a build, that may not be merely simple state changes. Look at [trac:source:trunk/sample-plugins/workflow sample-plugins/workflow] for a few examples to get started. 234 264 235 265 But if even that is not enough, you can disable the !ConfigurableTicketWorkflow component and create a plugin that completely replaces it. 236 266 237 == Adding Workflow States to Milestone Progress Bars == 238 239 If you add additional states to your workflow, you may want to customize your milestone progress bars as well. See [TracIni#milestone-groups-section TracIni]. 240 241 == some ideas for next steps == 242 243 New enhancement ideas for the workflow system should be filed as enhancement tickets against the `ticket system` component. If desired, add a single-line link to that ticket here. Also look at the [http://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin] as it provides experimental operations. 244 245 If you have a response to the comments below, create an enhancement ticket, and replace the description below with a link to the ticket. 246 247 * the "operation" could be on the nodes, possible operations are: 248 * '''preops''': automatic, before entering the state/activity 249 * '''postops''': automatic, when leaving the state/activity 250 * '''actions''': can be chosen by the owner in the list at the bottom, and/or drop-down/pop-up together with the default actions of leaving the node on one of the arrows. 251 ''This appears to add complexity without adding functionality; please provide a detailed example where these additions allow something currently impossible to implement.'' 252 253 * operations could be anything: sum up the time used for the activity, or just write some statistical fields like 254 ''A workflow plugin can add an arbitrary workflow operation, so this is already possible.'' 255 256 * set_actor should be an operation allowing to set the owner, e.g. as a "preop": 257 * either to a role, a person 258 * entered fix at define time, or at run time, e.g. out of a field, or select. 259 ''This is either duplicating the existing `set_owner` operation, or needs to be clarified.'' 260 261 * Actions should be selectable based on the ticket type (different Workflows for different tickets) 262 ''Look into the [http://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin]'s `triage` operation.'' 263 264 * I'd wish to have an option to perform automatic status changes. In my case, I do not want to start with "new", but with "assigned". So tickets in state "new" should automatically go into state "assigned". Or is there already a way to do this and I just missed it? 265 ''Have a look at [http://trac-hacks.org/wiki/TicketCreationStatusPlugin TicketCreationStatusPlugin] and [http://trac-hacks.org/wiki/TicketConditionalCreationStatusPlugin TicketConditionalCreationStatusPlugin]'' 266 267 * I added a 'testing' state. A tester can close the ticket or reject it. I'd like the transition from testing to rejected to set the owner to the person that put the ticket in 'testing'. The [http://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin] is close with set_owner_to_field, but we need something like set_field_to_owner. 268 269 * I'd like to track the time a ticket is in each state, adding up 'disjoints' intervals in the same state. 267 == Adding Workflow States to Milestone Progress Bars 268 269 If you add additional states to your workflow, you may want to customize your milestone progress bars as well. See [TracIni#milestone-groups-section TracIni]. 270 271 == Ideas for next steps 272 273 Enhancement ideas for the workflow system should be filed as enhancement tickets against the [trac:query:?status=assigned&status=new&status=reopened&keywords=~workflow&component=ticket+system ticket system] component. You can also document ideas on the [trac:TracIdeas/TracWorkflow TracIdeas/TracWorkflow] page. Also look at the [http://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin] as it provides experimental operations. -
wiki/pages/WikiFormatting
r26484 r37343 1 = WikiFormatting = 1 = WikiFormatting 2 2 3 [[TracGuideToc]] 3 4 4 5 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole. 5 6 6 Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis, 7 especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole]. 8 7 Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis, especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole]. 9 8 10 9 This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed. 11 10 12 The ''Cheat sheet'' below gives you a quickoverview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page.11 The sections below provide an overview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page. 13 12 14 13 A few other wiki pages present the advanced features of the Trac wiki markup in more depth: 15 - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof ,16 - WikiPageNames talks aboutthe various names a wiki page can take, CamelCase or not17 - WikiMacros lists the macros available for generating dynamic content ,14 - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof 15 - WikiPageNames covers the various names a wiki page can take, CamelCase or not 16 - WikiMacros lists the macros available for generating dynamic content 18 17 - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways 19 20 21 == C heat sheet ==18 - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios 19 20 == Common wiki markup 22 21 23 22 ||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =|| … … 182 181 || `!wiki:WikiFormatting`, `!WikiFormatting` ||\ 183 182 || !wiki:WikiFormatting, !WikiFormatting || 184 || {{{`}}}`{{{-}}}`{{{`}}}` triple curly brackets`||\183 || [[html(<code>`{{{-}}}` triple curly brackets</code>)]] ||\ 185 184 || `{{{-}}}` triple curly brackets || 186 185 |----------------------------------------------------------- … … 243 242 }}} 244 243 245 246 == Font Styles == 244 == Font Styles 247 245 248 246 The Trac wiki supports the following font styles: … … 264 262 * **also bold**, //italic as well//, 265 263 and **'' bold italic **'' //(since 0.12)// 264 * [[span(style=color: #FF0000, a red text )]] 266 265 }}} 267 266 }}} … … 281 280 * **also bold**, //italic as well//, 282 281 and **'' bold italic **'' //(since 0.12)// 282 * [[span(style=color: #FF0000, a red text )]] 283 283 }}} 284 284 … … 290 290 with a `//` one, and `'''` can't be paired with `**`) 291 291 292 293 == Headings == 294 295 You can create heading by starting a line with one up to six ''equal'' characters ("=") 296 followed by a single space and the headline text. 292 == Headings 293 294 You can create heading by starting a line with one up to six ''equal'' characters ("=") followed by a single space and the headline text. 297 295 298 296 [=#hn] … … 322 320 }}} 323 321 324 == Paragraphs ==322 == Paragraphs 325 323 326 324 A new text paragraph is created whenever two blocks of text are separated by one or more empty lines. … … 350 348 }}} 351 349 352 == Lists ==350 == Lists 353 351 354 352 The wiki supports both ordered/numbered and unordered lists. … … 406 404 }}} 407 405 408 409 == Definition Lists == 406 == Definition Lists 410 407 411 408 The wiki also supports definition lists. … … 431 428 Note that you need a space in front of the defined term. 432 429 433 434 == Preformatted Text == 430 == Preformatted Text 435 431 436 432 Block containing preformatted text are suitable for source code snippets, notes and examples. Use three ''curly braces'' wrapped around the text to define a block quote. The curly braces need to be on a separate line. … … 454 450 Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors. 455 451 456 == Blockquotes ==452 == Blockquotes 457 453 458 454 In order to mark a paragraph as blockquote, indent that paragraph with two spaces. … … 470 466 }}} 471 467 472 == Discussion Citations ==468 == Discussion Citations 473 469 474 470 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, e-mail-like citation marks (">", ">>", etc.) may be used. … … 490 486 }}} 491 487 492 493 == Tables ==494 === Simple Tables === 488 == Tables 489 === Simple Tables 490 495 491 Simple tables can be created like this: 496 492 ||= Wiki Markup =||= Display =|| … … 582 578 }}} 583 579 584 === Complex Tables ===580 === Complex Tables 585 581 586 582 If the possibilities offered by the simple "pipe"-based markup for tables described above are not enough for your needs, you can create more elaborated tables by using [#Processors-example-tables WikiProcessor based tables]. 587 583 588 589 == Links == 584 == Links 590 585 591 586 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}. … … 641 636 }}} 642 637 643 '''Note''': the [trac:WikiCreole] style for links is quick to type and 644 certainly looks familiar as it's the one used on Wikipedia and in many 645 other wikis. Unfortunately it conflicts with the syntax for [#Macros macros]. 646 So in the rare case when you need to refer to a page which is named after 647 a macro (typical examples being TitleIndex, InterTrac and InterWiki), 648 by writing `[[TitleIndex]]` you will actually call the macro instead of linking 649 to the page. 650 651 == Trac Links == 638 '''Note''': the [trac:WikiCreole] style for links is quick to type and certainly looks familiar as it is the one used on Wikipedia and in many other wikis. Unfortunately it conflicts with the syntax for [#Macros macros]. 639 So in the rare case when you need to refer to a page which is named after a macro (typical examples being TitleIndex, InterTrac and InterWiki), by writing `[[TitleIndex]]` you will actually call the macro instead of linking to the page. 640 641 == Trac Links 652 642 653 643 Wiki pages can link directly to other parts of the Trac system. Pages can refer to tickets, reports, changesets, milestones, source files and other Wiki pages using the following notations: … … 679 669 There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers. 680 670 681 682 == Setting Anchors == 671 == Setting Anchors 683 672 684 673 An anchor, or more correctly speaking, an [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, in order to uniquely identify a position in the document: … … 724 713 For more complex anchors (e.g. when a custom title is wanted), one can use the Span macro, e.g. `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`. 725 714 726 727 715 == Escaping Links, WikiPageNames and other Markup == #Escaping 728 716 … … 737 725 {{{ 738 726 Various forms of escaping for list markup: 739 `-`escaped minus sign \\740 ``1. escaped number \\741 {{{*}}}escaped asterisk sign727 ^^- escaped minus sign \\ 728 ^^1. escaped number \\ 729 ^^* escaped asterisk sign 742 730 }}} 743 731 }}} … … 747 735 748 736 Various forms of escaping for list markup: 749 `-`escaped minus sign \\750 ``1. escaped number \\751 {{{*}}}escaped asterisk sign752 }}} 753 754 == Images ==737 ^^- escaped minus sign \\ 738 ^^1. escaped number \\ 739 ^^* escaped asterisk sign 740 }}} 741 742 == Images 755 743 756 744 Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags. … … 776 764 See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.) 777 765 778 779 == Macros == 766 == Macros 780 767 781 768 Macros are ''custom functions'' to insert dynamic content in a page. … … 805 792 }}} 806 793 807 808 == Processors == 794 == Processors 809 795 810 796 Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in … … 943 929 See WikiProcessors for more information. 944 930 945 946 == Comments == 931 == Comments 947 932 948 933 Comments can be added to the plain text. These will not be rendered and will not display in any other format than plain text. … … 968 953 }}} 969 954 970 == Miscellaneous ==955 == Miscellaneous 971 956 972 957 An horizontal line can be used to separated different parts of your page: … … 1005 990 !WikiCreole style \\ line\\break 1006 991 }}} 1007 -
wiki/pages/WikiHtml
r26484 r37343 1 1 = Using HTML in Wiki Text = 2 2 3 Trac supports inserting HTML into any wiki context, accomplished using the `#!html` [wiki:WikiProcessors WikiProcessor]. 4 5 However a constraint is that this HTML has to be well-formed. 6 In particular you can't insert a start tag in an `#!html` block, 7 resume normal wiki text and insert the corresponding end tag in a 8 second `#!html` block. 9 10 Fortunately, for creating styled <div>s, <span>s or even complex tables 11 containing arbitrary Wiki text, there's a powerful alternative: use of 12 dedicated `#!div`, `#!span` and `#!table`, `#!tr`, `#!td` and `#!th` blocks. 13 14 Those Wiki processors are built-in, and does not require installing any additional packages. 3 Trac supports the display of HTML in any wiki context, by using the `#!html` [wiki:WikiProcessors WikiProcessor]. 4 5 However, this HTML has to be [http://en.wikipedia.org/wiki/Well-formed_element well-formed]. 6 In particular, you can't insert a start tag in an `#!html` block, resume normal wiki text and insert the corresponding end tag in a second `#!html` block. 7 8 Fortunately, for creating styled <div>s, <span>s or even complex tables containing arbitrary Wiki text, there is a powerful alternative: `#!div`, `#!span` and `#!table`, `#!tr`, `#!td` and `#!th` blocks. Those Wiki processors are built-in and do not require additional packages to be installed. 15 9 16 10 == How to use `#!html` == #HowtoUseHTML 17 To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor .11 To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor: 18 12 19 13 ||= Wiki Markup =||= Display =|| … … 33 27 }}} 34 28 35 Note that Trac sanitizes your HTML code before displaying it. That means that if you try to use potentially dangerous constructs such as Javascript event handlers, thosewill be removed from the output.36 37 Since 0.11, the filtering is done by Genshi, and as such, the produced output will be a well-formed fragment of HTML. As noted above in the introduction, this mean that you can no longer use two HTML blocks, one for opening a <div>, the secondfor closing it, in order to wrap arbitrary wiki text.38 The new way to wrap any wiki content inside a <div> is to use the `#!div` Wiki 29 Note that Trac sanitizes your HTML code before displaying it. That means that potentially dangerous constructs, such as Javascript event handlers, will be removed from the output. 30 31 The filtering is done by [http://genshi.edgewall.org/ Genshi] and the output will be a well-formed fragment of HTML. This means that you can no longer use two HTML blocks, one for opening a <div> and another for closing it, in order to wrap arbitrary wiki text. 32 The new way to wrap any wiki content inside a <div> is to use the `#!div` Wiki processor. 39 33 40 34 == How to use `#!div` and `#!span` == #HowtoUseDivSpan … … 116 110 }}} 117 111 118 Note that the contents of a `#!div` block are contained in one or more paragraphs, which have a non-zero top and bottom margin. This leads to the top and bottom padding in the example above. To remove the top and bottom margin of the content s, add the `compact` class to the `#!div`. Another predefined class besides `wikipage` and `compact` is `important`, which can be used to make a paragraph stand out. Extra CSS classes can be defined via the `site/style.css` file for example, see TracInterfaceCustomization#SiteAppearance.119 120 For spans, you should ratheruse the Macro call syntax:112 Note that the contents of a `#!div` block are contained in one or more paragraphs, which have a non-zero top and bottom margin. This leads to the top and bottom padding in the example above. To remove the top and bottom margin of the content, add the `compact` class to the `#!div`. Another predefined class besides `wikipage` and `compact` is `important`, which can be used to make a paragraph stand out. Extra CSS classes can be defined via the `site/style.css` file for example, see TracInterfaceCustomization#SiteAppearance. 113 114 For spans, you should use the Macro call syntax: 121 115 ||= Wiki Markup =|| 122 116 {{{#!td … … 135 129 == How to use `#!td` and other table related processors == #Tables 136 130 137 `#!td` or `#!th` processors are actually the main ones, for creating table data andheader cells, respectively. The other processors `#!table` and `#!tr` are not required for introducing a table structure, as `#!td` and `#!th` will do this automatically. The `|-` row separator can be used to start a new row when needed, but some may prefer to use a `#!tr` block for that, as this introduces a more formal grouping and offers the possibility to use an extra level of indentation. The main purpose of the `#!table` and `#!tr` is to give the possibility to specify HTML attributes, like ''style'' or ''valign'' to these elements.131 The `#!td` or `#!th` processors should be used to create table data and table header cells, respectively. The other processors `#!table` and `#!tr` are not required for introducing a table structure, as `#!td` and `#!th` will do this automatically. The `|-` row separator can be used to start a new row when needed, but some may prefer to use a `#!tr` block for that, as this introduces a more formal grouping and offers the possibility to use an extra level of indentation. The main purpose of the `#!table` and `#!tr` is to give the possibility to specify HTML attributes, like ''style'' or ''valign'' to these elements. 138 132 139 133 ||= Wiki Markup =||= Display =|| … … 263 257 }}} 264 258 265 Note that by default tables are assigned the "wiki" CSS class, which gives a distinctive look to the header cells and a default border to the table and cells (as can be seen for the tables on this page). By removing this class (`#!table class=""`), one regains complete control on the table presentation. In particular, neither the table, the rows nor the cells will have a border, so this is a more effective way to get such an effectthan having to specify a `style="border: no"` parameter everywhere.259 Note that by default tables are assigned the "wiki" CSS class, which gives a distinctive look to the header cells and a default border to the table and cells, as can be seen for the tables on this page. By removing this class (`#!table class=""`), one regains complete control on the table presentation. In particular, neither the table nor the rows nor the cells will have a border, so this is a more effective way to get such an effect rather than having to specify a `style="border: no"` parameter everywhere. 266 260 267 261 {{{#!table class="" … … 309 303 }}} 310 304 311 312 305 == HTML comments == 313 HTML comments are stripped from the output of the `html` processor. To add an HTML comment to a wiki page, use the `htmlcomment` processor (available since 0.12). For example, the following code block:306 HTML comments are stripped from the output of the `html` processor. To add an HTML comment to a wiki page, use the `htmlcomment` processor, available since Trac 0.12: 314 307 ||= Wiki Markup =|| 315 308 {{{#!td -
wiki/pages/WikiMacros
r26484 r37343 1 = Trac Macros =1 = Trac Macros 2 2 3 3 [[PageOutline]] … … 5 5 Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting. Its syntax is `[[macro-name(optional-arguments)]]`. 6 6 7 The WikiProcessors are another kind of macros. They typically deal with alternate markup formats and transformation of larger "blocks" of information (like source code highlighting). They are used for processing the multiline `{{{#!wiki-processor-name ... }}}` blocks.7 The WikiProcessors are another kind of macros. They typically deal with alternate markup formats and transformation of larger "blocks" of information, like source code highlighting. They are used for processing the multiline `{{{#!wiki-processor-name ... }}}` blocks. 8 8 9 == Using Macros ==9 == Using Macros 10 10 11 Macro calls are enclosed in two ''square brackets'' . Like Python functions, macros can also have arguments, a comma separated list within parentheses.11 Macro calls are enclosed in two ''square brackets'' `[[..]]`. Like Python functions, macros can also have arguments, a comma separated list within parentheses `[[..(,)]]`. 12 12 13 === Getting Detailed Help === 13 === Getting Detailed Help 14 14 15 The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below]. 15 16 … … 18 19 Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. `[[MacroList(MacroList)]]`, or, more conveniently, by appending a question mark (`?`) to the macro's name, like in `[[MacroList?]]`. 19 20 21 === Example 20 22 21 22 === Example === 23 24 A list of 3 most recently changed wiki pages starting with 'Trac': 23 A list of the 3 most recently changed wiki pages starting with 'Trac': 25 24 26 25 ||= Wiki Markup =||= Display =|| … … 62 61 }}} 63 62 64 == Available Macros ==63 == Available Macros 65 64 66 65 ''Note that the following list will only contain the macro documentation if you've not enabled `-OO` optimizations, or not set the `PythonOptimize` option for [wiki:TracModPython mod_python].'' … … 68 67 [[MacroList]] 69 68 70 == Macros from around the world ==69 == Macros from around the world 71 70 72 The [http://trac-hacks.org/ Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you 're looking for new macros, or have written one that you'd like to share with the world, pleasedon't hesitate to visit that site.71 The [http://trac-hacks.org/ Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share with the world, don't hesitate to visit that site. 73 72 74 == Developing Custom Macros == 73 == Developing Custom Macros 74 75 75 Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins. 76 76 77 77 For more information about developing macros, see the [trac:TracDev development resources] on the main project site. 78 78 79 Here are 2 simple examples showing how to create a Macro. Also, have a look at [trac:source:tags/trac-1.0.2/sample-plugins/Timestamp.py Timestamp.py] for an example that shows the difference between old style and new style macros and at the [trac:source:tags/trac-0.11/wiki-macros/README macros/README] which provides a little more insight about the transition. 79 80 80 Here are 2 simple examples showing how to create a Macro with Trac 0.11. 81 === Macro without arguments 81 82 82 Also, have a look at [trac:source:tags/trac-0.11/sample-plugins/Timestamp.py Timestamp.py] for an example that shows the difference between old style and new style macros and at the [trac:source:tags/trac-0.11/wiki-macros/README macros/README] which provides a little more insight about the transition.83 84 === Macro without arguments ===85 83 To test the following code, you should saved it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory. 86 84 {{{ … … 102 100 def expand_macro(self, formatter, name, text): 103 101 t = datetime.now(utc) 104 return tag. b(format_datetime(t, '%c'))102 return tag.strong(format_datetime(t, '%c')) 105 103 }}} 106 104 107 === Macro with arguments === 108 To test the following code, you should saved it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. 105 === Macro with arguments 106 107 To test the following code, you should save it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. 109 108 {{{ 110 109 #!python … … 167 166 Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it by yourself (using `return Markup.escape(result)`) or, if this is indeed HTML, wrap it in a Markup object (`return Markup(result)`) with `Markup` coming from Genshi, (`from genshi.core import Markup`). 168 167 169 You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup , for example by doing:168 You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup: 170 169 171 170 {{{ … … 177 176 178 177 class HelloWorldMacro(WikiMacroBase): 179 180 181 182 183 184 178 def expand_macro(self, formatter, name, text, args): 179 text = "whatever '''wiki''' markup you want, even containing other macros" 180 # Convert Wiki markup to HTML, new style 181 out = StringIO.StringIO() 182 Formatter(self.env, formatter.context).format(text, out) 183 return Markup(out.getvalue()) 185 184 }}} -
wiki/pages/WikiNewPage
r26484 r37343 2 2 [[TracGuideToc]] 3 3 4 Note: make sure you actually have the rights to edit wiki pages. If you don't see the **Edit this page** button, read the information relative to the editing policy for your Trac installation (usually on the front page WikiStart), or contact your local Trac administrator. 4 You can create a new wiki page by typing the CamelCase name of the page in the quick-search field at the top of the page, or by trying to view a wiki page of that name, ie by visiting for example http://trac.edgewall.org/wiki/MyNewWikiPage. Note that a page is "orphaned" by default until it is linked to from another page. 5 6 Prerequisite: make sure you actually have the rights to edit wiki pages. If you don't see the **Edit this page** button near the bottom of the page, read the information relative to the editing policy for your Trac installation, usually on the front page WikiStart, or contact your local Trac administrator. 7 8 A new wiki page can also be created as follows: 5 9 6 10 1. Choose a name for your new page. See WikiPageNames for naming conventions. 7 2. Edit an existing page (or any other resourcesthat support WikiFormatting and add a [TracLinks link] to your new page. Save your changes.11 2. Edit an existing page or any other resource that support WikiFormatting and add a [TracLinks link] to your new page. Save your changes. 8 12 3. Follow the link you created to take you to the new page. Trac will display a "describe !PageName here" message. 9 4. Click the "Edit this page" button to edit and add content to your new page. Save your changes. 10 5. All done. Your new page is published. 11 12 You can skip the second step by entering the CamelCase name of the page in the quick-search field at the top of the page. But note that the page will effectively be "orphaned" unless you link to it from somewhere else. 13 4. Click the "Edit this page" button to edit and add content to your new page. Save your changes and your new page is published. 13 14 14 15 == Rename a page #renaming 15 16 16 While picking up good WikiPageNames is important, you can always change your mind 17 and rename the page later. 17 While creating good WikiPageNames is important for usability purposes, you can always rename the page later. You will need the WIKI_RENAME permission to rename pages. 18 18 19 You'll need to ask for the WIKI_RENAME permission in order to be allowed to do this. 20 When renaming a page, you'll be offered the possibility to create a redirection page, so that links pointing to the old location will not be left dangling. 19 When renaming a page, you'll be offered the possibility to create a redirection page, so that links pointing to the old location will not be pointing to a non-existent page. 21 20 22 21 ---- -
wiki/pages/WikiPageNames
r26484 r37343 1 = Wiki Page Names =1 = Wiki Page Names 2 2 [[TracGuideToc]] 3 3 4 4 Wiki page names commonly use the CamelCase convention. Within wiki text, any word in CamelCase automatically becomes a hyperlink to the wiki page with that name. 5 5 6 CamelCase page names mustfollow these rules:6 CamelCase page names follow these rules: 7 7 8 1. The name must consist of '''alphabetic characters only''' . No digits, spaces, punctuation,or underscores are allowed.9 2. A name must have at least two capital letters.10 3. The first character must be capitalized.11 4. Every capital letter must be followed by one or more lower-case letters.12 5. The use of slash ( / ) is permitted in page names (possibly representing a hierarchy).8 1. The name must consist of '''alphabetic characters only'''; no digits, spaces, punctuation or underscores are allowed. 9 1. A name must have at least two capital letters. 10 1. The first character must be capitalized. 11 1. Every capital letter must be followed by one or more lower-case letters. 12 1. The use of slash ( / ) is permitted in page names, where it typically represents a hierarchy. 13 13 14 If you want to create a wiki page that does n't follow CamelCase rulesyou can use the following syntax:14 If you want to create a wiki page that does not follow CamelCase rules. you can use the following syntax: 15 15 {{{ 16 16 * [wiki:Wiki_page], [wiki:ISO9000], … … 28 28 * [wiki:"Space Matters"] ''(that page name embeds space characters)'' 29 29 and with a label: [wiki:"Space Matters" all about white space] 30 * or simply: ["WikiPageName"]s ''(old !MoinMoin's internal free links style)''30 * or simply: ["WikiPageName"]s 31 31 * even better, the new [[WikiCreole link style]] 32 32 and with a label: [[WikiCreole link style|WikiCreole style links]] 33 ''(since 0.12, also now adopted by !MoinMoin)''34 33 34 It is possible to link to a specific ''version'' of a Wiki page as you would do for a specific version of a file, for example: WikiStart@1. 35 35 36 Starting with Trac 0.11, it's also possible to link to a specific ''version'' of a Wiki page, as you would do for a specific version of a file, for example: WikiStart@1.36 You can also prevent a !CamelCase name from being interpreted as a [TracLinks link] by quoting it with an exclamation mark: `!CamelCase`. See TracLinks#EscapingLinks. 37 37 38 You can also prevent a CamelCase name to be interpreted as a TracLinks, by quoting it. See TracLinks#EscapingLinks.38 As in the example above, you can also append an anchor to a Wiki page name to link to a specific section within that page. The anchor can be seen by hovering the mouse over a section heading, then clicking on the [[html(¶)]] sign that appears at its end. The anchor is usually generated automatically, but it is also possible to specify it explicitly: see WikiFormatting#using-explicit-id-in-heading. 39 39 40 As visible in the example above, one can also append an anchor to a Wiki page name, in order to link to a specific section within that page. The anchor can easily be seen by hovering the mouse over a section heading, then clicking on the [[html(¶)]] sign that appears at its end. The anchor is usually generated automatically, but it's also possible to specify it explicitly: see WikiFormatting#using-explicit-id-in-heading.41 40 ---- 42 41 See also: WikiNewPage, WikiFormatting, TracWiki, TracLinks -
wiki/pages/WikiProcessors
r26484 r37343 1 = Wiki Processors =1 = Wiki Processors 2 2 3 3 Processors are WikiMacros designed to provide alternative markup formats for the [TracWiki Wiki engine]. Processors can be thought of as ''macro functions to process user-edited text''. 4 4 5 Wiki processors can be used in any Wiki text throughout Trac, 6 for various different purposes, like: 7 - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim, 8 - rendering [#HTMLrelated Wiki markup inside a context], 9 like inside <div> blocks or <span> or within <td> or <th> table cells, 10 - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and 11 [wiki:WikiRestructuredText Restructured Text], 12 or [http://www.textism.com/tools/textile/ textile] 13 14 15 == Using Processors == 16 17 To use a processor on a block of text, first delimit the lines using 18 a Wiki ''code block'': 5 Wiki processors can be used in any Wiki text throughout Trac, such as: 6 - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim 7 - rendering [#HTMLrelated Wiki markup inside a context], like inside <div> blocks or <span> or within <td> or <th> table cells 8 - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and [wiki:WikiRestructuredText Restructured Text] or [http://www.textism.com/tools/textile/ textile] 9 10 == Using Processors 11 12 To use a processor on a block of text, first delimit the lines using a Wiki ''code block'': 19 13 {{{ 20 14 {{{ … … 24 18 }}} 25 19 26 Immediately after the `{{{` or on the line just below, 27 add `#!` followed by the ''processor name''. 20 Immediately after the `{{{` or on the line just below, add `#!` followed by the ''processor name'': 28 21 29 22 {{{ … … 37 30 This is the "shebang" notation, familiar to most UNIX users. 38 31 39 Besides their content, some Wiki processors can also accept ''parameters'', 40 which are then given as `key=value` pairs after the processor name, 41 on the same line. If `value` has to contain space, as it's often the case for 42 the style parameter, a quoted string can be used (`key="value with space"`). 43 44 As some processors are meant to process Wiki markup, it's quite possible to 45 ''nest'' processor blocks. 46 You may want to indent the content of nested blocks for increased clarity, 47 this extra indentation will be ignored when processing the content. 48 49 50 == Examples == 32 Besides their content, some Wiki processors can also accept ''parameters'', which are then given as `key=value` pairs after the processor name and on the same line. If `value` has to contain space, as it's often the case for the style parameter, a quoted string can be used (`key="value with space"`). 33 34 As some processors are meant to process Wiki markup, it's quite possible to ''nest'' processor blocks. 35 You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content. 36 37 == Examples 51 38 52 39 ||= Wiki Markup =||= Display =|| … … 150 137 }}} 151 138 }}} 152 == Available Processors == 139 140 == Available Processors 153 141 154 142 The following processors are included in the Trac distribution: 155 143 156 144 || '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`) || 157 || '''`#!comment`''' || Do not process the text in this section (i.e. contents exist only in the plain text - not in the rendered page). || 158 |||| || 159 ||||= '''HTML related''' =|| 145 || '''`#!comment`''' || Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page. || 146 || '''`#!rtl`''' || Introduce a Right-To-Left block with appropriate CSS direction and styling ''(since 0.12.2)'' || 147 |||| || 148 ||||= '''[=#HTMLrelated HTML related]''' =|| 160 149 || '''`#!html`''' || Insert custom HTML in a wiki page. || 161 150 || '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page (''since 0.12''). || … … 165 154 || '''`#!td`''' || Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'') || 166 155 || '''`#!th`''' || Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'') || 167 || '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes of better visual grouping (''since 0.12'') || 156 || '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping (''since 0.12'') || 157 || '''`#!table`''' || Can optionally be used for wrapping `#!tr`, `#!td` and `#!th` blocks, for specifying table attributes. One current limitation however is that tables cannot be nested. (''since 0.12'') || 168 158 || || See WikiHtml for example usage and more details about these processors. || 169 159 |||| || … … 172 162 || '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. || 173 163 |||| || 174 ||||= ''' Code Highlighting Support''' =||164 ||||= '''[=#CodeHighlightingSupport Code Highlighting Support]''' =|| 175 165 || '''`#!c`''' [[BR]] '''`#!cpp`''' (C++) [[BR]] '''`#!python`''' [[BR]] '''`#!perl`''' [[BR]] '''`#!ruby`''' [[BR]] '''`#!php`''' [[BR]] '''`#!asp`''' [[BR]] '''`#!java`''' [[BR]] '''`#!js`''' (Javascript) [[BR]] '''`#!sql`''' [[BR]] '''`#!xml`''' (XML or HTML) [[BR]] '''`#!sh`''' (!Bourne/Bash shell) [[BR]] '''etc.''' [[BR]] || Trac includes processors to provide inline syntax highlighting for source code in various languages. [[BR]] [[BR]] Trac relies on external software packages for syntax coloring, like [http://pygments.org Pygments]. [[BR]] [[BR]] See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. || 176 166 |||| || 167 168 Since 1.1.2 the default, coding highlighting and MIME-type processors support the argument `lineno` for adding line numbering to the code block. When a value is specified, as in `lineno=3`, the numbering will start at the specified value. When used in combination with the `lineno` argument, the `marks` argument is also supported for highlighting lines. A single line number, set of line numbers and range of line numbers are allowed. For example, `marks=3`, `marks=3-6`, `marks=3,5,7` and `marks=3-5,7` are all allowed. The specified values are relative to the numbered lines, so if `lineno=2` is specified to start the line numbering at 2, `marks=2` will result in the first line being highlighted. 177 169 178 170 Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. … … 243 235 }}} 244 236 245 For more processor macros developed and/or contributed by users, visit: 246 * [trac:ProcessorBazaar] 247 * [trac:MacroBazaar] 248 * [http://trac-hacks.org Trac Hacks] community site 249 250 Developing processors is no different from Wiki macros. 251 In fact they work the same way, only the usage syntax differs. 252 See WikiMacros#DevelopingCustomMacros for more information. 253 237 Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//. 238 {{{ 239 {{{#!python lineno=3 marks=3,9-10,16 240 def expand_markup(stream, ctxt=None): 241 """A Genshi stream filter for expanding `genshi.Markup` events. 242 243 Note: Expansion may not be possible if the fragment is badly 244 formed, or partial. 245 """ 246 for event in stream: 247 if isinstance(event[1], Markup): 248 try: 249 for subevent in HTML(event[1]): 250 yield subevent 251 except ParseError: 252 yield event 253 else: 254 yield event 255 }}} 256 }}} 257 {{{#!python lineno=3 marks=3,9-10,16 258 def expand_markup(stream, ctxt=None): 259 """A Genshi stream filter for expanding `genshi.Markup` events. 260 261 Note: Expansion may not be possible if the fragment is badly 262 formed, or partial. 263 """ 264 for event in stream: 265 if isinstance(event[1], Markup): 266 try: 267 for subevent in HTML(event[1]): 268 yield subevent 269 except ParseError: 270 yield event 271 else: 272 yield event 273 }}} 274 275 For more processor macros developed and/or contributed by users, visit the [th:WikiStart Trac Hacks] community site. 276 277 Developing processors is no different from Wiki macros. In fact, they work the same way, only the usage syntax differs. See WikiMacros#DevelopingCustomMacros for more information. 254 278 255 279 ---- -
wiki/pages/WikiRestructuredText
r26484 r37343 1 1 = reStructuredText Support in Trac = 2 2 3 Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any contextWikiFormatting is used.3 Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used. 4 4 5 5 From the reStucturedText webpage: 6 6 "''reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. ''" 7 7 8 If you want a file from your Subversion repository be displayed as reStructuredText in Trac's source browser, set `text/x-rst` asvalue for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example].8 If you want a file from your Subversion repository to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type`. See [trac:source:/trunk/INSTALL this example]. 9 9 10 10 === Requirements === 11 Note that to activate RST support in Trac, the python docutils package must be installed. 12 If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. 13 14 Install docutils using `easy_install docutils`. Do not use the package manager of your OS (e.g. `apt-get install python-docutils`), because Trac will not find docutils then. 11 To activate RST support in Trac, install the python docutils package: `easy_install docutils`. If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website]. 12 13 Do not use the package manager of your OS, eg `apt-get install python-docutils`, because Trac will not find docutils then. 15 14 16 15 === More information on RST === … … 70 69 For a complete example of all uses of the `:trac:` role, please see WikiRestructuredTextLinks. 71 70 72 73 71 === Syntax highlighting in reStructuredText === 74 72 75 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called 76 code-block 73 There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block: 77 74 78 75 ||= Wiki Markup ||= Display || … … 109 106 === Wiki Macros in reStructuredText === 110 107 111 For doing [WikiMacros Wiki Macros] in RST you use the same directive as for syntax highlighting i.e code-block. 108 To enable [WikiMacros Wiki Macros] in RST, you use the same directive as for syntax highlighting, ie code-block: 112 109 113 110 ||= Wiki Markup ||= Display || … … 135 132 }}} 136 133 137 Or a more concise Wiki Macro 134 Or a more concise Wiki Macro-like syntax is also available, using the `:code-block:` role: 138 135 139 136 ||= Wiki Markup ||= Display || … … 156 153 157 154 === Bigger RST Example === 158 The example below should be mostlyself-explanatory:155 The example below should be self-explanatory: 159 156 160 157 ||= Wiki Markup ||= Display || -
wiki/pages/WikiRestructuredTextLinks
r26484 r37343 1 1 = TracLinks in reStructuredText = 2 2 3 This document illustrates how to use the `:trac:` role in reStructuredText. The page is written like:3 This document illustrates how to use the `:trac:` role in [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText]. The page is written like: 4 4 5 5 {{{ … … 13 13 * Changesets: :trac:`r1`, :trac:`[1]` or :trac:`changeset:1` 14 14 * Revision log: :trac:`r1:3`, :trac:`[1:3]` or :trac:`log:@1:3`, :trac:`log:trunk@1:3` 15 * Diffs (since version 0.10): :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539`15 * Diffs: :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539` 16 16 * Wiki pages: :trac:`CamelCase` or :trac:`wiki:CamelCase` 17 17 * Milestones: :trac:`milestone:1.0` … … 27 27 }}} 28 28 29 Provided you have docutilsinstalled, the above block will render as:29 Provided you have [http://docutils.sourceforge.net/ docutils] installed, the above block will render as: 30 30 ---- 31 31 {{{ … … 38 38 * Changesets: :trac:`r1`, :trac:`[1]` or :trac:`changeset:1` 39 39 * Revision log: :trac:`r1:3`, :trac:`[1:3]` or :trac:`log:@1:3`, :trac:`log:trunk@1:3` 40 * Diffs (since version 0.10): :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539`40 * Diffs: :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539` 41 41 * Wiki pages: :trac:`CamelCase` or :trac:`wiki:CamelCase` 42 42 * Milestones: :trac:`milestone:1.0` … … 52 52 ---- 53 53 54 Note also that any ofthe above could have been written using substitution references and the `trac::` directive:54 Note that the above could have been written using substitution references and the `trac::` directive: 55 55 {{{ 56 56 {{{ -
wiki/pages/WikiStart
r37342 r37343 1 [[CollapsibleStart(Title-of-Structure)]] 1 = Welcome to Trac 1.2 = 2 2 3 WikiFormatted text inside foldable structure. 3 Trac is a '''minimalistic''' approach to '''web-based''' management of 4 '''software projects'''. Its goal is to simplify effective tracking and handling of software issues, enhancements and overall progress. 4 5 5 [[CollapsibleEnd]] 6 All aspects of Trac have been designed with the single goal to 7 '''help developers write great software''' while '''staying out of the way''' 8 and imposing as little as possible on a team's established process and 9 culture. 10 11 As all Wiki pages, this page is editable, this means that you can 12 modify the contents of this page simply by using your 13 web-browser. Simply click on the "Edit this page" link at the bottom 14 of the page. WikiFormatting will give you a detailed description of 15 available Wiki formatting commands. 16 17 "[wiki:TracAdmin trac-admin] ''yourenvdir'' initenv" created 18 a new Trac environment, containing a default set of wiki pages and some sample 19 data. This newly created environment also contains 20 [wiki:TracGuide documentation] to help you get started with your project. 21 22 You can use [wiki:TracAdmin trac-admin] to configure 23 [http://trac.edgewall.org/ Trac] to better fit your project, especially in 24 regard to ''components'', ''versions'' and ''milestones''. 6 25 7 26 8 [[CollapsibleStart]] 27 TracGuide is a good place to start. 9 28 10 WikiFormatted text inside foldable structure. 29 Enjoy! [[BR]] 30 ''The Trac Team'' 11 31 12 [[CollapsibleEnd]] 32 == Starting Points == 13 33 34 * TracGuide -- Built-in Documentation 35 * [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project 36 * [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions 37 * TracSupport -- Trac Support 14 38 15 {{{#!Fold title="A title for the folded section" tag=h2 16 This section of the wiki page is folded up and can be expanded by clicking on the title. 17 18 This can contain any ''formatted'' **wiki** content, including macros and nested Fold sections. 19 }}} 39 For a complete list of local wiki pages, see TitleIndex.
Note: See TracChangeset
for help on using the changeset viewer.