Context Navigation

Changes between Version 5 and Version 6 of TracInstall

Timestamp:: Sep 21, 2017, 3:39:12 PM (7 years ago)
Author:: trac
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

TracInstall

-              v5
+              v6
+= Trac Installation Guide for 1.0
+= Trac Installation Guide for 1.2
 [[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 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.
+Trac can also be localized, and there is probably a translation available in your language. If you want to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version.
 If you're interested in contributing new translations for other languages or enhancing the existing translations, then please have a look at [trac:wiki:TracL10N TracL10N].
 What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please '''first read through these general instructions''' to get a good understanding of the tasks involved.
+What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms], please '''first read through these general instructions''' to get a good understanding of the tasks involved.
 [[PageOutline(2-3,Installation Steps,inline)]]
 == Dependencies
 === Mandatory Dependencies
 To install Trac, the following software packages must be installed:
  * [http://www.python.org/ Python], version >= 2.5 and < 3.0
    (note that we dropped the support for Python 2.4 in this release)
+ * [http://www.python.org/ Python], version >= 2.6 and < 3.0
+   (note that we dropped the support for Python 2.5 in this release)
  * [http://pypi.python.org/pypi/setuptools setuptools], version >= 0.6
  * [http://genshi.edgewall.org/wiki/Download Genshi], version >= 0.6
 …
 ==== For the SQLite database #ForSQLite
 As you must be using Python 2.5, 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python: the `sqlite3` module.
+As you must be using Python 2.6 or 2.7, you already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module).
 Optionally, you may install a newer version of [http://pypi.python.org/pypi/pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details.
 …
 Trac works well with MySQL, provided you follow the guidelines:
  * [http://mysql.com/ MySQL] or [http://mariadb.org/ MariaDB], version 5.0 or later
+ * [http://mysql.com/ MySQL], version 5.0 or later
  * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later
 Given the caveats and known issues surrounding MySQL, read the [trac:MySqlDb] page before creating the database.
+Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database.
 === Optional Dependencies
+==== Version Control System
+===== Subversion
+ * [http://subversion.apache.org/ Subversion], 1.5.x or 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.
+==== Subversion
+[http://subversion.apache.org/ Subversion], 1.6.x or later and the '''''corresponding''''' Python bindings.
 There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. [trac:TracSubversion] points you to [http://alagazam.net Alagazam], which works for me under Python 2.6.)
+Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings.
+'''Note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
+===== Git
+ * [http://git-scm.com/ Git] 1.5.6 or later.
+More information is available on the [trac:TracGit] page.
+===== Others
+Support for other version control systems is provided via third-parties. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem].
+For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page.
+{{{#!div style="border: 1pt dotted; margin: 1em"
+**Note:**
+* Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer `ctype`-style bindings.
+* If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
+}}}
+==== Git
+[http://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page.
+==== Other Version Control Systems
+Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem].
 ==== Web Server
+A web server is optional because Trac has a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
+A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
 Alternatively you can configure Trac to run in any of the following environments:
  * [http://httpd.apache.org/ Apache] with
+   - [http://code.google.com/p/modwsgi/ mod_wsgi], see [wiki:TracModWSGI] and
+     http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac
+   - [http://modpython.org/ mod_python 3.5.0], see TracModPython
+  * [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac].
+  * [http://modpython.org/ mod_python 3.5.0], see TracModPython
  * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi)
  * an [http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
    server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp])
  * a FastCGI and FastCGI-to-WSGI gateway (see [trac:TracOnWindowsIisWfastcgi])
  * a CGI-capable web server (see TracCgi), but //usage of Trac as a cgi script
    is highly discouraged//, better use one of the previous options.
+ * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI])
+ * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script
+   is highly discouraged''', better use one of the previous options.
 ==== Other Python Packages
  * [http://babel.edgewall.org Babel], version 0.9.5, 0.9.6 or >= 1.3
+ * [http://babel.edgewall.org Babel], version 0.9.6 or >= 1.3,
    needed for localization support
  * [http://docutils.sourceforge.net/ docutils], version >= 0.3.9
 …
  * [http://pygments.org Pygments] for
    [TracSyntaxColoring syntax highlighting].
-   [http://silvercity.sourceforge.net/ SilverCity] and/or
-   [http://gnu.org/software/enscript/enscript.html Enscript] may still be used
-   but are deprecated and you really should be using Pygments.
  * [http://pytz.sf.net pytz] to get a complete list of time zones,
    otherwise Trac will fall back on a shorter list from
 …
 }}}
 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.
+Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''.
 == Installing Trac
 …
 The [TracAdmin trac-admin] command-line tool, used to create and maintain [TracEnvironment project environments], as well as the [TracStandalone tracd] standalone server are installed along with Trac. There are several methods for installing Trac.
 It is assumed throughout this guide that you have elevated permissions as the `root` user, or by prefixing commands with `sudo`. The umask `0022` should be used for a typical installation on a Unix-based platform.
+It is assumed throughout this guide that you have elevated permissions as the `root` user or by prefixing commands with `sudo`. The umask `0002` should be used for a typical installation on a Unix-based platform.
 === Using `easy_install`
+Trac can be installed from [https://pypi.python.org/pypi/Trac PyPI] or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools].
+A few command-line examples:
+Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools].
+A few examples:
  - Install the latest stable version of Trac:
 …
 }}}
    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.
+   either use a released version or install from source
 More information can be found on the [trac:wiki:setuptools setuptools] page.
 …
 === Using `pip`
+'pip' is an easy_install replacement that is very useful to quickly install Python packages.
+'pip' is an easy_install replacement that is very useful to quickly install python packages.
 To get a Trac installation up and running in less than 5 minutes:
+Assuming you want to have your entire pip installation in `/opt/user/trac`:
+ -
+Assuming you want to have your entire pip installation in `/opt/user/trac`
  {{{#!sh
 $ pip install trac psycopg2
 }}}
+or:
+ -
+or
  {{{#!sh
 $ pip install trac mysql-python
 …
 pip will automatically resolve all dependencies (like Genshi, pygments, etc.), download the latest packages from pypi.python.org and create a self contained installation in `/opt/user/trac`.
 All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive).
+All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive)
 Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip.
 === From source
 Using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. `Trac-1.0.tar.gz`) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details.
 …
 }}}
+You will need root permissions or equivalent for this step.
+''You will need root permissions or equivalent for this step.''
 This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory
 …
 $ python ./setup.py install
 }}}
 Alternatively, you can run `bdist_egg` and copy the .egg from `dist/` to the place of your choice, or you can create a Windows installer (`bdist_wininst`).
 === Using installer
 On Windows Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32 and 64 bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation.
+On Windows, Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32-bit and 64-bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation.
 === Using package manager
 Trac may be available in the package repository for your platform. Note however, that the version provided by the package manager may not be the latest release.
+Trac may be available in your platform's package repository. Note however, that the version provided by your package manager may not be the latest release.
 === Advanced `easy_install` Options
 …
 $ easy_install --prefix=/path/to/installdir
 }}}
 or, if installing Trac on a Mac OS X system:
 {{{#!sh
+$ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.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.5/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.
+$ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages
+}}}
+{{{#!div style="border: 1pt dotted; margin: 1em"
+**Mac OS X Note:** On Mac OS X 10.6,  running `easy_install trac` will install into `/usr/local` and `/Library/Python/2.6/site-packages` by default.
+The `tracd` and `trac-admin` commands will be placed in `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.6/site-packages`, which is Apple's preferred location for third-party Python application installations.
+}}}
 == Creating a Project Environment
 A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable [TracIni configuration file], and other files and directories.
+A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is a directory that contains a human-readable [TracIni configuration file], and other files and directories.
 A new environment is created using [TracAdmin trac-admin]:
 …
 }}}
+[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.
+Using the default database connection string in particular 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.
+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.
+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.
+Using the default database connection string will always work as long as you have SQLite installed. For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point.
+Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file.
 {{{#!div style="border: 1pt dotted; margin: 1em"
 …
 Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter:
 {{{#!sh
 $ chown -R apache.apache /path/to/myproject
 }}}
 The actual username and groupname of the Apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).
+$ 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
 …
  - [wiki:TracModWSGI Apache with mod_wsgi]
  - [TracModPython Apache with mod_python]
  - //[TracCgi CGI]: should not be used, as it degrades performance//
+ - [TracCgi CGI] //(should not be used, as the performance is far from optimal)//
 Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.
 …
 ==== Generating the Trac cgi-bin directory #cgi-bin
+In order for Trac to function properly with FastCGI you need to have a `trac.fcgi` file and for mod_wsgi a `trac.wsgi` file. These are Python scripts which load the appropriate Python code. They can be generated using the `deploy` option of [TracAdmin trac-admin].
+There is, however, a bit of a chicken-and-egg problem. The [TracAdmin trac-admin] command requires an existing environment to function, but complains if the deploy directory already exists. This is a problem, because environments are often stored in a subdirectory of the deploy. The solution is to do something like this:
+{{{#!sh
+$ mkdir -p /usr/share/trac/projects/my-project
+$ trac-admin /usr/share/trac/projects/my-project initenv
+$ trac-admin /usr/share/trac/projects/my-project deploy /tmp/deploy
+$ mv /tmp/deploy/* /usr/share/trac
+}}}
+Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory.
+Application scripts for CGI, FastCGI and mod-wsgi can be generated using the [TracAdmin trac-admin] `deploy` command:
+[[TracAdminHelp(deploy)]]
+Grant the web server execution right on scripts in the `cgi-bin` directory.
+For example, the following yields a typical directory structure:
+{{{#!sh
+$ mkdir -p /var/trac
+$ trac-admin /var/trac/<project> initenv
+$ trac-admin /var/trac/<project> deploy /var/www
+$ ls /var/www
+cgi-bin htdocs
+$ chmod ugo+x /var/www/cgi-bin/*
+}}}
 ==== Mapping Static Resources
 …
 There are two primary URL paths for static resources: `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible at the `/chrome/<plugin>` path.
+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.
+The resources are extracted using the [TracAdmin trac-admin]` <environment> deploy` command:
+[[TracAdminHelp(deploy)]]
+The target `<directory>` will contain an `htdocs` directory with:
+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.
+The `deploy` command creates an `htdocs` directory with:
  - `common/` - the static resources of Trac
  - `site/` - a copy of the environment's `htdocs/` directory
 …
 Assuming the deployment has been done this way:
 {{{#!sh
 $ trac-admin /var/trac/env deploy /path/to/shared/trac
+$ trac-admin /var/trac/<project> deploy /var/www
 }}}
 …
 }}}
 Another alternative to aliasing `/trac/chrome/common` is having Trac generate direct links for those static resources (and only those), using the [[TracIni#trac-section| [trac] htdocs_location]] configuration setting:
+Another alternative to aliasing `/trac/chrome/common` is having Trac generate direct links for those static resources (and only those), using the [TracIni#trac-section htdocs_location] configuration setting:
 {{{#!ini
 [trac]
 …
 }}}
 ==== Setting up the Plugin Cache
+==== Setting up the Plugin Cache #egg-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.
+If you setup hook scripts that call Trac, such as the Subversion post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts as well.
 == Configuring Authentication
 …
 Please refer to one of the following sections:
  * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
  * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi` of course, but the same instructions applies also for `mod_python`, `mod_fcgi` or `mod_fastcgi`.
  * TracFastCgi if you are using another web server with FCGI support, such as Cherokee, Lighttpd, !LiteSpeed, nginx.
 The following document also contains some useful information for beginners: [trac:TracAuthenticationIntroduction].
+ * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi`, `mod_python`, `mod_fcgi` or `mod_fastcgi`.
+ * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)
+[trac:TracAuthenticationIntroduction] also contains some useful information for beginners.
 == Granting admin rights to the admin user
 Grant admin rights to user admin:
 {{{#!sh
 …
 }}}
+This user will have an "Admin" entry menu that will allow you to administrate your Trac project.
+== Finishing the install
+=== 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 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:
+{{{#!ini
+[components]
+tracopt.versioncontrol.svn.* = enabled
+}}}
+{{{#!ini
+[components]
+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 changeset references can be inserted as ticket comments by configuring [TracRepositoryAdmin#Automaticchangesetreferencesintickets CommitTicketUpdater].
+=== Using Trac
+This user will have an //Admin// navigation item that directs to pages for administering your Trac project.
+== Configuring Trac
+TracRepositoryAdmin provides information on configuring version control repositories for your project.
+== Using Trac
 Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.