Changes between Version 4 and Version 5 of TracInstall

Timestamp:

2019-07-17T11:42:42-03:00 (5 years ago)

Author:

trac

Comment:

--

TracInstall

@@ -1 @@
-= Trac Installation Guide for 1.1
+= Trac Installation Guide for 1.2
 [[TracGuideToc]]
 
@@ -75 +75 @@
 Alternatively you can configure Trac to run in any of the following environments:
  * [http://httpd.apache.org/ Apache] with 
-   - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and 
-     [http://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac].
-   - [http://modpython.org/ mod_python 3.5.0], see TracModPython
+  * [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
@@ -138 +137 @@
 Assuming you want to have your entire pip installation in `/opt/user/trac`
 
- - 
  {{{#!sh
-pip install trac psycopg2 
+$ pip install trac psycopg2 
 }}}
 or
- - 
  {{{#!sh
-pip install trac mysql-python 
+$ pip install trac mysql-python 
 }}}
 
@@ -186 +183 @@
 To install Trac to a custom location, or find out about other advanced installation options, run:
 {{{#!sh
-easy_install --help
+$ easy_install --help
 }}}
 
@@ -193 +190 @@
 Specifically, you might be interested in:
 {{{#!sh
-easy_install --prefix=/path/to/installdir
+$ easy_install --prefix=/path/to/installdir
 }}}
 or, if installing Trac on a Mac OS X system:
 {{{#!sh
-easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages
+$ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.6/site-packages
 }}}
 
@@ -215 +212 @@
 }}}
 
-[TracAdmin trac-admin] will prompt you for the information it needs to create the environment: the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for any of these options, just press `<Enter>` to use the default value. 
+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.
@@ -274 +271 @@
  - [wiki:TracModWSGI Apache with mod_wsgi] 
  - [TracModPython Apache with mod_python]
- - //[TracCgi CGI] (should not be used, as the performance is far from optimal)//
+ - [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.
@@ -280 +277 @@
 ==== 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
@@ -299 +300 @@
 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
@@ -322 +320 @@
 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
 }}}
 
@@ -366 +364 @@
 }}}
 
-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]
@@ -379 +377 @@
 }}}
 
-==== 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