| 1 | = Installing Trac as CGI = |
| 2 | |
| 3 | {{{ |
| 4 | #!div class=important |
| 5 | ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.'' |
| 6 | }}} |
| 7 | |
| 8 | CGI script is the entrypoint that web-server calls when a web-request to an application is made. To generate the `trac.cgi` script run: |
| 9 | {{{ |
| 10 | trac-admin /path/to/env deploy /path/to/www/trac |
| 11 | }}} |
| 12 | `trac.cgi` will be in the `cgi-bin` folder inside the given path. Make sure it is executable by your web server. This command also copies `static resource` files to a `htdocs` directory of a given destination. |
| 13 | |
| 14 | == Apache web-server configuration == |
| 15 | |
| 16 | In [http://httpd.apache.org/ Apache] there are two ways to run Trac as CGI: |
| 17 | |
| 18 | 1. Use a `ScriptAlias` directive that maps an URL to the `trac.cgi` script (recommended) |
| 19 | 2. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory. |
| 20 | |
| 21 | To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation: |
| 22 | {{{ |
| 23 | ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi |
| 24 | }}} |
| 25 | |
| 26 | ''Note that this directive requires enabled `mod_alias` module.'' |
| 27 | |
| 28 | If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable: |
| 29 | {{{ |
| 30 | <Location "/trac"> |
| 31 | SetEnv TRAC_ENV "/path/to/projectenv" |
| 32 | </Location> |
| 33 | }}} |
| 34 | |
| 35 | Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable: |
| 36 | {{{ |
| 37 | <Location "/trac"> |
| 38 | SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir" |
| 39 | </Location> |
| 40 | }}} |
| 41 | |
| 42 | ''Note that the `SetEnv` directive requires enabled `mod_env` module. It is also possible to set TRAC_ENV in trac.cgi. Just add the following code between "try:" and "from trac.web ...":'' |
| 43 | |
| 44 | {{{ |
| 45 | import os |
| 46 | os.environ['TRAC_ENV'] = "/path/to/projectenv" |
| 47 | }}} |
| 48 | |
| 49 | '' Or for TRAC_ENV_PARENT_DIR: '' |
| 50 | |
| 51 | {{{ |
| 52 | import os |
| 53 | os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir" |
| 54 | }}} |
| 55 | |
| 56 | If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [http://trac.edgewall.org/wiki/ApacheSuexec]. |
| 57 | |
| 58 | On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a .cgi file (Explorer -> Tools -> Folder Options -> File Types -> CGI). |
| 59 | |
| 60 | == Mapping Static Resources == |
| 61 | |
| 62 | Out of the box, Trac will pass static resources such as style sheets or images through itself. For a CGI setup this is '''highly undesirable''', because this way CGI script is invoked for documents that could be much more efficiently served directly by web server. |
| 63 | |
| 64 | Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We already used this capability by defining a `ScriptAlias` for the CGI script. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by CGI script. |
| 65 | |
| 66 | There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources usually accessible by `/chrome/plugin` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything. |
| 67 | |
| 68 | Add the following snippet to Apache configuration '''before''' the `ScriptAlias` for the CGI script, changing paths to match your deployment: |
| 69 | {{{ |
| 70 | Alias /trac/chrome/common /path/to/trac/htdocs/common |
| 71 | Alias /trac/chrome/site /path/to/trac/htdocs/site |
| 72 | <Directory "/path/to/www/trac/htdocs"> |
| 73 | Order allow,deny |
| 74 | Allow from all |
| 75 | </Directory> |
| 76 | }}} |
| 77 | |
| 78 | If using mod_python, you might want to add this too (otherwise, the alias will be ignored): |
| 79 | {{{ |
| 80 | <Location "/trac/chrome/common/"> |
| 81 | SetHandler None |
| 82 | </Location> |
| 83 | }}} |
| 84 | |
| 85 | Note that we mapped `/trac` part of the URL to the `trac.cgi` script, and the path `/chrome/common` is the path you have to append to that location to intercept requests to the static resources. |
| 86 | |
| 87 | For example, if Trac is mapped to `/cgi-bin/trac.cgi` on your server, the URL of the Alias should be `/cgi-bin/trac.cgi/chrome/common`. |
| 88 | |
| 89 | Similarly, if you have static resources in a project's htdocs directory (which is referenced by /chrome/site URL in themes), you can configure Apache to serve those resources (again, put this '''before''' the `ScriptAlias` for the CGI script, and adjust names and locations to match your installation): |
| 90 | |
| 91 | {{{ |
| 92 | Alias /trac/chrome/site /path/to/projectenv/htdocs |
| 93 | <Directory "/path/to/projectenv/htdocs"> |
| 94 | Order allow,deny |
| 95 | Allow from all |
| 96 | </Directory> |
| 97 | }}} |
| 98 | |
| 99 | Alternatively to hacking `/trac/chrome/site`, you can directly specify path to static resources using `htdocs_location` configuration option in [wiki:TracIni trac.ini]: |
| 100 | {{{ |
| 101 | [trac] |
| 102 | htdocs_location = http://yourhost.example.org/trac-htdocs |
| 103 | }}} |
| 104 | |
| 105 | Trac will then use this URL when embedding static resources into HTML pages. Of course, you still need to make the Trac `htdocs` 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: |
| 106 | {{{ |
| 107 | $ ln -s /path/to/www/trac/htdocs /var/www/yourhost.example.org/trac-htdocs |
| 108 | }}} |
| 109 | |
| 110 | Note that in order to get this `htdocs` directory, you need first to extract the relevant Trac resources using the `deploy` command of TracAdmin: |
| 111 | [[TracAdminHelp(deploy)]] |
| 112 | |
| 113 | |
| 114 | == Adding Authentication == |
| 115 | |
| 116 | The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file: |
| 117 | {{{ |
| 118 | $ htpasswd -c /somewhere/trac.htpasswd admin |
| 119 | New password: <type password> |
| 120 | Re-type new password: <type password again> |
| 121 | Adding password for user admin |
| 122 | }}} |
| 123 | |
| 124 | After the first user, you dont need the "-c" option anymore: |
| 125 | {{{ |
| 126 | $ htpasswd /somewhere/trac.htpasswd john |
| 127 | New password: <type password> |
| 128 | Re-type new password: <type password again> |
| 129 | Adding password for user john |
| 130 | }}} |
| 131 | |
| 132 | ''See the man page for `htpasswd` for full documentation.'' |
| 133 | |
| 134 | After you've created the users, you can set their permissions using TracPermissions. |
| 135 | |
| 136 | Now, you'll need to enable authentication against the password file in the Apache configuration: |
| 137 | {{{ |
| 138 | <Location "/trac/login"> |
| 139 | AuthType Basic |
| 140 | AuthName "Trac" |
| 141 | AuthUserFile /somewhere/trac.htpasswd |
| 142 | Require valid-user |
| 143 | </Location> |
| 144 | }}} |
| 145 | |
| 146 | If you're hosting multiple projects you can use the same password file for all of them: |
| 147 | {{{ |
| 148 | <LocationMatch "/trac/[^/]+/login"> |
| 149 | AuthType Basic |
| 150 | AuthName "Trac" |
| 151 | AuthUserFile /somewhere/trac.htpasswd |
| 152 | Require valid-user |
| 153 | </LocationMatch> |
| 154 | }}} |
| 155 | |
| 156 | For better security, it is recommended that you either enable SSL or at least use the “digest” authentication scheme instead of “Basic”. Please read the [http://httpd.apache.org/docs/2.0/ Apache HTTPD documentation] to find out more. For example, on a Debian 4.0r1 (etch) system the relevant section in apache configuration can look like this: |
| 157 | {{{ |
| 158 | <Location "/trac/login"> |
| 159 | LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so |
| 160 | AuthType Digest |
| 161 | AuthName "trac" |
| 162 | AuthDigestDomain /trac |
| 163 | AuthUserFile /somewhere/trac.htpasswd |
| 164 | Require valid-user |
| 165 | </Location> |
| 166 | }}} |
| 167 | and you'll have to create your .htpasswd file with htdigest instead of htpasswd as follows: |
| 168 | {{{ |
| 169 | # htdigest /somewhere/trac.htpasswd trac admin |
| 170 | }}} |
| 171 | where the "trac" parameter above is the same as !AuthName above ("Realm" in apache-docs). |
| 172 | |
| 173 | ---- |
| 174 | See also: TracGuide, TracInstall, [wiki:TracModWSGI], TracFastCgi, TracModPython |