Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInstall URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInstall?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInstall (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInstall Sat Nov 15 01:14:46 2014 @@ -1,24 +1,30 @@ -= Trac Installation Guide for 1.0 = +{{{#!div style="margin-top: .5em; padding: 0 1em; background-color: #ffd; border:1px outset #ddc; text-align: center" + + '''NOTE: the information in this page applies to Trac 1.0, the current version of Trac. \\ + For installing previous Trac versions, please refer to [[wiki:0.12/TracInstall]] (for Trac 0.12)''' +}}} + += Trac Installation Guide for 1.0 [[TracGuideToc]] Trac is written in the Python programming language and needs a database, [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], or [http://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://genshi.edgewall.org Genshi] templating system. -Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default english version, as usual. +Since version 0.12, Trac can also be localized, and there's probably a translation available for your language. If you want to be able to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version, as usual. -If you're interested in contributing new translations for other languages or enhance the existing translations, then please have a look at [[trac:TracL10N]]. +If you're interested in contributing new translations for other languages or enhance the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N]. What follows are generic instructions for installing and setting up Trac and its requirements. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to '''first read through these general instructions''' to get a good understanding of the tasks involved. [[PageOutline(2-3,Installation Steps,inline)]] -== Dependencies == +== Dependencies === Mandatory Dependencies To install Trac, the following software packages must be installed: * [http://www.python.org/ Python], version >= 2.5 and < 3.0 (note that we dropped the support for Python 2.4 in this release) - * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6, or better yet, [http://pypi.python.org/pypi/distribute distribute] - * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 (unreleased version 0.7dev should work as well) + * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.6 + * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL. @@ -27,10 +33,10 @@ The database can be either SQLite, Postg As you must be using Python 2.5, 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module). -However, if you'd like, you can download the latest and greatest version of [[trac:Pysqlite]] from +However, if you'd like, you can download the latest and greatest version of [[trac:PySqlite]] from [http://code.google.com/p/pysqlite/downloads/list google code], where you'll find the Windows installers or the `tar.gz` archive for building from source: -{{{ +{{{#!sh $ tar xvfz <version>.tar.gz $ cd <version> $ python setup.py build_static install @@ -40,7 +46,7 @@ This will download the latest SQLite cod SQLite 2.x is no longer supported. -A known bug PySqlite versions 2.5.2-4 prohibits upgrade of trac databases +A known bug in PySqlite versions 2.5.2-4 prohibits upgrades of Trac databases from 0.11.x to 0.12. Please use versions 2.5.5 and newer or 2.5.1 and older. See #9434 for more detail. @@ -50,7 +56,7 @@ See additional information in [trac:PySq You need to install the database and its Python bindings: * [http://www.postgresql.org/ PostgreSQL], version 8.0 or later - * [http://pypi.python.org/pypi/psycopg2 psycopg2] + * [http://pypi.python.org/pypi/psycopg2 psycopg2], version 2.0 or later See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details. @@ -66,9 +72,9 @@ It is '''very''' important to read caref === Optional Dependencies -==== Version Control System ==== +==== Version Control System -===== Subversion ===== +===== Subversion * [http://subversion.apache.org/ Subversion], 1.5.x or 1.6.x and the '''''corresponding''''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. should still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. TracSubversion points you to [http://alagazam.net Algazam], which works for me under Python 2.6.) @@ -79,18 +85,18 @@ Note that Trac '''doesn't''' use [http:/ '''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. -===== Others ===== +===== Others Support for other version control systems is provided via third-parties. See [trac:PluginList] and [trac:VersionControlSystem]. -==== Web Server ==== -A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server ] section below. +==== Web Server +A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below. -Alternatively you configure Trac to run in any of the following environments. +Alternatively you can configure Trac to run in any of the following environments. * [http://httpd.apache.org/ Apache] with - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac - - [http://modpython.org/ mod_python 3.3.1], deprecated: see TracModPython) + - [http://modpython.org/ mod_python 3.3.1], (deprecated: see TracModPython) * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi) * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp]) @@ -98,13 +104,13 @@ Alternatively you configure Trac to run is highly discouraged''', better use one of the previous options. -==== Other Python Packages ==== +==== Other Python Packages * [http://babel.edgewall.org Babel], version >= 0.9.5, needed for localization support (unreleased version 1.0dev should work as well) * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9 for WikiRestructuredText. - * [http://pygments.pocoo.org Pygments] for + * [http://pygments.org Pygments] for [wiki:TracSyntaxColoring syntax highlighting]. [http://silvercity.sourceforge.net/ SilverCity] and/or [http://gnu.org/software/enscript/enscript.html Enscript] may still be used @@ -113,106 +119,109 @@ Alternatively you configure Trac to run otherwise Trac will fall back on a shorter list from an internal time zone implementation. -'''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel]. +'''Attention''': The various available versions of these dependencies are not necessarily interchangeable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel]. Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing'' (there are even some pages that are still talking about Trac 0.8!). -== Installing Trac == +== Installing Trac === Using `easy_install` One way to install Trac is using [http://pypi.python.org/pypi/setuptools setuptools]. -With setuptools you can install Trac from the subversion repository; +With setuptools you can install Trac from the Subversion repository; A few examples: - - install Trac 1.0: - {{{ + - Install Trac 1.0: + {{{#!sh easy_install Trac==1.0 }}} - (NOT YET ENABLED) - - install latest development version 1.0dev: - {{{ + - Install latest development version: + {{{#!sh easy_install Trac==dev }}} Note that in this case you won't have the possibility to run a localized version of Trac; either use a released version or install from source +{{{#!div style="border: 1pt dotted; margin: 1em" +**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. More information may be found in the sections on [#RunningtheStandaloneServer Running The Standalone Server] and [#RunningTraconaWebServer Running Trac on a Web Server]. +}}} + === Using `pip` 'pip' is an easy_install replacement that is very useful to quickly install python packages. -To get a trac installation up and running in less than 5 minutes: +To get a Trac installation up and running in less than 5 minutes: Assuming you want to have your entire pip installation in `/opt/user/trac` - -{{{ -pip -E /opt/user/trac install trac psycopg2 + {{{#!sh +pip install trac psycopg2 }}} or - -{{{ -pip -E /opt/user/trac install trac mysql-python + {{{#!sh +pip install trac mysql-python }}} -Make sure your OS specific headers are available for pip to automatically build PostgreSQL (libpq-dev) or MySQL (libmysqlclient-dev) bindings. +Make sure your OS specific headers are available for pip to automatically build PostgreSQL (`libpq-dev`) or MySQL (`libmysqlclient-dev`) bindings. pip will automatically resolve all dependencies (like Genshi, pygments, etc.) and download the latest packages on pypi.python.org and create a self contained installation in `/opt/user/trac`. All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive) -Additionally, you can install several trac plugins (listed [http://pypi.python.org/pypi?:action=search&term=trac&submit=search here]) through pip. +Additionally, you can install several Trac plugins (listed [http://pypi.python.org/pypi?:action=search&term=trac&submit=search here]) through pip. === From source Of course, using the python-typical setup at the top of the source directory also works. -You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. Trac-1.0.tar.gz), or you can get the source directly from the repository (see Trac:SubversionRepository for details). +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). -{{{ +{{{#!sh $ python ./setup.py install }}} ''You'll need root permissions or equivalent for this step.'' -This will byte-compile the python source code and install it as an .egg file or folder in the `site-packages` directory -of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates. +This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory +of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as `htdocs` and `templates`. The script will also install the [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments], as well as the [wiki:TracStandalone tracd] standalone server. -If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed): -{{{ +If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed): +{{{#!sh $ python ./setup.py install }}} -Alternatively, you can do a `bdist_egg` and copy the .egg from dist/ to the place of your choice, or you can create a Windows installer (`bdist_wininst`). +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`). -=== Advanced Options === +=== Advanced Options To install Trac to a custom location, or find out about other advanced installation options, run: -{{{ +{{{#!sh easy_install --help }}} -Also see [http://docs.python.org/inst/inst.html Installing Python Modules] for detailed information. +Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information. Specifically, you might be interested in: -{{{ +{{{#!sh easy_install --prefix=/path/to/installdir }}} -or, if installing Trac to a Mac OS X system: -{{{ +or, if installing Trac on a Mac OS X system: +{{{#!sh easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages }}} -Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.6/site-packages }}} by default +Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.6/site-packages }}} by default. The above will place your `tracd` and `trac-admin` commands into `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.5/site-packages`, which is Apple's preferred location for third-party Python application installations. -== Creating a Project Environment == +== Creating a Project Environment A [TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable [TracIni configuration file], and various other files and directories. A new environment is created using [wiki:TracAdmin trac-admin]: -{{{ +{{{#!sh $ trac-admin /path/to/myproject initenv }}} @@ -221,15 +230,19 @@ $ trac-admin /path/to/myproject initenv Using the default database connection string in particular will always work as long as you have SQLite installed. For the other [DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point. -Since 0.12, Trac doesn't ask for a [TracEnvironment#SourceCodeRepository source code repository] anymore when creating an environment. Repositories can be [TracRepositoryAdmin added] afterward, or the version control support can be disabled completely if you don't need it. +Since 0.12, Trac doesn't ask for a [TracEnvironment#SourceCodeRepository source code repository] anymore when creating an environment. Repositories can be [TracRepositoryAdmin added] afterwards, and support for specific version control systems is disabled by default. Also note that the values you specify here can be changed later by directly editing the [TracIni conf/trac.ini] configuration file. +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), 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 (though the best advice is to opt for a platform with sub-second timestamp resolution when possible regardless of the version of Trac you are running). + Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter: -{{{ -# chown -R apache.apache /path/to/myproject +{{{#!sh +$ chown -R apache.apache /path/to/myproject }}} +The actual username and groupname of the apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use). + {{{#!div class=important '''Warning:''' Please only use ASCII-characters for account name and project path, unicode characters are not supported there. }}} @@ -237,19 +250,33 @@ Finally, make sure the user account unde == Deploying Trac -=== Running the Standalone Server === +=== Running the Standalone Server After having created a Trac environment, you can easily try the web interface by running the standalone server [wiki:TracStandalone tracd]: -{{{ +{{{#!sh $ tracd --port 8000 /path/to/myproject }}} Then, fire up a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that `tracd` knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this: -{{{ +{{{#!sh $ tracd -s --port 8000 /path/to/myproject }}} -=== Running Trac on a Web Server === +{{{#!div style="border: 1pt dotted; margin: 1em" +**Setuptools Warning:** If the version of your setuptools is in the range 5.4 through 5.6, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` must be set in order to avoid significant performance degradation. The environment variable can be set system-wide, or for just the user that runs the `tracd` process. There are several ways to accomplish this in addition to what is discussed here, and depending on the distribution of your OS. + +To be effective system-wide a shell script with the `export` statement may be added to `/etc/profile.d`. To be effective for a user session the `export` statement may be added to `~/.profile`. +{{{#!sh +export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 +}}} + +Alternatively, the variable can be set in the shell before executing `tracd`: +{{{#!sh +$ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject +}}} +}}} + +=== Running Trac on a Web Server Trac provides various options for connecting to a "real" web server: - [wiki:TracFastCgi FastCGI] @@ -259,20 +286,21 @@ Trac provides various options for connec Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc. -==== Generating the Trac cgi-bin directory ==== #cgi-bin +==== Generating the Trac cgi-bin directory #cgi-bin In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [wiki:TracAdmin trac-admin]. There is, however, a bit of a chicken-and-egg problem. The [wiki:TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this: -{{{ +{{{#!sh mkdir -p /usr/share/trac/projects/my-project trac-admin /usr/share/trac/projects/my-project initenv trac-admin /usr/share/trac/projects/my-project deploy /tmp/deploy mv /tmp/deploy/* /usr/share/trac }}} +Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory. -==== Mapping Static Resources ==== +==== Mapping Static Resources Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance). @@ -288,15 +316,15 @@ The target `<directory>` will then conta - `common/` - the static resources of Trac itself - `<plugins>/` - one directory for each resource directory managed by the plugins enabled for this environment -===== Example: Apache and `ScriptAlias` ===== #ScriptAlias-example +===== Example: Apache and `ScriptAlias` #ScriptAlias-example Assuming the deployment has been done this way: -{{{ +{{{#!sh $ trac-admin /var/trac/env deploy /path/to/trac/htdocs/common }}} Add the following snippet to Apache configuration ''before'' the `ScriptAlias` or `WSGIScriptAlias` (which map all the other requests to the Trac application), changing paths to match your deployment: -{{{ +{{{#!apache Alias /trac/chrome/common /path/to/trac/htdocs/common Alias /trac/chrome/site /path/to/trac/htdocs/site @@ -307,7 +335,7 @@ Alias /trac/chrome/site /path/to/trac/ht }}} If using mod_python, you might want to add this too (otherwise, the alias will be ignored): -{{{ +{{{#!apache <Location "/trac/chrome/common/"> SetHandler None </Location> @@ -316,7 +344,7 @@ If using mod_python, you might want to a 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. Similarly, if you have static resources in a project's `htdocs` directory (which is referenced by `/trac/chrome/site` URL in themes), you can configure Apache to serve those resources (again, put this ''before'' the `ScriptAlias` or `WSGIScriptAlias` for the .*cgi scripts, and adjust names and locations to match your installation): -{{{ +{{{#!apache Alias /trac/chrome/site /path/to/projectenv/htdocs <Directory "/path/to/projectenv/htdocs"> @@ -326,25 +354,25 @@ Alias /trac/chrome/site /path/to/project }}} 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: -{{{ +{{{#!ini [trac] htdocs_location = http://static.example.org/trac-common/ }}} Note that this makes it easy to have a dedicated domain serve those static resources (preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less]). Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server: -{{{ +{{{#!sh $ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common }}} -==== Setting up the Plugin Cache ==== +==== Setting up the Plugin Cache -Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions on how to set environment variables. +Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the `PYTHON_EGG_CACHE` environment variable. Refer to your server documentation for detailed instructions on how to set environment variables. -== Configuring Authentication == +== Configuring Authentication -Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the REMOTE_USER variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info. +Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the `REMOTE_USER` variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info. The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. @@ -353,28 +381,46 @@ Please refer to one of the following sec * [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`. * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx) +The following document also constains some useful information for beginners: [trac:TracAuthenticationIntroduction]. + == Granting admin rights to the admin user Grant admin rights to user admin: -{{{ +{{{#!sh $ trac-admin /path/to/myproject permission add admin TRAC_ADMIN }}} -This user will have an "Admin" entry menu that will allow you to admin your trac project. +This user will have an "Admin" entry menu that will allow you to administrate your Trac project. == Finishing the install -=== Automatic reference to the SVN changesets in Trac tickets === +=== Enable version control components + +Support for version control systems is provided by optional components in Trac and the components are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them. See TracRepositoryAdmin for more details. + +The components can be enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel. + +{{{#!ini +tracopt.versioncontrol.svn.* = enabled +}}} + +{{{#!ini +tracopt.versioncontrol.git.* = enabled +}}} + +After enabling the components, repositories can be configured through the "Repositories" admin panel or by editing [TracIni#repositories-section trac.ini]. + +=== Automatic reference to the SVN changesets in Trac tickets You can configure SVN to automatically add a reference to the changeset into the ticket comments, whenever changes are committed to the repository. The description of the commit needs to contain one of the following formulas: * '''`Refs #123`''' - to reference this changeset in `#123` ticket * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed'' This functionality requires a post-commit hook to be installed as described in [wiki:TracRepositoryAdmin#ExplicitSync TracRepositoryAdmin], and enabling the optional commit updater components by adding the following line to the `[components]` section of your [wiki:TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel. -{{{ +{{{#!ini tracopt.ticket.commit_updater.* = enabled }}} For more information, see the documentation of the `CommitTicketUpdater` component in the "Plugins" admin panel. -=== Using Trac === +=== Using Trac Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.
Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInterfaceCustomization URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInterfaceCustomization?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInterfaceCustomization (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracInterfaceCustomization Sat Nov 15 01:14:46 2014 @@ -33,7 +33,7 @@ Icons should be a 32x32 image in `.gif` icon = site/my_icon.ico }}} -Note though that this icon is ignored by Internet Explorer, which only accepts a file named ``favicon.ico`` at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from ``trac.ini`` as follows: +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: {{{ [project] @@ -98,7 +98,7 @@ header and footer. Save the following co </html> }}} -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. +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-section|[trac] htdocs_location]] configuration setting. `site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find and modify them. @@ -135,7 +135,7 @@ If the environment is upgraded from 0.10 </form> }}} -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. +Also note that the `site.html` (despite its name) can be put in a shared templates directory - see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets. == Project List == #ProjectList @@ -220,4 +220,4 @@ Trac resolves requests for a template by Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server. ---- -See also TracGuide, TracIni +See also TracGuide, TracIni \ No newline at end of file Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracLinks URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracLinks?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracLinks (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracLinks Sat Nov 15 01:14:46 2014 @@ -27,7 +27,7 @@ and any other text fields explicitly mar Reports :: `{1}` or `report:1` Milestones :: `milestone:1.0` Attachment :: `attachment:example.tgz` (for current page attachment), `attachment:attachment.1073.diff:ticket:944` (absolute path) - Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk` + Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`, `[1/repository]` Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]` Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`, `diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` @@ -42,7 +42,7 @@ and any other text fields explicitly mar Reports :: {1} or report:1 Milestones :: milestone:1.0 Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path) - Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk + Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository] Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk] Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default @@ -315,13 +315,15 @@ Example: === timeline: links === -Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but alternatively you can specify your local time, followed by your timezone if you don't want to compute the UTC time. +Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC. Examples: - `timeline:2008-01-29` - `timeline:2008-01-29T15:48` - `timeline:2008-01-29T15:48Z` - `timeline:2008-01-29T16:48+01` + - `timeline:2008-01-29T16:48+0100` + - `timeline:2008-01-29T16:48+01:00` ''(since Trac 0.11)'' @@ -349,9 +351,9 @@ If the revision is specified, one can ev - `source:/some/file@123#L10` - `source:/tag/0.10@head#L10` -Finally, one can also highlight an arbitrary set of lines: - - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103. - ''(since 0.11)'' +Finally, one can also highlight an arbitrary set of lines ''(since 0.11)'': + - `source:/some/file@123:10-20,100,103#L99` - highlight lines 10 to 20, and lines 100 and 103, and target line 99 + - or without version number (the `@` is still needed): `source:/some/file@:10-20,100,103#L99`. Version can be omitted when the path is pointing to a source file that will no longer change (like `source:/tags/...`), otherwise it's better to specify which lines of //which version// of the file you're talking about Note that in presence of multiple repositories, the name of the repository is simply integrated in the path you specify for `source:` (e.g. `source:reponame/trunk/README`). ''(since 0.12)'' @@ -386,4 +388,4 @@ In the presence of multiple repositories ---- See also: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki - + \ No newline at end of file Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracModWSGI URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracModWSGI?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracModWSGI (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracModWSGI Sat Nov 15 01:14:46 2014 @@ -1,7 +1,7 @@ = Trac and mod_wsgi = -[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. +[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 performance. [[PageOutline(2-3,Overview,inline)]] @@ -24,6 +24,16 @@ application = trac.web.main.dispatch_req 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. +On Windows: + - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example: +{{{#!python +os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs' +}}} + - If run under a Window service, you should create a directory for Python Egg cache. +{{{#!python +os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs' +}}} + === A more elaborate script If you'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. @@ -72,7 +82,7 @@ WSGIScriptAlias /trac /usr/local/trac/my Here, the script is in a subdirectory of the Trac environment. -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: +If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following: {{{ WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi @@ -171,6 +181,8 @@ The "trac" parameter above is the "realm For multiple environments, you can use the same `LocationMatch` as described with the previous method. +'''Note: `Location` cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity. ''' + Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system: {{{ LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so @@ -307,7 +319,7 @@ This will generally be matched with an A Require valid-user </Location> }}} -Note that '''authFile''' need not exist. See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server. +Note that '''authFile''' need not exist (unless you are using Account Manager older than 0.4). See the !HttpAuthStore link above for examples where multiple Trac projects are hosted on a server. === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host @@ -387,14 +399,14 @@ A somewhat brutal workaround is to disab But it's not necessary to edit the source of Trac, the following lines in `trac.wsgi` will also work: -{{{ +{{{#!python import trac.db.postgres_backend trac.db.postgres_backend.PostgreSQLConnection.poolable = False }}} or -{{{ +{{{#!python import trac.db.mysql_backend trac.db.mysql_backend.MySQLConnection.poolable = False }}} Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracNotification URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracNotification?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracNotification (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracNotification Sat Nov 15 01:14:46 2014 @@ -27,41 +27,7 @@ When using apache and mod_kerb for authe === Configuration Options === These are the available options for the `[notification]` section in trac.ini. - * '''`smtp_enabled`''': Enable email notification. - * '''`smtp_from`''': Email address to use for ''Sender''-headers in notification emails. - * '''`smtp_from_name`''': Sender name to use for ''Sender''-headers in notification emails. - * '''`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. - * '''`smtp_replyto`''': Email address to use for ''Reply-To''-headers in notification emails. - * '''`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. - * '''`smtp_always_cc`''': List of email addresses to always send notifications to. ''Typically used to post ticket changes to a dedicated mailing list.'' - * '''`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 - * '''`smtp_subject_prefix`''': (''since 0.10.1'') Text that is inserted before the subject of the email. Set to "!__default!__" by default. - * '''`always_notify_reporter`''': Always send notifications to any address in the reporter field (default: false). - * '''`always_notify_owner`''': (''since 0.9'') Always send notifications to the address in the owner field (default: false). - * '''`always_notify_updater`''': (''since 0.10'') Always send a notification to the updater of a ticket (default: true). - * '''`use_public_cc`''': (''since 0.10'') Addresses in To: (owner, reporter) and Cc: lists are visible by all recipients (default is ''Bcc:'' - hidden copy). - * '''`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. - * '''`ignore_domains`''': Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains). - * '''`mime_encoding`''': (''since 0.10'') This option allows selecting the MIME encoding scheme. Supported values: - * `none`: default value, uses 7bit encoding if the text is plain ASCII, or 8bit otherwise. - * `base64`: works with any kind of content. May cause some issues with touchy anti-spam/anti-virus engines. - * `qp` or `quoted-printable`: best for european languages (more compact than base64) if 8bit encoding cannot be used. - * '''`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. - * '''`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: - * `SmtpEmailSender`: connects to an SMTP server (default). - * `SendmailEmailSender`: runs a `sendmail`-compatible executable. - -Either '''`smtp_from`''' or '''`smtp_replyto`''' (or both) ''must'' be set, otherwise Trac refuses to send notification mails. - -The following options are specific to email delivery through SMTP. - * '''`smtp_server`''': SMTP server used for notification messages. - * '''`smtp_port`''': (''since 0.9'') Port used to contact the SMTP server. - * '''`smtp_user`''': (''since 0.9'') User name for authentication SMTP account. - * '''`smtp_password`''': (''since 0.9'') Password for authentication SMTP account. - * '''`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. - -The following option is specific to email delivery through a `sendmail`-compatible executable. - * '''`sendmail_path`''': (''since 0.12'') Path to the sendmail executable. The sendmail program must accept the `-i` and `-f` options. +[[TracIni(notification)]] === Example Configuration (SMTP) === {{{ @@ -98,7 +64,7 @@ The following variables are available in === Customizing the e-mail content === -The notification e-mail content is generated based on `ticket_notify_email.txt` in `trac/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: +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: {{{ $ticket_body_hdr @@ -245,17 +211,12 @@ smtp_password = password where ''user'' and ''password'' match an existing GMail account, ''i.e.'' the ones you use to log in on [http://gmail.com] Alternatively, you can use `smtp_port = 25`.[[br]] -You should not use `smtp_port = 465`. 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. +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 [trac:comment:2:ticket:7107 #7107] for details. -== Filtering notifications for one's own changes == +== Filtering notifications for one's own changes and comments == In Gmail, use the filter: {{{ -from:(<smtp_from>) (("Reporter: <username>" -Changes) OR "Changes (by <username>)") -}}} - -For Trac .10, use the filter: -{{{ from:(<smtp_from>) (("Reporter: <username>" -Changes -Comment) OR "Changes (by <username>)" OR "Comment (by <username>)") }}} @@ -264,11 +225,8 @@ to delete these notifications. In Thunderbird, there is no such solution if you use IMAP (see http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body). -The best you can do is to set "always_notify_updater" in conf/trac.ini to false. -You will however still get an email if you comment a ticket that you own or have reported. - You can also add this plugin: -http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin +http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin, or vote for [trac:#2247] to be fixed. == Troubleshooting == Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPermissions URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPermissions?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPermissions (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPermissions Sat Nov 15 01:14:46 2014 @@ -13,7 +13,7 @@ In addition to these privileges, users c == Graphical Admin Tab == ''This feature is new in version 0.11.'' -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): +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): {{{ $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN }}} @@ -26,6 +26,8 @@ Then, the user `bob` will be able to see 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. +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. + == Available Privileges == 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. @@ -97,7 +99,7 @@ Attention: the "view tickets" button app == Creating New Privileges == -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. +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. == Granting Privileges == Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPlugins URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPlugins?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPlugins (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracPlugins Sat Nov 15 01:14:46 2014 @@ -168,6 +168,7 @@ If you install a plugin globally (i.e., * ...you actually added the necessary line(s) to the `[components]` section. * ...the package/module names are correct. * ...the value is "enabled", not "enable" or "Enable". + * ...the section name is "components", not "component". === Check the permissions on the .egg file === Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracQuery URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracQuery?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracQuery (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracQuery Sat Nov 15 01:14:46 2014 @@ -83,7 +83,7 @@ A more compact representation without th This is displayed as: [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]] -Finally, if you wish to receive only the number of defects that match the query, use the ``count`` parameter. +Finally, if you wish to receive only the number of defects that match the query, use the `count` parameter. {{{ [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]] Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracReports URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracReports?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracReports (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracReports Sat Nov 15 01:14:46 2014 @@ -135,7 +135,6 @@ Example: http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical }}} -Dynamic variables can also be used in the report title and description (since 1.1.1). === !Special/Constant Variables === There is one dynamic variable whose value is set automatically (the URL does not have to be changed) to allow practical reports. @@ -163,6 +162,7 @@ final report. * '''ticket''' â Ticket ID number. Becomes a hyperlink to that ticket. * '''id''' â same as '''ticket''' above when '''realm''' is not set * '''realm''' â together with '''id''', can be used to create links to other resources than tickets (e.g. a realm of ''wiki'' and an ''id'' to a page name will create a link to that wiki page) + - for some kind of resources, it may be necessary to specify their ''parent'' resources (e.g. for ''changeset'', which ''repos'') and this can be achieved using the '''parent_realm''' and '''parent_id''' columns * '''created, modified, date, time''' â Format cell as a date and/or time. * '''description''' â Ticket description field, parsed through the wiki engine. Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracRepositoryAdmin URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracRepositoryAdmin?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracRepositoryAdmin (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracRepositoryAdmin Sat Nov 15 01:14:46 2014 @@ -89,7 +89,7 @@ There is also new functionality in the f Please note that at the time of writing, no initial resynchronization or any hooks are necessary for Mercurial repositories - see [trac:#9485] for more information. === Explicit synchronization === #ExplicitSync -This is the preferred method of repository synchronization. It requires setting the `[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-change hook as well. +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-change` hook as well. `changeset added <repos> <rev> [...]`:: Notify Trac that one or more changesets have been added to a repository. @@ -99,7 +99,9 @@ This is the preferred method of reposito The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository. -Note that you may have to set the environment variable PYTHON_EGG_CACHE to the same value as was used for the web server configuration before calling trac-admin, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information. +Note that you may have to set the environment variable `PYTHON_EGG_CACHE` to the same value as was used for the web server configuration before calling `trac-admin`, if you changed it from its default location. See [wiki:TracPlugins Trac Plugins] for more information. + +==== Subversion ==== The following examples are complete post-commit and post-revprop-change scripts for Subversion. They should be edited for the specific environment, marked executable (where applicable) and placed in the `hooks` directory of each repository. On Unix (`post-commit`): {{{#!sh @@ -107,14 +109,9 @@ The following examples are complete post export PYTHON_EGG_CACHE="/path/to/dir" /usr/bin/trac-admin /path/to/env changeset added "$1" "$2" }}} -Note: Ubuntu doesn't seem to like /usr/bin/trac-admin, so just use: -{{{#!sh -#!/bin/sh -export PYTHON_EGG_CACHE="/path/to/dir" -trac-admin /path/to/env/ changeset added "$1" "$2" -}}} +Note: Check with `whereis trac-admin`, whether `trac-admin` is really installed under `/usr/bin/` or maybe under `/usr/local/bin/` and adapt the path. On Windows (`post-commit.cmd`): -{{{#!application/x-dos-batch +{{{#!bat @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2" }}} @@ -125,7 +122,7 @@ export PYTHON_EGG_CACHE="/path/to/dir" /usr/bin/trac-admin /path/to/env changeset modified "$1" "$2" }}} On Windows (`post-revprop-change.cmd`): -{{{#!application/x-dos-batch +{{{#!bat @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2" }}} @@ -135,12 +132,30 @@ Note that calling `trac-admin` in your S See the [http://svnbook.red-bean.com/en/1.5/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook setups. -Git hooks can be used in the same way for explicit syncing of git repositories. Add the following to `.git/hooks/post-commit`: +==== Git ==== + +Git hooks can be used in the same way for explicit syncing of Git repositories. If your git repository is one that gets committed to directly on the machine that hosts trac, add the following to the `hooks/post-receive` file in your git repo (note: this will do nothing if you only update the repo by pushing to it): {{{#!sh -REV=$(git rev-parse HEAD) -trac-admin /path/to/env changeset added <my-repository> $REV +#!/bin/sh +REV=$(git rev-parse HEAD) +trac-admin /path/to/env changeset added <repos> $REV }}} +Alternately, if your repository is one that only gets pushed to, add the following to the `hooks/post-receive` file in the repo: +{{{#!sh +#!/bin/sh +while read oldrev newrev refname; do + git rev-list --reverse $newrev ^$oldrev | \ + while read rev; do + trac-admin /path/to/env changeset added <repos> $rev + done +done +}}} + +The `<repos>` argument can be either a repository name (use "`(default)`" for the default repository) or the path to the repository. + +==== Mercurial ==== + For Mercurial, add the following entries to the `.hgrc` file of each repository accessed by Trac (if [trac:TracMercurial] is installed in a Trac `plugins` directory, download [trac:source:mercurial-plugin/tracext/hg/hooks.py hooks.py] and place it somewhere accessible): {{{#!ini [hooks] Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSearch URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSearch?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSearch (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSearch Sat Nov 15 01:14:46 2014 @@ -16,7 +16,8 @@ For example: * ![42] -- Opens change set 42 * !#42 -- Opens ticket number 42 * !{1} -- Opens report 1 - * /trunk -- Opens the browser for the `trunk` directory + * /trunk -- Opens the browser for the `trunk` directory in the default repository + * /repos1/trunk -- Opens the browser for the `trunk` directory in the `repos1` repository == Advanced == Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracStandalone URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracStandalone?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracStandalone (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracStandalone Sat Nov 15 01:14:46 2014 @@ -13,7 +13,7 @@ It can be used in a variety of situation * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd. * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead, - or [http://trac.edgewall.org/wiki/STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy. + or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy. == Usage examples == @@ -21,7 +21,7 @@ A single project on port 8080. (http://l {{{ $ tracd -p 8080 /path/to/project }}} -Stricly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option. +Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option. {{{ $ tracd --hostname=localhost -p 8080 /path/to/project }}} @@ -95,6 +95,8 @@ $ net start tracd Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives) +Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like `ext2` or `ext3` on Linux) may go undetected. + Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line. The general format for using authentication is: Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSyntaxColoring URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSyntaxColoring?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSyntaxColoring (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracSyntaxColoring Sat Nov 15 01:14:46 2014 @@ -6,8 +6,8 @@ To do this, Trac uses external libraries Currently Trac supports syntax coloring using one or more of the following packages: * [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 - * [http://www.codento.com/people/mtr/genscript/ GNU Enscript], commonly available on Unix but somewhat unsupported on Windows - * [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] + * [http://www.codento.com/people/mtr/genscript/ GNU Enscript], commonly available on Unix but somewhat unsupported on Windows //(use is deprecated)// + * [http://silvercity.sourceforge.net/ SilverCity], legacy system, some versions can be problematic //(use is deprecated)// To activate syntax coloring, simply install either one (or more) of these packages (see [#ExtraSoftware] section below). @@ -16,7 +16,7 @@ If none of these packages is available, === About Pygments === -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]. +Since Trac 0.11 [http://pygments.org/ pygments] is 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]. 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]. @@ -35,7 +35,7 @@ In a similar way, a document with the mi 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. -If mimetype such as 'svn:mime-type' is set to 'text/plain', there is no coloring even if file is known type like 'java'. +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'. === List of Languages Supported, by Highlighter #language-supported Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTickets URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTickets?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTickets (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTickets Sat Nov 15 01:14:46 2014 @@ -27,7 +27,7 @@ A ticket contains the following informa * '''Assigned to/Owner''' â Principal person responsible for handling the issue. * '''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.'' * '''Resolution''' â Reason for why a ticket was closed. One of {{{fixed}}}, {{{invalid}}}, {{{wontfix}}}, {{{duplicate}}}, {{{worksforme}}}. - * '''Status''' â What is the current status? One of {{{new}}}, {{{assigned}}}, {{{closed}}}, {{{reopened}}}. + * '''Status''' â What is the current status? One of {{{new}}}, {{{assigned}}}, {{{accepted}}}, {{{closed}}}, {{{reopened}}}. * '''Summary''' â A brief description summarizing the problem or issue. Simple text without WikiFormatting. * '''Description''' â The body of the ticket. A good description should be specific, descriptive and to the point. Accepts WikiFormatting. Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTicketsCustomFields URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTicketsCustomFields?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTicketsCustomFields (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracTicketsCustomFields Sat Nov 15 01:14:46 2014 @@ -39,11 +39,13 @@ The example below should help to explain * '''textarea''': Multi-line text area. * label: Descriptive label. * value: Default text. - * cols: Width in columns. + * cols: Width in columns * rows: Height in lines. * order: Sort order placement. * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting. (''since 0.11.3'') +Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`. + === Sample Config === {{{ [ticket-custom] @@ -113,6 +115,14 @@ SELECT p.value AS __color__, Note in particular the `LEFT OUTER JOIN` statement here. +Note that if your config file uses an uppercase name, e.g., +{{{ +[ticket-custom] + +Progress_Type = text +}}} +you would use lowercase in the SQL: `AND c.name = 'progress_type'` + === Updating the database === 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: Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracUpgrade URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracUpgrade?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracUpgrade (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracUpgrade Sat Nov 15 01:14:46 2014 @@ -14,10 +14,10 @@ It is not a good idea to update a runnin Get the new version as described in TracInstall, or your operating system specific procedure. -If you already have a 0.11 version of Trac installed via `easy_install`, it might be easiest to also use `easy_install` to upgrade your Trac installation: +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: {{{ -# easy_install --upgrade Trac==0.12 +# easy_install --upgrade Trac==1.0 }}} If you do a manual (not operating system-specific) upgrade, you should also stop any running Trac servers before the installation. Doing "hot" upgrades is not advised, especially on Windows ([trac:#7265]). @@ -73,8 +73,13 @@ Remove above note once #9936 is fixed. }}} === 6. Steps specific to a given Trac version === + ==== Upgrading from Trac 0.12 to Trac 1.0 ==== #to1.0 +===== Python 2.4 no longer supported ===== +The minimum supported version of python is now 2.5 + +===== Subversion components not enabled by default for new installations 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: {{{ [components] @@ -82,8 +87,13 @@ tracopt.versioncontrol.svn.* = enabled }}} The upgrade procedure should take care of this and change the TracIni appropriately, unless you already had the svn components explicitly disabled. + +===== Attachments migrated to new location 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. +===== Behavior of `[ticket] default_owner` changed +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. + ==== Upgrading from Trac 0.11 to Trac 0.12 ==== @@ -103,7 +113,7 @@ This may be of interest to users with on ===== Resynchronize the Trac Environment Against the Source Code Repository ===== -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: +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: {{{ trac-admin /path/to/projenv repository resync '*' @@ -182,9 +192,8 @@ Upgrading Python to a newer version will 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. === Changing Database Backend === -==== SQLite to PostgreSQL ==== -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 +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. === Upgrading from older versions of Trac === #OlderVersions Modified: bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracWiki URL: http://svn.apache.org/viewvc/bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracWiki?rev=1639823&r1=1639822&r2=1639823&view=diff ============================================================================== --- bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracWiki (original) +++ bloodhound/branches/trac-1.0.2-integration/trac/trac/wiki/default-pages/TracWiki Sat Nov 15 01:14:46 2014 @@ -14,7 +14,7 @@ As contributing to a wiki is essentially general advice regarding HTML authoring apply here as well. For example, the ''[http://www.w3.org/Provider/Style Style Guide for online hypertext]'' explains how to think about the [http://www.w3.org/Provider/Style/Structure.html overall structure of a work] -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.â +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.â Learn more about: * WikiFormatting rules, including advanced topics like WikiMacros and WikiProcessors
