| 5 | | 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. |
| 6 | | |
| 7 | | Since version 0.12, 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. |
| | 4 | Trac is written in the Python programming language and needs a database, [https://sqlite.org/ SQLite], [https://www.postgresql.org/ PostgreSQL], or [https://www.mysql.com/ MySQL]. For HTML rendering, Trac uses the [https://genshi.edgewall.org/ Genshi] templating system. |
| | 5 | |
| | 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. |
| 21 | | * [http://www.python.org/ Python], version >= 2.5 and < 3.0 |
| 22 | | (note that we dropped the support for Python 2.4 in this release) |
| 23 | | * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6 |
| 24 | | * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6 |
| | 18 | * [https://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 | * [https://pypi.org/project/setuptools setuptools], version >= 0.6 |
| | 21 | * [https://pypi.org/project/Genshi Genshi], version >= 0.6 |
| 30 | | 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. |
| 31 | | |
| 32 | | Optionally, you may install a newer version of [http://pypi.python.org/pypi/pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details. |
| | 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 [https://pypi.org/project/pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details. |
| 46 | | * [http://mysql.com/ MySQL] or [http://mariadb.org/ MariaDB], version 5.0 or later |
| 47 | | * [http |
| 48 | | |
| 49 | | Given the caveats and known issues surrounding MySQL, read |
| | 43 | * [https://www.mysql.com/ MySQL], version 5.0 or later |
| | 44 | * [https://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later |
| | 45 | |
| | 46 | Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database. |
| 53 | | ==== Version Control System |
| 54 | | |
| 55 | | ===== Subversion |
| 56 | | * [http://subversion.apache.org/ Subversion], 1.5.x or later and the '''corresponding''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. may still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page. |
| 57 | | |
| 58 | | 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.) |
| 59 | | |
| 60 | | Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings. |
| 61 | | |
| 62 | | '''Note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported]. |
| 63 | | |
| 64 | | ===== Git |
| 65 | | * [http://git-scm.com/ Git] 1.5.6 or later. |
| 66 | | |
| 67 | | More information is available on the [trac:TracGit] page. |
| 68 | | |
| 69 | | ===== Others |
| 70 | | |
| 71 | | Support for other version control systems is provided via third-parties. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem]. |
| | 50 | ==== Subversion |
| | 51 | |
| | 52 | [https://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings. |
| | 53 | |
| | 54 | There are [https://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 [https://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 | [https://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]. |
| 78 | | * [http://httpd.apache.org/ Apache] with |
| 79 | | - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and |
| 80 | | http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac |
| 81 | | - [http://modpython.org/ mod_python 3.5.0], see TracModPython |
| 82 | | * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi) |
| 83 | | * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web |
| | 76 | * [https://httpd.apache.org/ Apache] with |
| | 77 | * [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and [https://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac]. |
| | 78 | * [http://modpython.org/ mod_python 3.5.0], see TracModPython |
| | 79 | * a [https://fastcgi-archives.github.io/ FastCGI]-capable web server (see TracFastCgi) |
| | 80 | * an [https://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web |
| 85 | | * a FastCGI and FastCGI-to-WSGI gateway (see [trac:TracOnWindowsIisWfastcgi]) |
| 86 | | * a CGI-capable web server (see TracCgi), but //usage of Trac as a cgi script |
| 87 | | is highly discouraged//, better use one of the previous options. |
| | 82 | * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI]) |
| | 83 | * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script |
| | 84 | is highly discouraged''', better use one of the previous options. |
| 208 | | $ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages |
| 209 | | }}} |
| 210 | | |
| 211 | | '''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.5/site-packages }}} by default. |
| 212 | | |
| 213 | | 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. |
| | 196 | $ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages |
| | 197 | }}} |
| | 198 | |
| | 199 | {{{#!div style="border: 1pt dotted; margin: 1em" |
| | 200 | **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. |
| | 201 | |
| | 202 | 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. |
| | 203 | }}} |
| 224 | | [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. |
| 225 | | |
| 226 | | Using the default database connection string in particular will always work as long as you have SQLite installed. |
| 227 | | For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point. |
| 228 | | |
| 229 | | 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. |
| 230 | | |
| 231 | | Also note that the values you specify here can be changed later by directly editing the [TracIni conf/trac.ini] configuration file. |
| | 214 | You will be prompted for the information needed 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. |
| | 215 | |
| | 216 | 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. |
| | 217 | |
| | 218 | Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file. |
| 286 | | - //[TracCgi CGI]: should not be used, as it degrades performance// |
| 287 | | |
| 288 | | 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. |
| | 273 | - [TracCgi CGI] //(should not be used, as the performance is far from optimal)// |
| | 274 | |
| | 275 | 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], [https://uwsgi-docs.readthedocs.io/en/latest/#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc. |
| 292 | | 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]. |
| 293 | | |
| 294 | | 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: |
| 295 | | {{{#!sh |
| 296 | | $ mkdir -p /usr/share/trac/projects/my-project |
| 297 | | $ trac-admin /usr/share/trac/projects/my-project initenv |
| 298 | | $ trac-admin /usr/share/trac/projects/my-project deploy /tmp/deploy |
| 299 | | $ mv /tmp/deploy/* /usr/share/trac |
| 300 | | }}} |
| 301 | | |
| 302 | | Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory. |
| | 279 | Application scripts for CGI, FastCGI and mod-wsgi can be generated using the [TracAdmin trac-admin] `deploy` command: |
| | 280 | [[TracAdminHelp(deploy)]] |
| | 281 | |
| | 282 | Grant the web server execution right on scripts in the `cgi-bin` directory. |
| | 283 | |
| | 284 | For example, the following yields a typical directory structure: |
| | 285 | {{{#!sh |
| | 286 | $ mkdir -p /var/trac |
| | 287 | $ trac-admin /var/trac/<project> initenv |
| | 288 | $ trac-admin /var/trac/<project> deploy /var/www |
| | 289 | $ ls /var/www |
| | 290 | cgi-bin htdocs |
| | 291 | $ chmod ugo+x /var/www/cgi-bin/* |
| | 292 | }}} |
| 312 | | A single `/chrome` alias can used if the static resources are extracted for all plugins. This means that the `deploy` command must be executed after installing or updating a plugin that provides static resources, or after modifying resources in the `$env/htdocs` directory. This is probably appropriate for most installations but may not be what you want if, for example, you wish to upload plugins through the //Plugins// administration page. |
| 313 | | |
| 314 | | The resources are extracted using the [TracAdmin trac-admin]` <environment> deploy` command: |
| 315 | | [[TracAdminHelp(deploy)]] |
| 316 | | |
| 317 | | The target `<directory>` will contain an `htdocs` directory with: |
| | 302 | A single `/chrome` alias can used if the static resources are extracted for all plugins. This means that the `deploy` command (discussed in the previous section) must be executed after installing or updating a plugin that provides static resources, or after modifying resources in the `$env/htdocs` directory. This is probably appropriate for most installations but may not be what you want if, for example, you wish to upload plugins through the //Plugins// administration page. |
| | 303 | |
| | 304 | The `deploy` command creates an `htdocs` directory with: |
| 404 | | * [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`. |
| 405 | | * TracFastCgi if you are using another web server with FCGI support, such as Cherokee, Lighttpd, !LiteSpeed, nginx. |
| 406 | | |
| 407 | | The following document also contains some useful information for beginners: [trac:TracAuthenticationIntroduction]. |
| | 393 | * [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`. |
| | 394 | * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx) |
| | 395 | |
| | 396 | [trac:TracAuthenticationIntroduction] also contains some useful information for beginners. |
| 416 | | This user will have an "Admin" entry menu that will allow you to administrate your Trac project. |
| 417 | | |
| 418 | | == Finishing the install |
| 419 | | |
| 420 | | === Enable version control components |
| 421 | | |
| 422 | | 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. |
| 423 | | |
| 424 | | The version control systems are 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: |
| 425 | | |
| 426 | | {{{#!ini |
| 427 | | [components] |
| 428 | | tracopt.versioncontrol.svn.* = enabled |
| 429 | | }}} |
| 430 | | |
| 431 | | {{{#!ini |
| 432 | | [components] |
| 433 | | tracopt.versioncontrol.git.* = enabled |
| 434 | | }}} |
| 435 | | |
| 436 | | After enabling the components, repositories can be configured through the //Repositories// admin panel or by editing [TracIni#repositories-section trac.ini]. Automatic changeset references can be inserted as ticket comments by configuring [TracRepositoryAdmin#Automaticchangesetreferencesintickets CommitTicketUpdater]. |
| 437 | | |
| 438 | | === Using Trac |
| | 404 | This user will have an //Admin// navigation item that directs to pages for administering your Trac project. |
| | 405 | |
| | 406 | == Configuring Trac |
| | 407 | |
| | 408 | TracRepositoryAdmin provides information on configuring version control repositories for your project. |
| | 409 | |
| | 410 | == Using Trac |
